Modèles de paramètres d'en-tête¶

uvx library-skills

Si vous avez un groupe de paramètres d'en-tête liés, vous pouvez créer un modèle Pydantic pour les déclarer.

Cela vous permet de réutiliser le modèle à plusieurs endroits et aussi de déclarer des validations et des métadonnées pour tous les paramètres en une seule fois. 😎

Paramètres d'en-tête avec un modèle Pydantic¶

Déclarez les paramètres d'en-tête dont vous avez besoin dans un modèle Pydantic, puis déclarez le paramètre comme Header :

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 extrait les données de chaque champ depuis les en-têtes de la requête et vous fournit le modèle Pydantic que vous avez défini.

Consultez les documents¶

Vous pouvez voir les en-têtes requis dans l'interface des documents à /docs :

Interdisez les en-têtes supplémentaires¶

Dans certains cas d'utilisation particuliers (probablement pas très courants), vous pourriez vouloir restreindre les en-têtes que vous souhaitez recevoir.

Vous pouvez utiliser la configuration du modèle de Pydantic pour forbid tout champ extra :

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

Si un client essaie d'envoyer des en-têtes supplémentaires, il recevra une réponse d'erreur.

Par exemple, si le client essaie d'envoyer un en-tête tool avec la valeur plumbus, il recevra une réponse d'erreur lui indiquant que le paramètre d'en-tête tool n'est pas autorisé :

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

Désactivez la conversion des caractères de soulignement¶

Comme pour les paramètres d'en-tête classiques, lorsque vous avez des caractères de soulignement dans les noms de paramètres, ils sont automatiquement convertis en tirets.

Par exemple, si vous avez un paramètre d'en-tête save_data dans le code, l'en-tête HTTP attendu sera save-data, et il apparaîtra ainsi dans les documents.

Si, pour une raison quelconque, vous devez désactiver cette conversion automatique, vous pouvez aussi le faire pour les modèles Pydantic de paramètres d'en-tête.

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

Combinez les modèles de paramètres¶

Vous pouvez combiner plusieurs modèles de paramètres d'en-tête avec des paramètres d'en-tête individuels et des dépendances. Chaque modèle est extrait et validé indépendamment, comme expliqué pour les modèles de paramètres de requête.

La configuration extra de chaque modèle s'applique à tous les paramètres d'en-tête, y compris ceux déclarés dans d'autres modèles ou dépendances. Avec extra="forbid", tout en-tête extérieur à ce modèle est rejeté. Avec extra="allow", ces en-têtes sont inclus comme champs supplémentaires du modèle.

Chaque modèle utilise son propre réglage Header(convert_underscores=...), aussi bien lors de la lecture de la requête que lors de la génération d'OpenAPI. Les alias de champs explicites restent des noms d'en-tête littéraux.

Modèles de paramètres d'en-tête optionnels¶

Déclarez un modèle de paramètres d'en-tête avec | None et une valeur par défaut de None pour rendre le groupe optionnel.

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

Si ni x-client-name ni x-client-version n'est envoyé, client vaut None. Si l'un des deux est envoyé, FastAPI valide le modèle et exige les deux champs.

Les mêmes règles concernant les valeurs par défaut, les champs supplémentaires et OpenAPI s'appliquent que pour les modèles de paramètres de requête optionnels.

Les en-têtes tels que Host suivent également la configuration extra du modèle. Avec extra="allow", ils rendent le modèle présent même si aucun des deux champs déclarés n'est fourni.

Résumé¶

Vous pouvez utiliser des modèles Pydantic pour déclarer des en-têtes dans FastAPI. 😎