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

AI coding agents

Use the official FastAPI skill for your installed version. Install it from your project directory:

uvx library-skills

See Develop with AI.

🌐 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 プロキシやサーバーがあることに留意してください。

パラメータモデルの組み合わせ¶

複数のヘッダーパラメータモデルを、個別のヘッダーパラメータや依存関係と組み合わせることができます。クエリパラメータのモデルで説明されているように、各モデルの抽出とバリデーションは独立して行われます。

各モデルの extra 設定は、他のモデルや依存関係で宣言されたものも含め、すべてのヘッダーパラメータに適用されます。extra="forbid" の場合、そのモデルに含まれないヘッダーはすべて拒否されます。extra="allow" の場合、それらのヘッダーはモデルの追加フィールドとして含まれます。

各モデルは、リクエストの読み取り時と OpenAPI の生成時の両方で、独自の Header(convert_underscores=...) 設定を使用します。明示的なフィールドエイリアスは、そのままヘッダー名として扱われます。

オプショナルなヘッダーパラメータモデル¶

ヘッダーパラメータモデルを | None とデフォルト値 None で宣言すると、グループ全体を省略可能にできます。

Python 3.10+

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

🤓 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 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

x-client-name も x-client-version も送信されない場合、client は None になります。どちらかが送信されると、FastAPI はモデルをバリデーションし、両方のフィールドを必須とします。

デフォルト値、追加フィールド、OpenAPI には、オプショナルなクエリパラメータモデルと同じルールが適用されます。

Host などのヘッダーもモデルの extra 設定に従います。extra="allow" の場合、宣言されたどちらのフィールドも指定されていなくても、これらのヘッダーによってモデルが存在するものとして扱われます。

まとめ¶

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