Modelos de Parâmetros de Cookie¶
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.
🌐 Tradução por IA e humanos
Esta tradução foi feita por IA orientada por humanos. 🤝
Ela pode conter erros de interpretação do significado original ou soar pouco natural, etc. 🤖
Você pode melhorar esta tradução ajudando-nos a orientar melhor o LLM de IA.
Se você possui um grupo de cookies que estão relacionados, você pode criar um modelo Pydantic para declará-los. 🍪
Isso lhe permitiria reutilizar o modelo em diversos lugares e também declarar validações e metadata para todos os parâmetros de uma vez. 😎
Nota
Isso é suportado desde a versão 0.115.0 do FastAPI. 🤓
Dica
Essa mesma técnica se aplica para Query, Cookie, e Header. 😎
Cookies com Modelos Pydantic¶
Declare os parâmetros de cookie de que você precisa em um modelo Pydantic, e depois declare o parâmetro como 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
O FastAPI irá extrair os dados para cada campo dos cookies recebidos na requisição e lhe fornecer o modelo Pydantic que você definiu.
Verifique a Documentação¶
Você pode ver os cookies definidos na IU da documentação em /docs:
Nota
Tenha em mente que, como os navegadores lidam com cookies de maneira especial e por baixo dos panos, eles não permitem facilmente que o JavaScript lide com eles.
Se você for na IU da documentação da API em /docs você poderá ver a documentação para cookies das suas operações de rota.
Mas mesmo que você adicione os dados e clique em "Executar", pelo motivo da IU da documentação trabalhar com JavaScript, os cookies não serão enviados, e você verá uma mensagem de erro como se você não tivesse escrito nenhum dado.
Proíba Cookies Adicionais¶
Em alguns casos especiais (provavelmente não muito comuns), você pode querer restringir os cookies que você deseja receber.
Agora a sua API possui o poder de controlar o seu próprio consentimento de cookie. 🤪🍪
Você pode utilizar a configuração do modelo Pydantic para proibir com forbid qualquer campo 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
Se o cliente tentar enviar alguns cookies extras, ele receberá uma resposta de erro.
Coitados dos banners de cookies com todo o seu esforço para obter o seu consentimento para a API rejeitá-lo. 🍪
Por exemplo, se o cliente tentar enviar um cookie santa_tracker com o valor de good-list-please, o cliente receberá uma resposta de erro informando que o santa_tracker cookie não é permitido:
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["cookie", "santa_tracker"],
"msg": "Extra inputs are not permitted",
"input": "good-list-please",
}
]
}
Combine Modelos de Parâmetros¶
Você pode combinar vários modelos de parâmetros de cookie com parâmetros de cookie individuais e dependências. Cada modelo é extraído e validado de forma independente, conforme explicado para modelos de parâmetros de query.
A configuração extra de cada modelo se aplica a todos os parâmetros de cookie, incluindo os declarados em outros modelos ou dependências. Com extra="forbid", qualquer cookie fora desse modelo é rejeitado. Com extra="allow", esses cookies são incluídos como campos extras do modelo.
Modelos Opcionais de Parâmetros de Cookie¶
Declare um modelo de parâmetros de cookie com | None e um valor padrão de None para tornar o grupo opcional.
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
Se nem theme nem locale forem enviados, preferences será None. Se qualquer um deles for enviado, o FastAPI validará o modelo e exigirá ambos os campos.
As mesmas regras para valores padrão, campos extras e OpenAPI se aplicam, assim como nos modelos opcionais de parâmetros de query.
Resumo¶
Você consegue utilizar modelos Pydantic para declarar cookies no FastAPI. 😎