Cookie 參數模型¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

你可以透過協助我們更好地引導 AI LLM來改進此翻譯。

英文版

如果你有一組彼此相關的「Cookie」，你可以建立一個「Pydantic 模型」來宣告它們。🍪

這樣你就能在多處重複使用該模型，並且能一次性為所有參數宣告驗證與中繼資料。😎

注意

自 FastAPI 版本 0.115.0 起支援。🤓

Tip

同樣的技巧也適用於 Query、Cookie 與 Header。😎

以 Pydantic 模型宣告 Cookie¶

在 Pydantic 模型中宣告所需的 Cookie 參數，接著將參數宣告為 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.10+ - non-Annotated

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

FastAPI 會從請求收到的 Cookie 中擷取 每個欄位 的資料，並交給你定義的 Pydantic 模型。

查看文件¶

你可以在 /docs 的文件介面中看到已定義的 Cookie：

Info

請注意，由於瀏覽器會以特殊且在背景進行的方式處理 Cookie，因此不會輕易允許 JavaScript 存取它們。

當你前往位於 /docs 的 API 文件介面時，可以看到路徑操作的 Cookie 說明。

但即使你填入資料並點擊「Execute」，因為該文件介面是以 JavaScript 運作，Cookie 不會被送出，你會看到錯誤訊息，就像完全沒有填任何值一樣。

禁止額外的 Cookie¶

在某些特殊情境（可能不太常見）下，你可能會想限制允許接收的 Cookie。

你的 API 現在也能掌控自己的 Cookie 同意。🤪🍪

你可以使用 Pydantic 的模型設定來 forbid 任何 extra 欄位：

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.10+ - non-Annotated

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

如果客戶端嘗試送出額外的 Cookie，會收到錯誤回應。

可憐的 Cookie 橫幅辛苦收集你的同意，最後卻是為了讓 API 拒絕它。🍪

例如，若客戶端嘗試送出名為 santa_tracker、值為 good-list-please 的 Cookie，客戶端會收到錯誤回應，告知 santa_tracker 這個 Cookie 不被允許：

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

摘要¶

你可以在 FastAPI 中使用 Pydantic 模型來宣告 Cookie。😎