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
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:
| URL | Der Wert von skip | Wert von limit | Beschreibung |
|---|---|---|---|
/items/ | 0 | 10 | Standardwert verwenden |
/items/?skip=20 | 20 | 10 | skip verwendet den übergebenen Wert, limit verwendet den Standardwert |
/items/?skip=20&limit=5 | 20 | 5 | Beide Parameter verwenden die übergebenen Werte |
Optionale Parameter
Setzen Sie den Standardwert aufNoneSie können optionale Query-Parameter deklarieren:
Beispiel
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
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
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
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:
| Parameter | Deklarationsmethode | Erforderlich? | Beschreibung |
|---|---|---|---|
item_id | item_id: str | Erforderlich | Pfadparameter, die im URL-Pfad vorkommen |
needy | needy: str | Erforderlich | Query-Parameter, kein Standardwert |
skip | skip: int = 0 | Optional | Query-Parameter, mit Standardwert 0 |
limit | limit: int | None = None | Optional | Query-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
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.