聲明不屬于路徑參數(shù)的其他函數(shù)參數(shù)時(shí),它們將被自動(dòng)解釋為"查詢字符串"參數(shù)
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]
查詢字符串是鍵值對(duì)的集合,這些鍵值對(duì)位于 URL 的 ??
? 之后,并以 ?&
?符號(hào)分隔。
例如,在以下 url 中:
http://127.0.0.1:8000/items/?skip=0&limit=10
...查詢參數(shù)為:
由于它們是 URL 的一部分,因此它們的"原始值"是字符串。
但是,當(dāng)你為它們聲明了 Python 類型(在上面的示例中為 ?int
?)時(shí),它們將轉(zhuǎn)換為該類型并針對(duì)該類型進(jìn)行校驗(yàn)。
應(yīng)用于路徑參數(shù)的所有相同過程也適用于查詢參數(shù):
由于查詢參數(shù)不是路徑的固定部分,因此它們可以是可選的,并且可以有默認(rèn)值。
在上面的示例中,它們具有 skip=0 和 limit=10 的默認(rèn)值。
因此,訪問 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
函數(shù)中的參數(shù)值將會(huì)是:
通過同樣的方式,你可以將它們的默認(rèn)值設(shè)置為 ?None
?來聲明可選查詢參數(shù):
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Optional[str] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
在這個(gè)例子中,函數(shù)參數(shù) ?q
?將是可選的,并且默認(rèn)值為 ?None
?。
還要注意的是,F(xiàn)astAPI 足夠聰明,能夠分辨出參數(shù) ?
item_id
? 是路徑參數(shù)而 ?q
?不是,因此 ?q
?是一個(gè)查詢參數(shù)。
你還可以聲明 ?bool
?類型,它們將被自動(dòng)轉(zhuǎn)換:
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Optional[str] = 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
這個(gè)例子中,如果你訪問:
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
或任何其他的變體形式(大寫,首字母大寫等等),你的函數(shù)接收的 ?short
?參數(shù)都會(huì)是布爾值 ?True
?。對(duì)于值為 ?False
?的情況也是一樣的。
你可以同時(shí)聲明多個(gè)路徑參數(shù)和查詢參數(shù),FastAPI 能夠識(shí)別它們。
而且你不需要以任何特定的順序來聲明。
它們將通過名稱被檢測(cè)到:
from typing import Optional
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: Optional[str] = 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
當(dāng)你為非路徑參數(shù)聲明了默認(rèn)值時(shí)(目前而言,我們所知道的僅有查詢參數(shù)),則該參數(shù)不是必需的。
如果你不想添加一個(gè)特定的值,而只是想使該參數(shù)成為可選的,則將默認(rèn)值設(shè)置為 ?None
?。
但當(dāng)你想讓一個(gè)查詢參數(shù)成為必需的,不聲明任何默認(rèn)值就可以:
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
這里的查詢參數(shù) ?needy
?是類型為 ?str
? 的必需查詢參數(shù)。
如果你在瀏覽器中打開一個(gè)像下面的 URL:
http://127.0.0.1:8000/items/foo-item
...因?yàn)闆]有添加必需的參數(shù) ?needy
?,你將看到類似以下的錯(cuò)誤:
{
"detail": [
{
"loc": [
"query",
"needy"
],
"msg": "field required",
"type": "value_error.missing"
}
]
}
由于 ?needy
?是必需參數(shù),因此你需要在 URL 中設(shè)置它的值:
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
...這樣就正常了:
{
"item_id": "foo-item",
"needy": "sooooneedy"
}
當(dāng)然,你也可以定義一些參數(shù)為必需的,一些具有默認(rèn)值,而某些則完全是可選的:
from typing import Optional
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: Optional[int] = None
):
item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
return item
在這個(gè)例子中,有3個(gè)查詢參數(shù):
Tip
你還可以像在 路徑參數(shù) 中那樣使用 Enum。
更多建議: