Перейти до змісту

Моделі параметрів кукі

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 LLM.

Англійська версія

Якщо у вас є група кукі, які пов'язані між собою, ви можете створити Pydantic-модель, щоб оголосити їх. 🍪

Це дозволить вам повторно використовувати модель у різних місцях, а також оголосити валідацію та метадані для всіх параметрів одночасно. 😎

Примітка

Це підтримується з версії FastAPI 0.115.0. 🤓

Порада

Ця ж техніка застосовується до Query, Cookie та Header. 😎

Кукі з Pydantic-моделлю

Оголосіть параметри кукі, які вам потрібні, у Pydantic-моделі, а потім оголосіть параметр як Cookie:

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

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 буде витягувати дані для кожного поля з кукі, отриманих у запиті, і передавати вам Pydantic-модель, яку ви визначили.

Перевірка у документації

Ви можете побачити визначені кукі в інтерфейсі документації за адресою /docs:

Примітка

Майте на увазі, що оскільки браузери обробляють кукі особливим чином і «за лаштунками», вони не дозволяють JavaScript легко з ними працювати.

Якщо ви зайдете до інтерфейсу документації API за адресою /docs, ви зможете побачити документацію для кукі у ваших операціях шляху.

Але навіть якщо ви заповните дані й натиснете «Execute», оскільки інтерфейс документації працює з JavaScript, кукі не будуть відправлені, і ви побачите помилку, ніби ви не ввели жодних значень.

Заборона додаткових кукі

У деяких спеціальних випадках (ймовірно, не дуже поширених) ви можете захотіти обмежити кукі, які хочете отримувати.

Ваш API тепер має можливість контролювати власну згоду на кукі. 🤪🍪

Ви можете використовувати налаштування моделі Pydantic, щоб forbid будь-які extra поля:

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

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

Якщо клієнт спробує надіслати якісь додаткові кукі, він отримає відповідь з помилкою.

Бідні банери кукі, які так старанно намагаються отримати вашу згоду, щоб 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",
        }
    ]
}

Поєднання моделей параметрів

Ви можете поєднувати кілька моделей параметрів кукі з окремими параметрами кукі та залежностями. Дані для кожної моделі витягуються та валідуються незалежно, як пояснено для моделей параметрів запиту.

Налаштування extra кожної моделі застосовується до всіх параметрів кукі, включно з оголошеними в інших моделях або залежностях. З extra="forbid" будь-які кукі поза цією моделлю відхиляються. З extra="allow" ці кукі включаються як додаткові поля моделі.

Оголосіть модель параметрів кукі з | None і значенням за замовчуванням None, щоб зробити групу необов'язковою.

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Preferences(BaseModel):
    theme: str
    locale: str


@app.get("/items/")
async def read_items(preferences: Annotated[Preferences | None, Cookie()] = None):
    return preferences
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Preferences(BaseModel):
    theme: str
    locale: str


@app.get("/items/")
async def read_items(preferences: Preferences | None = Cookie(default=None)):
    return preferences

Якщо не надіслано ні theme, ні locale, preferences має значення None. Якщо надіслано хоча б одне з них, FastAPI валідує модель і вимагає обидва поля.

Застосовуються ті самі правила щодо значень за замовчуванням, додаткових полів і OpenAPI, що й для необов'язкових моделей параметрів запиту.

Підсумок

Ви можете використовувати Pydantic-моделі для оголошення кукі у FastAPI. 😎