Sorgu Parametreleri¶
Fonksiyonda yol parametrelerinin parçası olmayan diğer tanımlamalar otomatik olarak "sorgu" parametresi olarak yorumlanır.
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]
Sorgu, bağlantıdaki ?
kısmından sonra gelen ve &
işareti ile ayrılan anahtar-değer çiftlerinin oluşturduğu bir kümedir.
Örneğin, aşağıdaki bağlantıda:
http://127.0.0.1:8000/items/?skip=0&limit=10
...sorgu parametreleri şunlardır:
skip
: değeri0
'dırlimit
: değeri10
'dır
Parametreler bağlantının bir parçası oldukları için doğal olarak string olarak değerlendirilirler.
Fakat, Python tipleri ile tanımlandıkları zaman (yukarıdaki örnekte int
oldukları gibi), parametreler o tiplere dönüştürülür ve o tipler çerçevesinde doğrulanırlar.
Yol parametreleri için geçerli olan her türlü işlem aynı şekilde sorgu parametreleri için de geçerlidir:
- Editör desteği (şüphesiz)
- Veri "ayrıştırma"
- Veri doğrulama
- Otomatik dokümantasyon
Varsayılanlar¶
Sorgu parametreleri, adres yolunun sabit bir parçası olmadıklarından dolayı isteğe bağlı ve varsayılan değere sahip olabilirler.
Yukarıdaki örnekte skip=0
ve limit=10
varsayılan değere sahiplerdir.
Yani, aşağıdaki bağlantıya gitmek:
http://127.0.0.1:8000/items/
şu adrese gitmek ile aynı etkiye sahiptir:
http://127.0.0.1:8000/items/?skip=0&limit=10
Ancak, mesela şöyle bir adresi ziyaret ederseniz:
http://127.0.0.1:8000/items/?skip=20
Fonksiyonunuzdaki parametre değerleri aşağıdaki gibi olacaktır:
skip=20
: çünkü bağlantıda böyle tanımlandı.limit=10
: çünkü varsayılan değer buydu.
İsteğe Bağlı Parametreler¶
Aynı şekilde, varsayılan değerlerini None
olarak atayarak isteğe bağlı parametreler tanımlayabilirsiniz:
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}
from typing import Union
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
Bu durumda, q
fonksiyon parametresi isteğe bağlı olacak ve varsayılan değer olarak None
alacaktır.
"Ek bilgi"
Ayrıca, dikkatinizi çekerim ki; FastAPI, item_id
parametresinin bir yol parametresi olduğunu ve q
parametresinin yol değil bir sorgu parametresi olduğunu fark edecek kadar beceriklidir.
Sorgu Parametresi Tip Dönüşümü¶
Aşağıda görüldüğü gibi dönüştürülmek üzere bool
tipleri de tanımlayabilirsiniz:
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
from typing import Union
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[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
Bu durumda, eğer şu adrese giderseniz:
http://127.0.0.1:8000/items/foo?short=1
veya
http://127.0.0.1:8000/items/foo?short=True
veya
http://127.0.0.1:8000/items/foo?short=true
veya
http://127.0.0.1:8000/items/foo?short=on
veya
http://127.0.0.1:8000/items/foo?short=yes
veya adres, herhangi farklı bir harf varyasyonu içermesi durumuna rağmen (büyük harf, sadece baş harfi büyük kelime, vb.) fonksiyonunuz, bool
tipli short
parametresini True
olarak algılayacaktır. Aksi halde False
olarak algılanacaktır.
Çoklu Yol ve Sorgu Parametreleri¶
FastAPI neyin ne olduğunu ayırt edebileceğinden dolayı aynı anda birden fazla yol ve sorgu parametresi tanımlayabilirsiniz.
Ve parametreleri, herhangi bir sıraya koymanıza da gerek yoktur.
İsimlerine göre belirleneceklerdir:
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
from typing import Union
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: Union[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
Zorunlu Sorgu Parametreleri¶
Türü yol olmayan bir parametre (şu ana kadar sadece sorgu parametrelerini gördük) için varsayılan değer tanımlarsanız o parametre zorunlu olmayacaktır.
Parametre için belirli bir değer atamak istemeyip parametrenin sadece isteğe bağlı olmasını istiyorsanız değerini None
olarak atayabilirsiniz.
Fakat, bir sorgu parametresini zorunlu yapmak istiyorsanız varsayılan bir değer atamamanız yeterli olacaktır:
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
Burada needy
parametresi str
tipinden oluşan zorunlu bir sorgu parametresidir.
Eğer tarayıcınızda şu bağlantıyı:
http://127.0.0.1:8000/items/foo-item
...needy
parametresini eklemeden açarsanız şuna benzer bir hata ile karşılaşırsınız:
{
"detail": [
{
"type": "missing",
"loc": [
"query",
"needy"
],
"msg": "Field required",
"input": null,
"url": "https://errors.pydantic.dev/2.1/v/missing"
}
]
}
needy
zorunlu bir parametre olduğundan dolayı bağlantıda tanımlanması gerekir:
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
...bu iş görür:
{
"item_id": "foo-item",
"needy": "sooooneedy"
}
Ve elbette, bazı parametreleri zorunlu, bazılarını varsayılan değerli ve bazılarını tamamen opsiyonel olarak tanımlayabilirsiniz:
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
from typing import Union
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: Union[int, None] = None
):
item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
return item
Bu durumda, 3 tane sorgu parametresi var olacaktır:
needy
, zorunlu birstr
.skip
, varsayılan değeri0
olan birint
.limit
, isteğe bağlı birint
.
"İpucu"
Ayrıca, Yol Parametrelerinde de kullanıldığı şekilde Enum
sınıfından faydalanabilirsiniz.