クッキーパラメータモデル¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

もし関連する複数のクッキーから成るグループがあるなら、それらを宣言するために、Pydanticモデルを作成できます。🍪

こうすることで、複数の場所でそのPydanticモデルを再利用でき、バリデーションやメタデータを、すべてのパラメータに対して一度に宣言できます。😎

備考

この機能は、FastAPIのバージョン 0.115.0 からサポートされています。🤓

豆知識

これと同じテクニックは Query 、 Cookie 、 Header にも適用できます。 😎

Pydanticモデルを使用したクッキー¶

必要な複数のクッキーパラメータをPydanticモデルで宣言し、さらに、パラメータを Cookie として宣言しましょう:

Python 3.10+

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

🤓 Other versions and variants

Python 3.9+Python 3.10+ - non-AnnotatedPython 3.9+ - non-Annotated

from typing import Annotated, Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

Tip

Prefer to use the Annotated version if possible.

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

FastAPIは、リクエストで受け取ったクッキーからそれぞれのフィールドのデータを抽出し、定義したPydanticモデルを提供します。

ドキュメントの確認¶

対話的APIドキュメントUI /docs で、定義されているクッキーを確認できます:

情報

ブラウザがクッキーを処理していますが、特別な方法で内部的に処理を行っているために、JavaScriptからは簡単に操作できないことに留意してください。

APIドキュメントUI /docs にアクセスすれば、path operationに関するクッキーのドキュメンテーションを確認できます。

しかし、たとえデータを入力して「Execute」をクリックしても、ドキュメントUIはJavaScriptで動作しているためクッキーは送信されず、まるで値を入力しなかったかのようなエラーメッセージが表示されます。

余分なクッキーを禁止する¶

特定の（あまり一般的ではないかもしれない）ケースで、受け付けるクッキーを制限する必要があるかもしれません。

あなたのAPIは独自のクッキー同意を管理する能力を持っています。 🤪🍪

Pydanticのモデルの Configuration を利用して、 extra フィールドを forbid とすることができます。

Python 3.10+

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

🤓 Other versions and variants

Python 3.9+Python 3.10+ - non-AnnotatedPython 3.9+ - non-Annotated

from typing import Annotated, Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

Tip

Prefer to use the Annotated version if possible.

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

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

どうせAPIに拒否されるのにあなたの同意を得ようと精一杯努力する可哀想なクッキーバナーたち... 🍪

例えば、クライアントがクッキー santa_tracker を good-list-please という値で送ろうとすると、santa_tracker というクッキーが許可されていないことを通知するエラーレスポンスが返されます:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["cookie", "santa_tracker"],
            "msg": "Extra inputs are not permitted",
            "input": "good-list-please",
        }
    ]
}

まとめ¶

FastAPIでは、クッキーを宣言するために、Pydanticモデルを使用できます。😎