Query Parameter Modelleri¶

🌐 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â LLM'ini daha iyi yönlendirmemize yardımcı olarak bu çeviriyi iyileştirebilirsiniz.

Birbirleriyle ilişkili bir query parameter grubunuz varsa, bunları tanımlamak için bir Pydantic model oluşturabilirsiniz.

Böylece modeli yeniden kullanabilir, birden fazla yerde tekrar tekrar kullanabilir ve tüm parametreler için validation (doğrulama) ile metadata’yı tek seferde tanımlayabilirsiniz. 😎

Not

Bu özellik FastAPI 0.115.0 sürümünden beri desteklenmektedir. 🤓

Pydantic Model ile Query Parameters¶

İhtiyacınız olan query parameter’ları bir Pydantic model içinde tanımlayın, ardından parametreyi Query olarak belirtin:

Python 3.10+

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

FastAPI, request’teki query parameter’lardan her field için veriyi extract eder ve tanımladığınız Pydantic model’i size verir.

Dokümanları Kontrol Edin¶

Query parameter’ları /docs altındaki dokümantasyon arayüzünde görebilirsiniz:

Ek Query Parameter'ları Yasaklayın¶

Bazı özel kullanım senaryolarında (muhtemelen çok yaygın değil), almak istediğiniz query parameter’ları kısıtlamak isteyebilirsiniz.

Pydantic’in model konfigürasyonunu kullanarak extra field’ları forbid edebilirsiniz:

Python 3.10+

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

Bir client, query parameter’larda ek (extra) veri göndermeye çalışırsa, error response alır.

Örneğin client, değeri plumbus olan bir tool query parameter’ı göndermeye çalışırsa:

https://example.com/items/?limit=10&tool=plumbus

tool query parameter’ına izin verilmediğini söyleyen bir error response alır:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

Özet¶

FastAPI içinde query parameter’ları tanımlamak için Pydantic model’leri kullanabilirsiniz. 😎

İpucu

Spoiler: cookie ve header’ları tanımlamak için de Pydantic model’leri kullanabilirsiniz; ancak bunu tutorial’ın ilerleyen bölümlerinde göreceksiniz. 🤫