Query Parametreleri ve String Doğrulamaları¶
🌐 Yapay Zekâ ve İnsanlar Tarafından Çeviri
Bu çeviri, insanlar tarafından yönlendirilen bir yapay zekâ ile oluşturuldu. 🤝
Orijinal anlamın yanlış anlaşılması ya da kulağa doğal gelmeme gibi hatalar içerebilir. 🤖
Yapay zekâyı daha iyi yönlendirmemize yardımcı olarak bu çeviriyi iyileştirebilirsiniz.
FastAPI, parametreleriniz için ek bilgi ve doğrulamalar (validation) tanımlamanıza izin verir.
Örnek olarak şu uygulamayı ele alalım:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Union
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Query parametresi q, str | None tipindedir. Yani tipi str’dir ama None da olabilir. Nitekim varsayılan değer None olduğu için FastAPI bunun zorunlu olmadığını anlar.
Not
FastAPI, q’nun zorunlu olmadığını = None varsayılan değerinden anlar.
str | None kullanmak, editörünüzün daha iyi destek vermesini ve hataları yakalamasını sağlar.
Ek doğrulama¶
q opsiyonel olsa bile, verildiği durumda uzunluğunun 50 karakteri geçmemesini zorlayacağız.
Query ve Annotated import edin¶
Bunu yapmak için önce şunları import edin:
fastapiiçindenQuerytypingiçindenAnnotated
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Bilgi
FastAPI, 0.95.0 sürümünde Annotated desteğini ekledi (ve önermeye başladı).
Daha eski bir sürüm kullanıyorsanız Annotated kullanmaya çalışırken hata alırsınız.
Annotated kullanmadan önce FastAPI sürümünü en az 0.95.1’e yükseltmek için FastAPI sürümünü yükseltin.
q parametresinin tipinde Annotated kullanın¶
Python Types Intro içinde Annotated ile parametrelerinize metadata ekleyebileceğinizi söylemiştim, hatırlıyor musunuz?
Şimdi bunu FastAPI ile kullanmanın zamanı. 🚀
Şu tip anotasyonuna sahiptik:
q: str | None = None
q: Union[str, None] = None
Şimdi bunu Annotated ile saracağız; şöyle olacak:
q: Annotated[str | None] = None
q: Annotated[Union[str, None]] = None
Bu iki sürüm de aynı anlama gelir: q, str veya None olabilen bir parametredir ve varsayılan olarak None’dır.
Şimdi işin eğlenceli kısmına geçelim. 🎉
q parametresindeki Annotated içine Query ekleyin¶
Artık ek bilgi (bu durumda ek doğrulama) koyabildiğimiz bir Annotated’ımız olduğuna göre, Annotated içine Query ekleyin ve max_length parametresini 50 olarak ayarlayın:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Varsayılan değerin hâlâ None olduğuna dikkat edin; yani parametre hâlâ opsiyonel.
Ama şimdi Annotated içinde Query(max_length=50) kullanarak FastAPI’ye bu değer için ek doğrulama istediğimizi söylüyoruz: en fazla 50 karakter. 😎
İpucu
Burada Query() kullanıyoruz çünkü bu bir query parametresi. İleride Path(), Body(), Header() ve Cookie() gibi, Query() ile aynı argümanları kabul eden diğerlerini de göreceğiz.
FastAPI artık şunları yapacak:
- Verinin uzunluğunun en fazla 50 karakter olduğundan emin olacak şekilde doğrulayacak
- Veri geçerli değilse client için net bir hata gösterecek
- Parametreyi OpenAPI şemasındaki path operation içinde dokümante edecek (dolayısıyla otomatik dokümantasyon arayüzünde görünecek)
Alternatif (eski): Varsayılan değer olarak Query¶
FastAPI’nin önceki sürümlerinde (0.95.0 öncesi) Query’yi Annotated içine koymak yerine, parametrenizin varsayılan değeri olarak kullanmanız gerekiyordu. Etrafta bu şekilde yazılmış kod görme ihtimaliniz yüksek; bu yüzden açıklayalım.
İpucu
Yeni kodlarda ve mümkün olduğunda, yukarıda anlatıldığı gibi Annotated kullanın. Birden fazla avantajı vardır (aşağıda anlatılıyor) ve dezavantajı yoktur. 🍰
Fonksiyon parametresinin varsayılan değeri olarak Query() kullanıp max_length parametresini 50 yapmak şöyle olurdu:
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Bu senaryoda (Annotated kullanmadığımız için) fonksiyondaki None varsayılan değerini Query() ile değiştirmemiz gerekiyor. Bu durumda varsayılan değeri Query(default=None) ile vermeliyiz; bu, (en azından FastAPI açısından) aynı varsayılan değeri tanımlama amacına hizmet eder.
Yani:
q: str | None = Query(default=None)
...parametreyi None varsayılan değeriyle opsiyonel yapar; şununla aynı:
q: str | None = None
Ancak Query sürümü bunun bir query parametresi olduğunu açıkça belirtir.
Sonrasında Query’ye daha fazla parametre geçebiliriz. Bu örnekte string’ler için geçerli olan max_length:
q: str | None = Query(default=None, max_length=50)
Bu, veriyi doğrular, veri geçerli değilse net bir hata gösterir ve parametreyi OpenAPI şemasındaki path operation içinde dokümante eder.
Varsayılan değer olarak Query veya Annotated içinde Query¶
Annotated içinde Query kullanırken Query için default parametresini kullanamayacağınızı unutmayın.
Bunun yerine fonksiyon parametresinin gerçek varsayılan değerini kullanın. Aksi halde tutarsız olur.
Örneğin şu kullanım izinli değildir:
q: Annotated[str, Query(default="rick")] = "morty"
...çünkü varsayılan değerin "rick" mi "morty" mi olması gerektiği belli değildir.
Bu nedenle (tercihen) şöyle kullanırsınız:
q: Annotated[str, Query()] = "rick"
...veya eski kod tabanlarında şuna rastlarsınız:
q: str = Query(default="rick")
Annotated’ın avantajları¶
Fonksiyon parametrelerindeki varsayılan değer stiline göre Annotated kullanmanız önerilir; birden fazla nedenle daha iyidir. 🤓
Fonksiyon parametresinin varsayılan değeri, gerçek varsayılan değerdir; bu genel olarak Python açısından daha sezgiseldir. 😌
Aynı fonksiyonu FastAPI olmadan başka yerlerde de çağırabilirsiniz ve beklendiği gibi çalışır. Eğer zorunlu bir parametre varsa (varsayılan değer yoksa) editörünüz hata ile bunu belirtir; ayrıca gerekli parametreyi vermeden çalıştırırsanız Python da şikayet eder.
Annotated kullanmayıp bunun yerine (eski) varsayılan değer stilini kullanırsanız, o fonksiyonu FastAPI olmadan başka yerlerde çağırdığınızda doğru çalışması için argümanları geçmeniz gerektiğini hatırlamak zorunda kalırsınız; yoksa değerler beklediğinizden farklı olur (ör. str yerine QueryInfo veya benzeri). Üstelik editörünüz de şikayet etmez ve Python da fonksiyonu çalıştırırken şikayet etmez; ancak içerideki operasyonlar hata verince ortaya çıkar.
Annotated birden fazla metadata anotasyonu alabildiği için, artık aynı fonksiyonu Typer gibi başka araçlarla da kullanabilirsiniz. 🚀
Daha fazla doğrulama ekleyin¶
min_length parametresini de ekleyebilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(min_length=3, max_length=50)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[Union[str, None], Query(min_length=3, max_length=50)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(default=None, min_length=3, max_length=50)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(default=None, min_length=3, max_length=50),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Regular expression ekleyin¶
Parametrenin eşleşmesi gereken bir pattern regular expression tanımlayabilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
Union[str, None], Query(min_length=3, max_length=50, pattern="^fixedquery$")
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(
default=None, min_length=3, max_length=50, pattern="^fixedquery$"
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(
default=None, min_length=3, max_length=50, pattern="^fixedquery$"
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Bu özel regular expression pattern’i, gelen parametre değerinin şunları sağladığını kontrol eder:
^: Aşağıdaki karakterlerle başlar; öncesinde karakter yoktur.fixedquery: Tam olarakfixedquerydeğerine sahiptir.$: Orada biter;fixedquerysonrasında başka karakter yoktur.
Bu "regular expression" konuları gözünüzü korkutuyorsa sorun değil. Birçok kişi için zor bir konudur. Regular expression’lara ihtiyaç duymadan da pek çok şey yapabilirsiniz.
Artık ihtiyaç duyduğunuzda FastAPI içinde kullanabileceğinizi biliyorsunuz.
Varsayılan değerler¶
Elbette None dışında varsayılan değerler de kullanabilirsiniz.
Örneğin q query parametresi için min_length değerini 3 yapmak ve varsayılan değer olarak "fixedquery" vermek istediğinizi düşünelim:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)] = "fixedquery"):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str = Query(default="fixedquery", min_length=3)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Not
None dahil herhangi bir tipte varsayılan değere sahip olmak, parametreyi opsiyonel (zorunlu değil) yapar.
Zorunlu parametreler¶
Daha fazla doğrulama veya metadata tanımlamamız gerekmiyorsa, q query parametresini yalnızca varsayılan değer tanımlamayarak zorunlu yapabiliriz:
q: str
şunun yerine:
q: str | None = None
Ancak biz artık Query ile tanımlıyoruz; örneğin şöyle:
q: Annotated[str | None, Query(min_length=3)] = None
Dolayısıyla Query kullanırken bir değeri zorunlu yapmak istediğinizde, varsayılan değer tanımlamamanız yeterlidir:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)]):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str = Query(min_length=3)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Zorunlu ama None olabilir¶
Bir parametrenin None kabul edebileceğini söyleyip yine de zorunlu olmasını sağlayabilirsiniz. Bu, client’ların değer göndermesini zorunlu kılar; değer None olsa bile.
Bunu yapmak için None’ı geçerli bir tip olarak tanımlayın ama varsayılan değer vermeyin:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(min_length=3)]):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[str, None], Query(min_length=3)]):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(min_length=3)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(min_length=3)):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Query parametresi listesi / birden fazla değer¶
Bir query parametresini Query ile açıkça tanımladığınızda, bir değer listesi alacak şekilde (başka bir deyişle, birden fazla değer alacak şekilde) de tanımlayabilirsiniz.
Örneğin URL’de q query parametresinin birden fazla kez görünebilmesini istiyorsanız şöyle yazabilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[list[str] | None, Query()] = None):
query_items = {"q": q}
return query_items
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[list[str], None], Query()] = None):
query_items = {"q": q}
return query_items
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: list[str] | None = Query(default=None)):
query_items = {"q": q}
return query_items
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[list[str], None] = Query(default=None)):
query_items = {"q": q}
return query_items
Sonra şu URL ile:
http://localhost:8000/items/?q=foo&q=bar
path operation function içinde, function parameter olan q parametresinde, birden fazla q query parameters değerini (foo ve bar) bir Python list’i olarak alırsınız.
Dolayısıyla bu URL’ye response şöyle olur:
{
"q": [
"foo",
"bar"
]
}
İpucu
Yukarıdaki örnekte olduğu gibi tipi list olan bir query parametresi tanımlamak için Query’yi açıkça kullanmanız gerekir; aksi halde request body olarak yorumlanır.
Etkileşimli API dokümanları da buna göre güncellenir ve birden fazla değere izin verir:
Varsayılanlarla query parametresi listesi / birden fazla değer¶
Hiç değer verilmezse varsayılan bir list de tanımlayabilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[list[str], Query()] = ["foo", "bar"]):
query_items = {"q": q}
return query_items
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: list[str] = Query(default=["foo", "bar"])):
query_items = {"q": q}
return query_items
Şu adrese giderseniz:
http://localhost:8000/items/
q’nun varsayılanı ["foo", "bar"] olur ve response şöyle olur:
{
"q": [
"foo",
"bar"
]
}
Sadece list kullanmak¶
list[str] yerine doğrudan list de kullanabilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[list, Query()] = []):
query_items = {"q": q}
return query_items
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: list = Query(default=[])):
query_items = {"q": q}
return query_items
Not
Bu durumda FastAPI, listenin içeriğini kontrol etmez.
Örneğin list[int], listenin içeriğinin integer olduğunu kontrol eder (ve dokümante eder). Ancak tek başına list bunu yapmaz.
Daha fazla metadata tanımlayın¶
Parametre hakkında daha fazla bilgi ekleyebilirsiniz.
Bu bilgiler oluşturulan OpenAPI’a dahil edilir ve dokümantasyon arayüzleri ile harici araçlar tarafından kullanılır.
Not
Farklı araçların OpenAPI desteği farklı seviyelerde olabilir.
Bazıları tanımladığınız ek bilgilerin hepsini göstermeyebilir; ancak çoğu durumda eksik özellik geliştirme planındadır.
Bir title ekleyebilirsiniz:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(title="Query string", min_length=3)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[Union[str, None], Query(title="Query string", min_length=3)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(default=None, title="Query string", min_length=3),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(default=None, title="Query string", min_length=3),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Ve bir description:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
str | None,
Query(
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
),
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
Union[str, None],
Query(
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
),
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(
default=None,
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(
default=None,
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Alias parametreleri¶
Parametrenin adının item-query olmasını istediğinizi düşünün.
Örneğin:
http://127.0.0.1:8000/items/?item-query=foobaritems
Ancak item-query geçerli bir Python değişken adı değildir.
En yakın seçenek item_query olur.
Ama sizin hâlâ tam olarak item-query olmasına ihtiyacınız var...
O zaman bir alias tanımlayabilirsiniz; bu alias, parametre değerini bulmak için kullanılacaktır:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(alias="item-query")] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Annotated[Union[str, None], Query(alias="item-query")] = None):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: str | None = Query(default=None, alias="item-query")):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(default=None, alias="item-query")):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Parametreleri deprecated yapmak¶
Diyelim ki artık bu parametreyi istemiyorsunuz.
Bazı client’lar hâlâ kullandığı için bir süre tutmanız gerekiyor, ama dokümanların bunu açıkça deprecated olarak göstermesini istiyorsunuz.
O zaman Query’ye deprecated=True parametresini geçin:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
str | None,
Query(
alias="item-query",
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
max_length=50,
pattern="^fixedquery$",
deprecated=True,
),
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[
Union[str, None],
Query(
alias="item-query",
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
max_length=50,
pattern="^fixedquery$",
deprecated=True,
),
] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(
default=None,
alias="item-query",
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
max_length=50,
pattern="^fixedquery$",
deprecated=True,
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(
default=None,
alias="item-query",
title="Query string",
description="Query string for the items to search in the database that have a good match",
min_length=3,
max_length=50,
pattern="^fixedquery$",
deprecated=True,
),
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Dokümanlarda şöyle görünür:
Parametreleri OpenAPI’dan hariç tutun¶
Oluşturulan OpenAPI şemasından (dolayısıyla otomatik dokümantasyon sistemlerinden) bir query parametresini hariç tutmak için Query’nin include_in_schema parametresini False yapın:
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
hidden_query: Annotated[str | None, Query(include_in_schema=False)] = None,
):
if hidden_query:
return {"hidden_query": hidden_query}
else:
return {"hidden_query": "Not found"}
🤓 Other versions and variants
from typing import Annotated, Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
hidden_query: Annotated[Union[str, None], Query(include_in_schema=False)] = None,
):
if hidden_query:
return {"hidden_query": hidden_query}
else:
return {"hidden_query": "Not found"}
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
hidden_query: str | None = Query(default=None, include_in_schema=False),
):
if hidden_query:
return {"hidden_query": hidden_query}
else:
return {"hidden_query": "Not found"}
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
hidden_query: Union[str, None] = Query(default=None, include_in_schema=False),
):
if hidden_query:
return {"hidden_query": hidden_query}
else:
return {"hidden_query": "Not found"}
Özel Doğrulama¶
Yukarıdaki parametrelerle yapılamayan bazı özel doğrulama ihtiyaçlarınız olabilir.
Bu durumlarda, normal doğrulamadan sonra (ör. değerin str olduğunun doğrulanmasından sonra) uygulanacak bir custom validator function kullanabilirsiniz.
Bunu, Annotated içinde Pydantic’in AfterValidator’ını kullanarak yapabilirsiniz.
İpucu
Pydantic’te BeforeValidator ve başka validator’lar da vardır. 🤓
Örneğin bu custom validator, bir item ID’sinin ISBN kitap numarası için isbn- ile veya IMDB film URL ID’si için imdb- ile başladığını kontrol eder:
import random
from typing import Annotated
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
🤓 Other versions and variants
import random
from typing import Annotated, Union
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[Union[str, None], AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
Bilgi
Bu özellik Pydantic 2 ve üzeri sürümlerde mevcuttur. 😎
İpucu
Veritabanı veya başka bir API gibi herhangi bir harici bileşen ile iletişim gerektiren bir doğrulama yapmanız gerekiyorsa, bunun yerine FastAPI Dependencies kullanmalısınız; onları ileride öğreneceksiniz.
Bu custom validator’lar, request’te sağlanan yalnızca aynı veri ile kontrol edilebilen şeyler içindir.
O Kodu Anlamak¶
Önemli nokta, Annotated içinde bir fonksiyonla birlikte AfterValidator kullanmak. İsterseniz bu kısmı atlayabilirsiniz. 🤸
Ama bu örnek kodun detaylarını merak ediyorsanız, birkaç ek bilgi:
value.startswith() ile String¶
Fark ettiniz mi? value.startswith() ile bir string, tuple alabilir ve tuple içindeki her değeri kontrol eder:
# Code above omitted 👆
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
# Code below omitted 👇
👀 Full file preview
import random
from typing import Annotated
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
🤓 Other versions and variants
import random
from typing import Annotated, Union
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[Union[str, None], AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
Rastgele Bir Item¶
data.items() ile, her dictionary öğesi için key ve value içeren tuple’lardan oluşan bir iterable object elde ederiz.
Bu iterable object’i list(data.items()) ile düzgün bir list’e çeviririz.
Ardından random.choice() ile list’ten rastgele bir değer alırız; yani (id, name) içeren bir tuple elde ederiz. Şuna benzer: ("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy").
Sonra tuple içindeki bu iki değeri id ve name değişkenlerine atarız.
Böylece kullanıcı bir item ID’si vermemiş olsa bile yine de rastgele bir öneri alır.
...bütün bunları tek bir basit satırda yapıyoruz. 🤯 Python’u sevmemek elde mi? 🐍
# Code above omitted 👆
@app.get("/items/")
async def read_items(
id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
👀 Full file preview
import random
from typing import Annotated
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
🤓 Other versions and variants
import random
from typing import Annotated, Union
from fastapi import FastAPI
from pydantic import AfterValidator
app = FastAPI()
data = {
"isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
"imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
"isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}
def check_valid_id(id: str):
if not id.startswith(("isbn-", "imdb-")):
raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
return id
@app.get("/items/")
async def read_items(
id: Annotated[Union[str, None], AfterValidator(check_valid_id)] = None,
):
if id:
item = data.get(id)
else:
id, item = random.choice(list(data.items()))
return {"id": id, "name": item}
Özet¶
Parametreleriniz için ek doğrulamalar ve metadata tanımlayabilirsiniz.
Genel doğrulamalar ve metadata:
aliastitledescriptiondeprecated
String’lere özel doğrulamalar:
min_lengthmax_lengthpattern
AfterValidator ile custom doğrulamalar.
Bu örneklerde str değerleri için doğrulamanın nasıl tanımlanacağını gördünüz.
Sayılar gibi diğer tipler için doğrulamaları nasıl tanımlayacağınızı öğrenmek için sonraki bölümlere geçin.