ヘッダーのパラメータ¶
ヘッダーのパラメータは、QueryやPath、Cookieのパラメータを定義するのと同じように定義できます。
Headerをインポート¶
まず、Headerをインポートします:
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}
🤓 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 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}
Headerのパラメータの宣言¶
次に、PathやQuery、Cookieと同じ構造を用いてヘッダーのパラメータを宣言します。
最初の値がデフォルト値で、追加の検証パラメータや注釈パラメータをすべて渡すことができます。
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}
🤓 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 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}
技術詳細
HeaderはPathやQuery、Cookieの「姉妹」クラスです。また、同じ共通のParamクラスを継承しています。
しかし、fastapiからQueryやPath、Headerなどをインポートする場合、それらは実際には特殊なクラスを返す関数であることを覚えておいてください。
情報
ヘッダーを宣言するには、Headerを使う必要があります。なぜなら、そうしないと、パラメータがクエリのパラメータとして解釈されてしまうからです。
自動変換¶
HeaderはPathやQuery、Cookieが提供する機能に加え、少しだけ追加の機能を持っています。
ほとんどの標準ヘッダーは、「マイナス記号」（-）としても知られる「ハイフン」で区切られています。
しかし、user-agentのような変数はPythonでは無効です。
そのため、デフォルトでは、Headerはパラメータの文字をアンダースコア（_）からハイフン（-）に変換して、ヘッダーを抽出して文書化します。
また、HTTPヘッダは大文字小文字を区別しないので、Pythonの標準スタイル（別名「スネークケース」）で宣言することができます。
そのため、User_Agentなどのように最初の文字を大文字にする必要はなく、通常のPythonコードと同じようにuser_agentを使用することができます。
もしなんらかの理由でアンダースコアからハイフンへの自動変換を無効にする必要がある場合は、Headerのconvert_underscoresにFalseを設定してください:
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}
🤓 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 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}
注意
convert_underscoresをFalseに設定する前に、HTTPプロキシやサーバの中にはアンダースコアを含むヘッダーの使用を許可していないものがあることに注意してください。
ヘッダーの重複¶
受信したヘッダーが重複することがあります。つまり、同じヘッダーで複数の値を持つということです。
これらの場合、リストの型宣言を使用して定義することができます。
重複したヘッダーのすべての値をPythonのlistとして受け取ることができます。
例えば、複数回出現する可能性のあるX-Tokenのヘッダを定義するには、以下のように書くことができます:
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}
🤓 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 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}
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}
もし、そのpath operationで通信する場合は、次のように２つのHTTPヘッダーを送信します:
X-Token: foo
X-Token: bar
このレスポンスは以下のようになります:
{
"X-Token values": [
"bar",
"foo"
]
}
まとめ¶
ヘッダーはHeaderで宣言し、QueryやPath、Cookieと同じパターンを使用する。
また、変数のアンダースコアを気にする必要はありません。FastAPI がそれらの変換をすべて取り持ってくれます。