ヘッダーのパラメータ¶
🌐 Translation by AI and humans
This translation was made by AI guided by humans. 🤝
It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖
You can improve this translation by helping us guide the AI LLM better.
ヘッダーのパラメータは、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}
🤓 Other versions and variants
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}
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}
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}
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}
🤓 Other versions and variants
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}
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}
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}
技術詳細
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 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}
🤓 Other versions and variants
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}
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}
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}
注意
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}
🤓 Other versions and variants
from typing import Annotated, 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}
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と通信する際に、次のように2つのHTTPヘッダーを送信する場合:
X-Token: foo
X-Token: bar
レスポンスは以下のようになります:
{
"X-Token values": [
"bar",
"foo"
]
}
まとめ¶
ヘッダーはHeaderで宣言し、QueryやPath、Cookieと同じ共通パターンを使用します。
また、変数のアンダースコアを気にする必要はありません。FastAPI がそれらの変換をすべて取り持ってくれます。