Modelos de Parâmetros de Consulta¶

Se você possui um grupo de parâmetros de consultas que são relacionados, você pode criar um modelo Pydantic para declará-los.

Isso permitiria que você reutilizasse o modelo em diversos lugares, e também declarasse validações e metadados de todos os parâmetros de uma única vez. 😎

Parâmetros de Consulta com um Modelo Pydantic¶

Declare os parâmetros de consulta que você precisa em um modelo Pydantic, e então declare o parâmetro como Query:

fromtypingimport Annotated, Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(BaseModel):
 limit: int = Field(100, gt=0, le=100)
 offset: int = Field(0, ge=0)
 order_by: Literal["created_at", "updated_at"] = "created_at"
 tags: list[str] = []
@app.get("/items/")
async defread_items(filter_query: Annotated[FilterParams, Query()]):
 return filter_query

fromtypingimport Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(BaseModel):
 limit: int = Field(100, gt=0, le=100)
 offset: int = Field(0, ge=0)
 order_by: Literal["created_at", "updated_at"] = "created_at"
 tags: list[str] = []
@app.get("/items/")
async defread_items(filter_query: FilterParams = Query()):
 return filter_query

O FastAPI extrairá os dados para cada campo dos parâmetros de consulta presentes na requisição, e fornecerá o modelo Pydantic que você definiu.

Verifique a Documentação¶

Você pode ver os parâmetros de consulta na IU da documentação em /docs:

Restrinja Parâmetros de Consulta Extras¶

Em alguns casos especiais (provavelmente não muito comuns), você queira restringir os parâmetros de consulta que deseja receber.

Você pode usar a configuração do modelo Pydantic para forbid qualquer campo extra:

fromtypingimport Annotated, Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(BaseModel):
 model_config = {"extra": "forbid"}
 limit: int = Field(100, gt=0, le=100)
 offset: int = Field(0, ge=0)
 order_by: Literal["created_at", "updated_at"] = "created_at"
 tags: list[str] = []
@app.get("/items/")
async defread_items(filter_query: Annotated[FilterParams, Query()]):
 return filter_query

fromtypingimport Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(BaseModel):
 model_config = {"extra": "forbid"}
 limit: int = Field(100, gt=0, le=100)
 offset: int = Field(0, ge=0)
 order_by: Literal["created_at", "updated_at"] = "created_at"
 tags: list[str] = []
@app.get("/items/")
async defread_items(filter_query: FilterParams = Query()):
 return filter_query

Caso um cliente tente enviar alguns dados extras nos parâmetros de consulta, eles receberão um retorno de erro.

Por exemplo, se o cliente tentar enviar um parâmetro de consulta tool com o valor plumbus, como:

https://example.com/items/?limit=10&tool=plumbus

Eles receberão um retorno de erro informando-os que o parâmetro de consulta tool não é permitido:

{
"detail":[
{
"type":"extra_forbidden",
"loc":["query","tool"],
"msg":"Extra inputs are not permitted",
"input":"plumbus"
}
]
}

Resumo¶

Você pode utilizar modelos Pydantic para declarar parâmetros de consulta no FastAPI. 😎