fastapi/docs/ja/docs/tutorial/body-multiple-params.md

ボディ - 複数のパラメータ

これまでPathとQueryをどう使うかを見てきましたが、リクエストボディ宣言のより高度な使い方を見てみましょう。

Path、Queryとボディパラメータを混ぜる

まず、もちろん、PathとQueryとリクエストボディのパラメータ宣言は自由に混ぜることができ、 FastAPI は何をするべきかを知っています。

また、デフォルトをNoneに設定することで、ボディパラメータをオプションとして宣言することもできます:

{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}

/// note | 備考

この場合、ボディから取得するitemはオプションであることに注意してください。デフォルト値がNoneになっているためです。

///

複数のボディパラメータ

上述の例では、path operationsはItemの属性を持つ以下のようなJSONボディを期待していました:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2
}

しかし、itemとuserのように複数のボディパラメータを宣言することもできます:

{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}

この場合、FastAPIは関数内に複数のボディパラメータがあることに気付きます（Pydanticモデルである2つのパラメータがあります）。

そのため、パラメータ名をボディのキー（フィールド名）として使用し、以下のようなボディを期待します:

{
    "item": {
        "name": "Foo",
        "description": "The pretender",
        "price": 42.0,
        "tax": 3.2
    },
    "user": {
        "username": "dave",
        "full_name": "Dave Grohl"
    }
}

/// note | 備考

以前と同じようにitemが宣言されていたにもかかわらず、itemはキーitemを持つボディの内部にあることが期待されていることに注意してください。

///

FastAPI はリクエストから自動で変換を行い、パラメータitemが特定の内容を受け取り、userも同じように特定の内容を受け取ります。

複合データの検証を行い、OpenAPIスキーマや自動ドキュメントのように文書化してくれます。

ボディ内の単数値

クエリとパスパラメータの追加データを定義するための Query と Path があるのと同じように、 FastAPI は同等の Body を提供します。

例えば、前のモデルを拡張して、同じボディに item と user の他にもう一つのキー importance を入れたいと決めることができます。

単数値なのでそのまま宣言すると、FastAPI はそれがクエリパラメータであるとみなします。

しかし、Bodyを使用して、FastAPI に別のボディキーとして扱うように指示することができます:

{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}

この場合、FastAPI は以下のようなボディを期待します:

{
    "item": {
        "name": "Foo",
        "description": "The pretender",
        "price": 42.0,
        "tax": 3.2
    },
    "user": {
        "username": "dave",
        "full_name": "Dave Grohl"
    },
    "importance": 5
}

繰り返しになりますが、データ型の変換、検証、文書化などを行います。

複数のボディパラメータとクエリ

もちろん、ボディパラメータに加えて、必要に応じて追加のクエリパラメータを宣言することもできます。

デフォルトでは、単数値はクエリパラメータとして解釈されるので、明示的に Query を追加する必要はなく、次のようにできます:

q: str | None = None

またはPython 3.10以上では:

q: Union[str, None] = None

例えば:

{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}

/// info | 情報

Bodyもまた、後述する Query や Path などと同様に、すべての追加検証パラメータとメタデータパラメータを持っています。

///

単一のボディパラメータの埋め込み

PydanticモデルItemの単一のitemボディパラメータしかないとしましょう。

デフォルトでは、FastAPIはそのボディを直接期待します。

しかし、追加のボディパラメータを宣言したときのように、キー item を持つ JSON と、その中のモデル内容を期待したい場合は、特別な Body パラメータ embed を使うことができます:

item: Item = Body(embed=True)

以下において:

{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}

この場合、FastAPI は以下のようなボディを期待します:

{
    "item": {
        "name": "Foo",
        "description": "The pretender",
        "price": 42.0,
        "tax": 3.2
    }
}

以下の代わりに:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2
}

まとめ

リクエストが単一のボディしか持てない場合でも、path operation functionに複数のボディパラメータを追加することができます。

しかし、FastAPI はそれを処理し、関数内の正しいデータを与え、path operation内の正しいスキーマを検証し、文書化します。

また、ボディの一部として受け取る単数値を宣言することもできます。

また、単一のパラメータしか宣言されていない場合でも、ボディをキーに埋め込むように FastAPI に指示することができます。