Тело запроса — несколько параметров¶
Теперь, когда мы увидели, как использовать Path и Query, давайте рассмотрим более продвинутые способы объявления тела запроса.
Смешивание параметров Path, Query и тела запроса¶
Во-первых, конечно, вы можете свободно смешивать объявления параметров Path, Query и тела запроса, и FastAPI будет знать, что делать.
А также вы можете объявлять параметры тела как необязательные, установив значение по умолчанию None:
from typing import Annotated
from fastapi import FastAPI, Path
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(
item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
q: str | None = None,
item: Item | None = None,
):
results = {"item_id": item_id}
if q:
results.update({"q": q})
if item:
results.update({"item": item})
return results
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
from fastapi import FastAPI, Path
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(
*,
item_id: int = Path(title="The ID of the item to get", ge=0, le=1000),
q: str | None = None,
item: Item | None = None,
):
results = {"item_id": item_id}
if q:
results.update({"q": q})
if item:
results.update({"item": item})
return results
Примечание
Обратите внимание, что в этом случае item, который будет взят из тела запроса, является необязательным. Поскольку у него значение по умолчанию None.
Несколько параметров тела запроса¶
В предыдущем примере операции пути ожидали бы JSON-тело с атрибутами Item, например:
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
Но вы также можете объявить несколько параметров тела, например item и user:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
class User(BaseModel):
username: str
full_name: str | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, user: User):
results = {"item_id": item_id, "item": item, "user": user}
return results
В этом случае FastAPI заметит, что в функции больше одного параметра тела (есть два параметра, которые являются моделями Pydantic).
Поэтому он будет использовать имена параметров в качестве ключей (имён полей) в теле запроса и ожидать тело вида:
{
"item": {
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
},
"user": {
"username": "dave",
"full_name": "Dave Grohl"
}
}
Примечание
Обратите внимание: хотя item был объявлен так же, как и раньше, теперь ожидается, что он будет внутри тела запроса с ключом item.
FastAPI выполнит автоматическое преобразование из запроса, так что параметр item получит своё конкретное содержимое, и то же самое для user.
Он выполнит валидацию составных данных и задокументирует это соответствующим образом для схемы OpenAPI и автоматической документации.
Единичные значения в теле запроса¶
Точно так же, как есть Query и Path для определения дополнительных данных для параметров запроса и пути, FastAPI предоставляет эквивалентный Body.
Например, расширяя предыдущую модель, вы могли бы решить, что хотите иметь ещё один ключ importance в том же теле запроса, помимо item и user.
Если вы объявите его как есть, поскольку это единичное значение, FastAPI предположит, что это параметр запроса.
Но вы можете указать FastAPI рассматривать его как ещё один ключ тела запроса, используя Body:
from typing import Annotated
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
class User(BaseModel):
username: str
full_name: str | None = None
@app.put("/items/{item_id}")
async def update_item(
item_id: int, item: Item, user: User, importance: Annotated[int, Body()]
):
results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
return results
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
class User(BaseModel):
username: str
full_name: str | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, user: User, importance: int = Body()):
results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
return results
В этом случае 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
Например:
from typing import Annotated
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
class User(BaseModel):
username: str
full_name: str | None = None
@app.put("/items/{item_id}")
async def update_item(
*,
item_id: int,
item: Item,
user: User,
importance: Annotated[int, Body(gt=0)],
q: str | None = None,
):
results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
if q:
results.update({"q": q})
return results
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
class User(BaseModel):
username: str
full_name: str | None = None
@app.put("/items/{item_id}")
async def update_item(
*,
item_id: int,
item: Item,
user: User,
importance: int = Body(gt=0),
q: str | None = None,
):
results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
if q:
results.update({"q": q})
return results
Примечание
Body также имеет все те же параметры дополнительной валидации и метаданных, что и Query, Path и другие, которые вы увидите позже.
Встраивание одного параметра тела запроса¶
Допустим, у вас есть только один параметр тела запроса item из модели Pydantic Item.
По умолчанию FastAPI будет ожидать его тело напрямую.
Но если вы хотите, чтобы он ожидал JSON с ключом item, внутри которого содержится модель, как это происходит, когда вы объявляете дополнительные параметры тела, вы можете использовать специальный параметр Body embed:
item: Annotated[Item, Body(embed=True)]
как в:
from typing import Annotated
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
results = {"item_id": item_id, "item": item}
return results
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(embed=True)):
results = {"item_id": item_id, "item": item}
return results
В этом случае FastAPI будет ожидать тело вида:
{
"item": {
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
}
вместо:
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
Итог¶
Вы можете добавить несколько параметров тела в вашу функцию операции пути, хотя запрос может иметь только одно тело.
Но FastAPI справится с этим, передаст вам правильные данные в вашу функцию и провалидирует и задокументирует правильную схему в операции пути.
Вы также можете объявлять единичные значения, которые должны приниматься как часть тела запроса.
И вы можете указать FastAPI встроить тело запроса в ключ, даже если объявлен только один параметр.