ヘッダーパラメータのモデル¶

🌐 AI と人間による翻訳

この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝

原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖

AI LLM をより適切に誘導するのを手伝うことで、この翻訳を改善できます。

英語版

関連するヘッダーパラメータが一式ある場合、それらを宣言するためのPydantic モデルを作成できます。

これにより、モデルを複数箇所で再利用でき、さらにすべてのパラメータに対するバリデーションやメタデータを一括で宣言できます。😎

備考

これは FastAPI バージョン 0.115.0 以降でサポートされています。🤓

Pydantic モデルによるヘッダーパラメータ¶

必要なヘッダーパラメータをPydantic モデル内で宣言し、関数引数ではそのパラメータを Header として宣言します:

Python 3.10+

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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 はリクエストのヘッダーから各フィールドの値を抽出し、定義した Pydantic モデルとして渡します。

ドキュメントの確認¶

/docs のドキュメント UI で必要なヘッダーを確認できます:

余分なヘッダーを禁止¶

特殊なユースケース（あまり一般的ではありません）では、受け付けるヘッダーを制限したい場合があります。

Pydantic のモデル設定で extra フィールドを forbid にして禁止できます:

Python 3.10+

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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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

クライアントが余分なヘッダーを送信しようとすると、エラーレスポンスが返されます。

例えば、クライアントが値 plumbus の tool ヘッダーを送ろうとすると、ヘッダーパラメータ tool は許可されていない旨のエラーレスポンスが返されます:

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

アンダースコア変換の無効化¶

通常のヘッダーパラメータと同様に、パラメータ名にアンダースコアがある場合は自動的にハイフンに変換されます。

例えば、コード上でヘッダーパラメータ save_data を定義すると、想定される HTTP ヘッダーは save-data となり、ドキュメント上にもそのように表示されます。

何らかの理由でこの自動変換を無効化する必要がある場合、ヘッダーパラメータ用の Pydantic モデルでも無効化できます。

Python 3.10+

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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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

注意

convert_underscores を False に設定する前に、アンダースコアを含むヘッダーの使用を禁止している HTTP プロキシやサーバーがあることに留意してください。

まとめ¶

Pydantic モデルを使って FastAPI で ヘッダーを宣言できます。😎