Header Parametre Modelleri¶

uvx library-skills

Birbiriyle ilişkili header parametrelerinden oluşan bir grubunuz varsa, bunları tanımlamak için bir Pydantic model oluşturabilirsiniz.

Bu sayede modeli birden fazla yerde yeniden kullanabilir, ayrıca tüm parametreler için doğrulamaları ve metadata bilgilerini tek seferde tanımlayabilirsiniz. 😎

Pydantic Model ile Header Parametreleri¶

İhtiyacınız olan header parametrelerini bir Pydantic model içinde tanımlayın, ardından parametreyi Header olarak belirtin:

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

FastAPI, request içindeki headers bölümünden her alan için veriyi çıkarır ve size tanımladığınız Pydantic model örneğini verir.

Dokümanları Kontrol Edin¶

Gerekli header'ları /docs altındaki doküman arayüzünde görebilirsiniz:

Ek Header'ları Yasaklayın¶

Bazı özel kullanım senaryolarında (muhtemelen çok yaygın değil), kabul etmek istediğiniz header'ları kısıtlamak isteyebilirsiniz.

Pydantic'in model yapılandırmasını kullanarak extra alanları forbid edebilirsiniz:

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


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

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


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

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

Bir client bazı ek header'lar göndermeye çalışırsa, hata response'u alır.

Örneğin client, değeri plumbus olan bir tool header'ı göndermeye çalışırsa, tool header parametresine izin verilmediğini söyleyen bir hata response'u alır:

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

Alt Çizgileri Dönüştürmeyi Kapatın¶

Normal header parametrelerinde olduğu gibi, parametre adlarında alt çizgi karakterleri olduğunda bunlar otomatik olarak tireye dönüştürülür.

Örneğin kodda save_data adlı bir header parametreniz varsa, beklenen HTTP header save-data olur ve dokümanlarda da bu şekilde görünür.

Herhangi bir sebeple bu otomatik dönüşümü kapatmanız gerekiyorsa, header parametreleri için kullandığınız Pydantic model'lerde de bunu devre dışı bırakabilirsiniz.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(
    headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
    return headers

Parametre Modellerini Birleştirin¶

Birden fazla header parametre modelini, ayrı header parametreleri ve bağımlılıklarla birleştirebilirsiniz. Query parametre modelleri için açıklandığı gibi, her modelin verileri bağımsız olarak çıkarılır ve doğrulanır.

Her modelin extra yapılandırması, diğer modellerde veya bağımlılıklarda tanımlananlar dahil tüm header parametrelerine uygulanır. extra="forbid" kullanıldığında, o modelin dışındaki tüm header'lar reddedilir. extra="allow" kullanıldığında ise bu header'lar modele ek alanlar olarak dahil edilir.

Her model, hem request'i okurken hem de OpenAPI oluştururken kendi Header(convert_underscores=...) ayarını kullanır. Açıkça belirtilen alan alias'ları, değiştirilmeden header adı olarak kullanılır.

İsteğe Bağlı Header Parametre Modelleri¶

Grubu isteğe bağlı yapmak için header parametre modelini | None ile tanımlayın ve varsayılan değerini None olarak ayarlayın.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: Annotated[ClientHeaders | None, Header()] = None):
    return client

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: ClientHeaders | None = Header(default=None)):
    return client

Ne x-client-name ne de x-client-version gönderilirse, client değeri None olur. İkisinden biri gönderilirse, FastAPI modeli doğrular ve her iki alanı da zorunlu tutar.

Varsayılan değerler, ek alanlar ve OpenAPI için isteğe bağlı query parametre modelleri ile aynı kurallar geçerlidir.

Host gibi header'lar da modelin extra yapılandırmasına tabidir. extra="allow" kullanıldığında, tanımlanan iki alanın hiçbiri gönderilmese bile bu header'lar modelin oluşturulmasını sağlar.

Özet¶

FastAPI'de headers tanımlamak için Pydantic model kullanabilirsiniz. 😎