標頭參數¶
您可以用定義 Query、Path 和 Cookie 參數相同的方式定義標頭參數。
導入 Header¶
首先導入 Header
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}
提示
如果可能，建議使用 Annotated 版本。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
宣告 Header 參數¶
然後使用與 Path、Query 和 Cookie 相同的結構宣告標頭參數。
您可以定義預設值以及所有額外的驗證或註釋參數。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
「技術細節」
Header 是 Path、Query 和 Cookie 的「姊妹」類別。它也繼承自相同的通用 Param 類別。
但請記住，當您從 fastapi 導入 Query、Path、Header 等時，這些實際上是返回特殊類別的函式。
資訊
要宣告標頭，您需要使用 Header，否則參數將被解釋為查詢參數。
自動轉換¶
Header 比 Path、Query 和 Cookie 提供了一些額外的功能。
大多數標準標頭都以「連字號」字元分隔，也稱為「減號」(-)。
但是像 user-agent 這樣的變數在 Python 中是無效的。
因此，預設情況下，Header 會將參數名稱中的底線 (_) 轉換為連字號 (-) 以提取和記錄標頭。
此外，HTTP 標頭是不區分大小寫的，因此您可以使用標準 Python 風格（也稱為「snake_case」）來宣告它們。
因此，您可以像在 Python 程式碼中那樣正常使用 user_agent，而無需像 User_Agent 或類似名稱那樣將首字母大寫。
如果由於某種原因您需要停用底線到連字號的自動轉換，請將 Header 的 convert_underscores 參數設定為 False。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
警告
在將 convert_underscores 設定為 False 之前，請記住某些 HTTP 代理伺服器和伺服器不允許使用帶有底線的標頭。
重複的標頭¶
可能會收到重複的標頭。這表示同一個標頭具有多個值。
您可以使用類型宣告中的列表來定義這些情況。
您將以 Python list 的形式接收來自重複標頭的所有值。
例如，要宣告一個可以出現多次的 X-Token 標頭，您可以這樣寫：
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}
提示
如果可能，建議使用 Annotated 版本。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
提示
如果可能，建議使用 Annotated 版本。
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}
如果您與該*路徑操作*通訊，並發送兩個 HTTP 標頭，例如：
X-Token: foo
X-Token: bar
則回應會像這樣：
{
"X-Token values": [
"bar",
"foo"
]
}
摘要¶
使用 Header 宣告標頭，使用與 Query、Path 和 Cookie 相同的通用模式。
不用擔心變數中的底線，FastAPI 會負責轉換它們。