FastAPI-Query-Parameter

Query-Parameter befinden sich in der URL?nach, mit&Getrennte Schlüssel-Wert-Paare. Wenn ein Funktionsparameter weder ein Pfadparameter noch ein Request-Body ist, interpretiert FastAPI ihn automatisch als Query-Parameter.


Grundlegende Verwendung

Das Deklarieren von Query-Parametern erfordert nur das Hinzufügen von Typannotationen und Standardwerten zu den Funktionsparametern:

Beispiel

from fastapi import FastAPI

app = FastAPI()

# skip und limit sind Query-Parameter mit Standardwerten
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):
    # Mock-Paginierungsabfrage
    return fake_items_db[skip : skip + limit]

Das Format von Query-Parametern in der URL:

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

Parameterwerte für verschiedene Zugriffsmethoden:

URLDer Wert von skipWert von limitBeschreibung
/items/010Standardwert verwenden
/items/?skip=202010skip verwendet den übergebenen Wert, limit verwendet den Standardwert
/items/?skip=20&limit=5205Beide Parameter verwenden die übergebenen Werte

Optionale Parameter

Setzen Sie den Standardwert aufNoneSie können optionale Query-Parameter deklarieren:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id ist ein Pfadparameter (erforderlich), q ist ein Query-Parameter (optional)
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Hierq: str | None = NoneRepräsentiertqKann eine Zeichenkette sein oderNone, der Standardwert istNone。

FastAPI verwendet Standardwerte= NoneBestimmt, ob ein Parameter erforderlich ist, statt durch Typannotationen.str | None. Typannotationen helfen Editoren hauptsächlich dabei, bessere Unterstützung zu bieten.


Typumwandlung von Query-Parametern

FastAPI unterstützt die automatische Umwandlung von Query-Parametern inboolTyp:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
    # Der Parameter short wird automatisch in einen booleschen Wert umgewandelt
    if short:
        return {"item_id": item_id}
    return {"item_id": item_id, "description": "This is a very long description"}

In der folgenden URL werden dieshortParameter umgewandelt inTrue:

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

Andere Werte werden umgewandelt inFalse。


Erforderlicher Query-Parameter

Query-Parameter ohne Standardwerte sind erforderliche Parameter:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
    # needy hat keinen Standardwert, es ist ein erforderlicher Query-Parameter
    return {"item_id": item_id, "needy": needy}

Wenn zugegriffen wird/items/foowenn nicht angegebenneedyParameter, wird FastAPI einen Fehler ähnlich dem folgenden zurückgeben:

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

Mischen von erforderlichen, mit Standardwerten versehenen und optionalen Parametern

Sie können verschiedene Arten von Query-Parametern in derselben Funktion mischen:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: str,           # Pfadparameter (erforderlich)
    needy: str,             # Erforderliche Query-Parameter
    skip: int = 0,          # Query-Parameter mit Standardwerten
    limit: int | None = None,  # Optionale Query-Parameter
):
    item = {"item_id": item_id, "needy": needy, "skip": skip}
    if limit:
        item.update({"limit": limit})
    return item

Zusammenfassung der Parametertypen:

ParameterDeklarationsmethodeErforderlich?Beschreibung
item_iditem_id: strErforderlichPfadparameter, die im URL-Pfad vorkommen
needyneedy: strErforderlichQuery-Parameter, kein Standardwert
skipskip: int = 0OptionalQuery-Parameter, mit Standardwert 0
limitlimit: int | None = NoneOptionalQuery-Parameter, Standardwert ist None

Mehrere Pfad- und Query-Parameter

FastAPI kann mehrere Pfadparameter und Query-Parameter gleichzeitig erkennen; die Deklarationsreihenfolge der Parameter hat keinen Einfluss auf die Erkennung:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int,       # Pfadparameter
    item_id: str,       # Pfadparameter
    q: str | None = None,  # Optionale Abfrageparameter
    short: bool = False,   # Abfrageparameter mit Standardwerten
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update({"description": "Dies ist eine sehr lange Beschreibung"})
    return item

FastAPI gleicht Variablen im Pfad anhand des Parameternamens ab, daher spielt die Reihenfolge der Funktionsparameter keine Rolle.


Zusammenfassung

Wichtige Punkte zu Abfrageparametern:

  • Parameter mit Standardwerten sind optional, und die ohne Standardwerte sind erforderlich.
  • FastAPI konvertiert Zeichenfolgen in der URL automatisch in den deklarierten Typ.
  • boolType unterstützt mehrere Syntaxvarianten (true、1、on、yesusw.)
  • Abfrageparameter können mit Pfadparametern gemischt werden; die Reihenfolge spielt keine Rolle.
Weitere Erweiterungen