Parâmetros de Cabeçalho¶
Você pode definir parâmetros de Cabeçalho da mesma maneira que define paramêtros com Query, Path e Cookie.
importe Header¶
Primeiro importe Header:
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
🤓 Other versions and variants
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
from typing import Annotated, Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
return {"User-Agent": user_agent}
from typing import Union
from fastapi import FastAPI, Header
from typing_extensions import Annotated
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
return {"User-Agent": user_agent}
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
return {"User-Agent": user_agent}
Declare parâmetros de Header¶
Então declare os paramêtros de cabeçalho usando a mesma estrutura que em Path, Query e Cookie.
O primeiro valor é o valor padrão, você pode passar todas as validações adicionais ou parâmetros de anotação:
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
🤓 Other versions and variants
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
from typing import Annotated, Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
return {"User-Agent": user_agent}
from typing import Union
from fastapi import FastAPI, Header
from typing_extensions import Annotated
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
return {"User-Agent": user_agent}
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
return {"User-Agent": user_agent}
Detalhes Técnicos
Header é uma classe "irmã" de Path, Query e Cookie. Ela também herda da mesma classe em comum Param.
Mas lembre-se que quando você importa Query, Path, Header, e outras de fastapi, elas são na verdade funções que retornam classes especiais.
Info
Para declarar headers, você precisa usar Header, caso contrário, os parâmetros seriam interpretados como parâmetros de consulta.
Conversão automática¶
Header tem algumas funcionalidades a mais em relação a Path, Query e Cookie.
A maioria dos cabeçalhos padrão são separados pelo caractere "hífen", também conhecido como "sinal de menos" (-).
Mas uma variável como user-agent é inválida em Python.
Portanto, por padrão, Header converterá os caracteres de nomes de parâmetros de sublinhado (_) para hífen (-) para extrair e documentar os cabeçalhos.
Além disso, os cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, portanto, você pode declará-los com o estilo padrão do Python (também conhecido como "snake_case").
Portanto, você pode usar user_agent como faria normalmente no código Python, em vez de precisar colocar as primeiras letras em maiúsculas como User_Agent ou algo semelhante.
Se por algum motivo você precisar desabilitar a conversão automática de sublinhados para hífens, defina o parâmetro convert_underscores de Header para False:
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: str | None = Header(default=None, convert_underscores=False),
):
return {"strange_header": strange_header}
🤓 Other versions and variants
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
return {"strange_header": strange_header}
from typing import Annotated, Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[
Union[str, None], Header(convert_underscores=False)
] = None,
):
return {"strange_header": strange_header}
from typing import Union
from fastapi import FastAPI, Header
from typing_extensions import Annotated
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[
Union[str, None], Header(convert_underscores=False)
] = None,
):
return {"strange_header": strange_header}
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Union[str, None] = Header(default=None, convert_underscores=False),
):
return {"strange_header": strange_header}
Aviso
Antes de definir convert_underscores como False, lembre-se de que alguns proxies e servidores HTTP não permitem o uso de cabeçalhos com sublinhados.
Cabeçalhos duplicados¶
É possível receber cabeçalhos duplicados. Isso significa, o mesmo cabeçalho com vários valores.
Você pode definir esses casos usando uma lista na declaração de tipo.
Você receberá todos os valores do cabeçalho duplicado como uma list Python.
Por exemplo, para declarar um cabeçalho de X-Token que pode aparecer mais de uma vez, você pode escrever:
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: list[str] | None = Header(default=None)):
return {"X-Token values": x_token}
🤓 Other versions and variants
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
return {"X-Token values": x_token}
from typing import Annotated, List, Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
return {"X-Token values": x_token}
from typing import List, Union
from fastapi import FastAPI, Header
from typing_extensions import Annotated
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
return {"X-Token values": x_token}
Tip
Prefer to use the Annotated version if possible.
from typing import Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Union[list[str], None] = Header(default=None)):
return {"X-Token values": x_token}
Tip
Prefer to use the Annotated version if possible.
from typing import List, Union
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Union[List[str], None] = Header(default=None)):
return {"X-Token values": x_token}
Se você se comunicar com essa operação de caminho enviando dois cabeçalhos HTTP como:
X-Token: foo
X-Token: bar
A resposta seria como:
{
"X-Token values": [
"bar",
"foo"
]
}
Recapitulando¶
Declare cabeçalhos com Header, usando o mesmo padrão comum que utiliza-se em Query, Path e Cookie.
E não se preocupe com sublinhados em suas variáveis, FastAPI cuidará da conversão deles.