Python Academy · Aula

Parâmetros de caminho, parâmetros de consulta e corpos de requisição

Defina parâmetros tipados e esquemas de corpo de requisição com Pydantic.

Parâmetros de caminho, parâmetros de consulta e corpos de requisição é uma aula grátis de Python Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Python Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Python Academy inclui 4 aulas no total.

Validação de parâmetros de caminho

Adicione validadores aos parâmetros de caminho usando Path(): defina as restrições ge, le, gt e lt.

from fastapi import FastAPI, Path
app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int = Path(ge=1, le=1000)):
    return {"item_id": item_id}

# GET /items/0  → 422 (must be >= 1)

Validação de parâmetros de consulta

Use Query() para adicionar validação, valores padrão, aliases e descrições aos parâmetros de consulta.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/search")
def search(
    q: str = Query(min_length=2, max_length=50),
    page: int = Query(default=1, ge=1),
):
    return {"q": q, "page": page}

Parâmetros de consulta opcionais

Use | None = None (Python 3.10+) ou Optional[str] = None para tornar um parâmetro de consulta opcional.

from fastapi import FastAPI
app = FastAPI()

@app.get("/users")
def list_users(
    dept: str | None = None,
    active: bool = True
):
    return {"dept": dept, "active": active}

# GET /users → dept=None, active=True
# GET /users?dept=HR&active=false

Vários valores para um parâmetro de consulta

Aceite uma lista de valores para um único parâmetro de consulta com list[str] e Query().

from fastapi import FastAPI, Query
from typing import Annotated
app = FastAPI()

@app.get("/filter")
def filter_items(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

# GET /filter?tags=python&tags=web

Corpos de solicitação aninhados

Os modelos Pydantic podem ser aninhados. O FastAPI processa JSON aninhado automaticamente.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class Address(BaseModel):
    street: str
    city: str

class User(BaseModel):
    name: str
    address: Address

@app.post("/users")
def create_user(user: User):
    return user.model_dump()

Restrições de campos no Pydantic

Use Field() dentro de um modelo para adicionar restrições, valores padrão e descrições a campos individuais.

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
    quantity: int = Field(ge=0, default=0, description="Items in stock")

Corpo de solicitação + caminho + consulta juntos

Combine os três tipos de parâmetros em um único ponto de acesso. O FastAPI os diferencia pela posição: o caminho fica na URL, os tipos simples são parâmetros de consulta e os modelos são o corpo.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class ItemUpdate(BaseModel):
    name: str
    price: float

@app.put("/shops/{shop_id}/items/{item_id}")
def update_item(
    shop_id: int,
    item_id: int,
    item: ItemUpdate,
    notify: bool = False,
):
    return {"shop": shop_id, "item": item_id,
            "data": item.model_dump(), "notify": notify}

Envios de arquivos

Use UploadFile e File() para aceitar envios de arquivos. Acesse o conteúdo com await file.read().

from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post("/upload")
async def upload(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "size": len(content)}

Dados de formulário

Use Form() para aceitar dados de formulários HTML (application/x-www-form-urlencoded ou multipart/form-data).

# pip install python-multipart
from fastapi import FastAPI, Form
app = FastAPI()

@app.post("/login")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

Resumo da validação de solicitações

O FastAPI valida automaticamente todos os tipos de parâmetros. Entradas inválidas retornam HTTP 422 com um erro detalhado antes que o seu manipulador seja chamado.

# Auto-validated:
# - Path params: type coercion, Path() constraints
# - Query params: Query() constraints, type coercion
# - Request body: Pydantic model validation
# - All errors → HTTP 422 Unprocessable Entity
# - No manual validation needed

Alias e obsolescência

Use alias= em Query() ou Field() para aceitar um nome diferente na solicitação e deprecated=True para marcar parâmetros antigos.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/items")
def get_items(
    q: str | None = Query(default=None, alias="search-query"),
    old: str | None = Query(default=None, deprecated=True),
):
    return {"q": q, "old": old}

# GET /items?search-query=python

Verificação rápida

Como o FastAPI diferencia um parâmetro de caminho, um parâmetro de consulta e um corpo de solicitação?

Recapitulação

Use Path()/Query() para definir restrições de parâmetros. Aninhe modelos Pydantic para corpos complexos. Combine livremente parâmetros de caminho, consulta e corpo. UploadFile lida com arquivos; Form() lida com formulários HTML. O FastAPI valida tudo antes de executar o seu manipulador.

Perguntas Frequentes

A aula “Parâmetros de caminho, parâmetros de consulta e corpos de requisição” é grátis?

Sim — o texto completo de “Parâmetros de caminho, parâmetros de consulta e corpos de requisição” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Python Academy, atualize para CoddyKit PRO. O curso de Python Academy inclui 4 aulas no total.

O que vou aprender em “Parâmetros de caminho, parâmetros de consulta e corpos de requisição”?

Defina parâmetros tipados e esquemas de corpo de requisição com Pydantic. Você pratica Python Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Python Academy?

Nenhuma experiência prévia é necessária. Python Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Parâmetros de caminho, parâmetros de consulta e corpos de requisição”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Python Academy?

Sim. Cada aula de Python Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Configuração de projeto FastAPI e primeiro endpoint
Parâmetros de caminho, parâmetros de consulta e corpos de requisição
Injeção de dependências e autenticação
Endpoints assíncronos e integração com banco de dados

← Voltar para Python Academy