Parámetros de consulta de FastAPI

Los parámetros de consulta son en la URL?después, y mediante&pares clave-valor separados. Cuando un parámetro de función no es un parámetro de ruta ni un cuerpo de solicitud, FastAPI lo interpreta automáticamente como un parámetro de consulta.

Uso básico

Para declarar parámetros de consulta, solo necesita agregar anotaciones de tipo y valores predeterminados en los parámetros de la función:

Ejemplo

from fastapi import FastAPI

app = FastAPI()

# skip y limit son parámetros de consulta, con valores predeterminados
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    # Simula una consulta paginada
    return fake_items_db[skip : skip + limit]

Formato de los parámetros de consulta en la URL:

http://127.0.0.1:8000/items/?skip=0&limit=10

Valores de los parámetros según diferentes formas de acceso:

URLValor de skipValor de limitDescripción
/items/010Usa el valor predeterminado
/items/?skip=202010skip usa el valor pasado, limit usa el valor predeterminado
/items/?skip=20&limit=5205Ambos parámetros usan los valores pasados

Parámetros opcionales

Establezca el valor predeterminado enNonepara declarar un parámetro de consulta opcional:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id es un parámetro de ruta (obligatorio), q es un parámetro de consulta (opcional)
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Aquíq: str | None = Nonesignificaqpuede ser una cadena oNone, el valor predeterminado esNone。

FastAPI, mediante el valor predeterminado,= Nonedetermina si el parámetro es obligatorio, en lugar de mediante la anotación de tipostr | None. Las anotaciones de tipo sirven principalmente para que el editor brinde un mejor soporte.

Conversión de tipos de parámetros de consulta

FastAPI admite la conversión automática de los parámetros de consulta al tipobooltipo:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
    # el parámetro short se convertirá automáticamente a booleano
    if short:
        return {"item_id": item_id}
    return {"item_id": item_id, "description": "Esta es una descripción muy larga"}

En las siguientes URL, losshortparámetros se convertirán todos aTrue：

/items/foo?short=1
/items/foo?short=True
/items/foo?short=true
/items/foo?short=on
/items/foo?short=yes

Los demás valores se convertirán aFalse。

Parámetros de consulta obligatorios

Los parámetros de consulta sin valor predeterminado son parámetros obligatorios:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
    # needy no tiene valor predeterminado, es un parámetro de consulta obligatorio
    return {"item_id": item_id, "needy": needy}

Si al acceder a/items/foono se proporcionaneedyparámetro, FastAPI devolverá un error similar al siguiente:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "needy"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Mezcla de parámetros obligatorios, con valores predeterminados y opcionales

Puede mezclar diferentes tipos de parámetros de consulta en la misma función:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: str,           # Parámetro de ruta (obligatorio)
    needy: str,             # Parámetro de consulta obligatorio
    skip: int = 0,          # Parámetro de consulta con valor predeterminado
    limit: int | None = None,  # Parámetro de consulta opcional
):
    item = {"item_id": item_id, "needy": needy, "skip": skip}
    if limit:
        item.update({"limit": limit})
    return item

Resumen de tipos de parámetros:

ParámetroForma de declaración¿Obligatorio?Descripción
item_iditem_id: strObligatorioParámetro de ruta, aparece en la ruta de la URL
needyneedy: strObligatorioParámetro de consulta, sin valor predeterminado
skipskip: int = 0OpcionalParámetro de consulta, con valor predeterminado 0
limitlimit: int | None = NoneOpcionalParámetro de consulta, valor predeterminado None

Múltiples parámetros de ruta y de consulta

FastAPI puede reconocer múltiples parámetros de ruta y de consulta al mismo tiempo; el orden de declaración de los parámetros no afecta el reconocimiento:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int,       # Parámetro de ruta
    item_id: str,       # Parámetro de ruta
    q: str | None = None,  # Parámetro de consulta opcional
    short: bool = False,   # Parámetro de consulta con valor predeterminado
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update({"description": "Esta es una descripción muy larga"})
    return item

FastAPI empareja las variables en la ruta mediante los nombres de los parámetros, por lo que el orden de los parámetros de la función no importa.

Resumen

Puntos clave de los parámetros de consulta:

  • Los parámetros con valor predeterminado son opcionales; los que no tienen valor predeterminado son obligatorios
  • FastAPI convierte automáticamente las cadenas de la URL al tipo declarado
  • boolEl tipo admite múltiples formas de escritura (true、1、on、yesetc.)
  • Los parámetros de consulta se pueden mezclar con los parámetros de ruta; el orden no importa
Otras extensiones