查詢參數¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

當你宣告不是路徑參數的其他函式參數時，會自動被視為「查詢（query）」參數。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

查詢是出現在 URL 中 ? 之後的一組鍵值對，以 & 字元分隔。

例如，URL：

http://127.0.0.1:8000/items/?skip=0&limit=10

...查詢參數為：

skip：值為 0
limit：值為 10

因為它們是 URL 的一部分，天生是字串。

但當你以 Python 型別宣告它們（如上例中的 int），它們會被轉換成該型別並據此驗證。

對於查詢參數，會套用與路徑參數相同的處理流程：

編輯器支援（當然）
資料「解析」
資料驗證
自動文件

預設值¶

由於查詢參數不是路徑的固定部分，因此可以是選填並具有預設值。

在上面的例子中，預設值為 skip=0 與 limit=10。

因此，造訪下列 URL：

http://127.0.0.1:8000/items/

等同於造訪：

http://127.0.0.1:8000/items/?skip=0&limit=10

但如果你改為造訪：

http://127.0.0.1:8000/items/?skip=20

函式中的參數值會是：

skip=20：因為你在 URL 中設定了它
limit=10：因為那是預設值

選用參數¶

同樣地，你可以將預設值設為 None 來宣告選用的查詢參數：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

在這種情況下，函式參數 q 為選用，且預設為 None。

注意

另外請注意，FastAPI 能辨識出路徑參數 item_id 是路徑參數，而 q 不是，因此 q 會被當作查詢參數。

查詢參數型別轉換¶

你也可以宣告 bool 型別，值會被自動轉換：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

在這種情況下，如果你造訪：

http://127.0.0.1:8000/items/foo?short=1

或

http://127.0.0.1:8000/items/foo?short=True

或

http://127.0.0.1:8000/items/foo?short=true

或

http://127.0.0.1:8000/items/foo?short=on

或

http://127.0.0.1:8000/items/foo?short=yes

或任何其他大小寫變化（全大寫、首字母大寫等），你的函式會將參數 short 視為 bool 值 True。否則為 False。

多個路徑與查詢參數¶

你可以同時宣告多個路徑參數與查詢參數，FastAPI 會自動分辨。

而且不必按特定順序宣告。

會依名稱辨識：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: str | None = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

必填查詢參數¶

當你為非路徑參數（目前我們只看到查詢參數）宣告了預設值時，它就不是必填。

若你不想提供特定預設值、只想讓它為選填，將預設值設為 None。

但若你要讓查詢參數成為必填，只要不要宣告任何預設值：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

此處查詢參數 needy 是必填的 str。

如果你在瀏覽器中開啟如下的 URL：

http://127.0.0.1:8000/items/foo-item

...沒有加上必填的 needy 參數，你會看到類似這樣的錯誤：

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "query",
        "needy"
      ],
      "msg": "Field required",
      "input": null
    }
  ]
}

由於 needy 是必填參數，你需要在 URL 中設定它：

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

...這樣就會成功：

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

當然，你可以同時定義部分參數為必填、部分有預設值、部分為選填：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

在此例中，有 3 個查詢參數：

needy，必填的 str。
skip，具有預設值 0 的 int。
limit，選填的 int。

提示

你也可以像在路徑參數中一樣使用 Enum。