Query Parameter Modelleri¶

uvx library-skills

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. 😎

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:

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

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:

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

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"
        }
    ]
}

Parametre Modellerini Birleştirin¶

Birden fazla query parameter modeli tanımlayabilir ve bunları tekil query parameter'larla veya dependency'lerle birleştirebilirsiniz.

from typing import Annotated

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

app = FastAPI()


class Pagination(BaseModel):
    limit: int = Field(10, ge=1)
    offset: int = Field(0, ge=0)


class Filters(BaseModel):
    tags: list[str] = []


@app.get("/items/")
def read_items(
    pagination: Annotated[Pagination, Query()],
    filters: Annotated[Filters, Query()],
    search: str | None = None,
):
    return {"pagination": pagination, "filters": filters, "search": search}

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

app = FastAPI()


class Pagination(BaseModel):
    limit: int = Field(10, ge=1)
    offset: int = Field(0, ge=0)


class Filters(BaseModel):
    tags: list[str] = []


@app.get("/items/")
def read_items(
    pagination: Pagination = Query(),
    filters: Filters = Query(),
    search: str | None = None,
):
    return {"pagination": pagination, "filters": filters, "search": search}

Request parametreleri aynı seviyede kalır.

https://example.com/items/?limit=5&offset=10&tags=red&tags=blue&search=shirt

Query string'de pagination veya filters anahtarları bulunmaz. Her model, kendi varsayılan değerleri, field validator'ları ve model validator'larıyla query parameter'ları bağımsız olarak doğrular. Modeller veya tekil parametreler dependency'lerde tanımlandığında da aynı durum geçerlidir.

Modeller aynı parametre adını veya alias'ı paylaşıyorsa, her model bu request parametresini bağımsız olarak doğrular. Bağımsız değerler için farklı adlar veya alias'lar kullanın. OpenAPI, dependency'lerle paylaşılan parametrelerde olduğu gibi, paylaşılan bir parametreyi yalnızca bir kez listeler. Bu nedenle, paylaşılan parametre tanımları aynı türü ve kısıtlamaları belirtmelidir.

Her modelin extra konfigürasyonu, diğer modellerde veya dependency'lerde tanımlananlar da dahil olmak üzere tüm query parameter'lara uygulanır. extra="forbid" kullanıldığında, modelin dışında kalan tüm parametreler reddedilir. extra="allow" kullanıldığında ise bu parametreler modele ek veriler olarak dahil edilir.

Bu, Header ve Cookie modelleri için de geçerlidir.

İsteğe Bağlı Query Parameter Modelleri¶

Grubu isteğe bağlı hale getirmek için query parameter modelini | None ile tanımlayın ve varsayılan değerini None olarak ayarlayın.

from datetime import date
from typing import Annotated

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()


class DateRange(BaseModel):
    start: date
    end: date


@app.get("/items/")
async def read_items(
    limit: int = 10,
    date_range: Annotated[DateRange | None, Query()] = None,
):
    return {"limit": limit, "date_range": date_range}

from datetime import date

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()


class DateRange(BaseModel):
    start: date
    end: date


@app.get("/items/")
async def read_items(
    limit: int = 10,
    date_range: DateRange | None = Query(default=None),
):
    return {"limit": limit, "date_range": date_range}

Ne start ne de end gönderilirse, date_range değeri None olur. İkisinden biri gönderilirse, FastAPI modeli doğrular ve her iki field'ı da zorunlu kılar.

Varsayılan değer belirtmeden | None kullanıldığında parametre yine zorunludur.

Ek parametreler modelin extra konfigürasyonuna göre işlenir. Yok sayılan ek parametreler, modelin gönderilmiş sayılmasına neden olmaz.

OpenAPI, gruptaki field'ları ayrı ayrı listeler ve isteğe bağlı olarak işaretler.

İsteğe bağlı header parameter modelleri ve cookie parameter modelleri de tanımlayabilirsiniz.

Özet¶

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