# Zusätzliche Responses in OpenAPI
-/// warning | "Achtung"
+/// warning | Achtung
Dies ist ein eher fortgeschrittenes Thema.
{!../../docs_src/additional_responses/tutorial001.py!}
```
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass Sie die `JSONResponse` direkt zurückgeben müssen.
{!../../docs_src/additional_responses/tutorial002.py!}
```
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass Sie das Bild direkt mit einer `FileResponse` zurückgeben müssen.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// warning | "Achtung"
+/// warning | Achtung
Wenn Sie eine `Response` direkt zurückgeben, wie im obigen Beispiel, wird sie direkt zurückgegeben.
///
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import JSONResponse` verwenden.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Das alles mag gekünstelt wirken. Und es ist möglicherweise noch nicht ganz klar, welchen Nutzen das hat.
{* ../../docs_src/async_tests/test_main.py hl[7] *}
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wie zuvor, wenn Sie den `TestClient` verwenden.
... welches wir verwendet haben, um unsere Requests mit dem `TestClient` zu machen.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass wir async/await mit dem neuen `AsyncClient` verwenden – der Request ist asynchron.
///
-/// warning | "Achtung"
+/// warning | Achtung
Falls Ihre Anwendung auf Lifespan-Events angewiesen ist, der `AsyncClient` löst diese Events nicht aus. Um sicherzustellen, dass sie ausgelöst werden, verwenden Sie `LifespanManager` von <a href="https://github.com/florimondmanca/asgi-lifespan#usage" class="external-link" target="_blank">florimondmanca/asgi-lifespan</a>.
Da die Testfunktion jetzt asynchron ist, können Sie in Ihren Tests neben dem Senden von Requests an Ihre FastAPI-Anwendung jetzt auch andere `async`hrone Funktionen aufrufen (und `await`en), genau so, wie Sie diese an anderer Stelle in Ihrem Code aufrufen würden.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie einen `RuntimeError: Task attached to a different loop` erhalten, wenn Sie asynchrone Funktionsaufrufe in Ihre Tests integrieren (z. B. bei Verwendung von <a href="https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop" class="external-link" target="_blank">MongoDBs MotorClient</a>), dann denken Sie daran, Objekte zu instanziieren, die einen Event Loop nur innerhalb asynchroner Funktionen benötigen, z. B. einen `@app.on_event("startup")`-Callback.
proxy --> server
```
-/// tip | "Tipp"
+/// tip | Tipp
Die IP `0.0.0.0` wird üblicherweise verwendet, um anzudeuten, dass das Programm alle auf diesem Computer/Server verfügbaren IPs abhört.
Falls Sie Hypercorn verwenden, das hat auch die Option `--root-path`.
-/// note | "Technische Details"
+/// note | Technische Details
Die ASGI-Spezifikation definiert einen `root_path` für diesen Anwendungsfall.
Dadurch wird Traefik angewiesen, Port 9999 abzuhören und eine andere Datei `routes.toml` zu verwenden.
-/// tip | "Tipp"
+/// tip | Tipp
Wir verwenden Port 9999 anstelle des Standard-HTTP-Ports 80, damit Sie ihn nicht mit Administratorrechten (`sudo`) ausführen müssen.
}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass, obwohl Sie unter `http://127.0.0.1:8000/app` darauf zugreifen, als `root_path` angezeigt wird `/api/v1`, welches aus der Option `--root-path` stammt.
## Zusätzliche Server
-/// warning | "Achtung"
+/// warning | Achtung
Dies ist ein fortgeschrittener Anwendungsfall. Überspringen Sie das gerne.
}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie den automatisch generierten Server mit dem `URL`-Wert `/api/v1`, welcher vom `root_path` stammt.
<img src="/img/tutorial/behind-a-proxy/image03.png">
-/// tip | "Tipp"
+/// tip | Tipp
Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server.
Und wenn diese `Response` einen JSON-Medientyp (`application/json`) hat, wie es bei `JSONResponse` und `UJSONResponse` der Fall ist, werden die von Ihnen zurückgegebenen Daten automatisch mit jedem Pydantic `response_model` konvertiert (und gefiltert), das Sie im *Pfadoperation-Dekorator* deklariert haben.
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Sie eine Response-Klasse ohne Medientyp verwenden, erwartet FastAPI, dass Ihre Response keinen Inhalt hat, und dokumentiert daher das Format der Response nicht in deren generierter OpenAPI-Dokumentation.
///
-/// tip | "Tipp"
+/// tip | Tipp
Die `ORJSONResponse` ist derzeit nur in FastAPI verfügbar, nicht in Starlette.
{!../../docs_src/custom_response/tutorial003.py!}
```
-/// warning | "Achtung"
+/// warning | Achtung
Eine `Response`, die direkt von Ihrer *Pfadoperation-Funktion* zurückgegeben wird, wird in OpenAPI nicht dokumentiert (zum Beispiel wird der `Content-Type` nicht dokumentiert) und ist in der automatischen interaktiven Dokumentation nicht sichtbar.
Bedenken Sie, dass Sie `Response` verwenden können, um alles andere zurückzugeben, oder sogar eine benutzerdefinierte Unterklasse zu erstellen.
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import HTMLResponse` verwenden.
Eine alternative JSON-Response mit <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>.
-/// warning | "Achtung"
+/// warning | Achtung
`ujson` ist bei der Behandlung einiger Sonderfälle weniger sorgfältig als Pythons eingebaute Implementierung.
{!../../docs_src/custom_response/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Möglicherweise ist `ORJSONResponse` eine schnellere Alternative.
Auf diese Weise können wir das Ganze in einen `with`-Block einfügen und so sicherstellen, dass das dateiartige Objekt nach Abschluss geschlossen wird.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass wir, da wir Standard-`open()` verwenden, welches `async` und `await` nicht unterstützt, hier die Pfadoperation mit normalen `def` deklarieren.
{!../../docs_src/custom_response/tutorial010.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie können dennoch weiterhin `response_class` in *Pfadoperationen* überschreiben, wie bisher.
Und dann, direkt nach dem `yield`, entladen wir das Modell. Dieser Code wird unmittelbar vor dem *Herunterfahren* ausgeführt, **nachdem** die Anwendung **die Bearbeitung von Requests abgeschlossen hat**. Dadurch könnten beispielsweise Ressourcen wie Arbeitsspeicher oder eine GPU freigegeben werden.
-/// tip | "Tipp"
+/// tip | Tipp
Das *Herunterfahren* würde erfolgen, wenn Sie die Anwendung **stoppen**.
## Alternative Events (deprecated)
-/// warning | "Achtung"
+/// warning | Achtung
Der empfohlene Weg, das *Hochfahren* und *Herunterfahren* zu handhaben, ist die Verwendung des `lifespan`-Parameters der `FastAPI`-App, wie oben beschrieben. Wenn Sie einen `lifespan`-Parameter übergeben, werden die `startup`- und `shutdown`-Eventhandler nicht mehr aufgerufen. Es ist entweder alles `lifespan` oder alles Events, nicht beides.
///
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass wir in diesem Fall eine Standard-Python-Funktion `open()` verwenden, die mit einer Datei interagiert.
<img src="/img/tutorial/generate-clients/image03.png">
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie die automatische Vervollständigung für `name` und `price`, welche in der FastAPI-Anwendung im `Item`-Modell definiert wurden.
In den nächsten Abschnitten sehen Sie weitere Optionen, Konfigurationen und zusätzliche Funktionen.
-/// tip | "Tipp"
+/// tip | Tipp
Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
**FastAPI** enthält mehrere Middlewares für gängige Anwendungsfälle. Wir werden als Nächstes sehen, wie man sie verwendet.
-/// note | "Technische Details"
+/// note | Technische Details
Für die nächsten Beispiele könnten Sie auch `from starlette.middleware.something import SomethingMiddleware` verwenden.
{!../../docs_src/openapi_callbacks/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Der Query-Parameter `callback_url` verwendet einen Pydantic-<a href="https://docs.pydantic.dev/latest/api/networks/" class="external-link" target="_blank">Url</a>-Typ.
In diesem Beispiel wird nicht der Callback selbst implementiert (das könnte nur eine Codezeile sein), sondern nur der Dokumentationsteil.
-/// tip | "Tipp"
+/// tip | Tipp
Der eigentliche Callback ist nur ein HTTP-Request.
Daher werden wir dasselbe Wissen nutzen, um zu dokumentieren, wie die *externe API* aussehen sollte ... indem wir die *Pfadoperation(en)* erstellen, welche die externe API implementieren soll (die, welche Ihre API aufruft).
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie den Code zum Dokumentieren eines Callbacks schreiben, kann es hilfreich sein, sich vorzustellen, dass Sie dieser *externe Entwickler* sind. Und dass Sie derzeit die *externe API* implementieren, nicht *Ihre API*.
}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass die verwendete Callback-URL die URL enthält, die als Query-Parameter in `callback_url` (`https://www.external.org/events`) empfangen wurde, und auch die Rechnungs-`id` aus dem JSON-Body (`2expen51ve`).
{!../../docs_src/openapi_callbacks/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass Sie nicht den Router selbst (`invoices_callback_router`) an `callback=` übergeben, sondern das Attribut `.routes`, wie in `invoices_callback_router.routes`.
## OpenAPI operationId
-/// warning | "Achtung"
+/// warning | Achtung
Wenn Sie kein „Experte“ für OpenAPI sind, brauchen Sie dies wahrscheinlich nicht.
{!../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie `app.openapi()` manuell aufrufen, sollten Sie vorher die `operationId`s aktualisiert haben.
///
-/// warning | "Achtung"
+/// warning | Achtung
Wenn Sie dies tun, müssen Sie sicherstellen, dass jede Ihrer *Pfadoperation-Funktionen* einen eindeutigen Namen hat.
Wenn Sie in Ihrer Anwendung eine *Pfadoperation* deklarieren, generiert **FastAPI** automatisch die relevanten Metadaten dieser *Pfadoperation*, die in das OpenAPI-Schema aufgenommen werden sollen.
-/// note | "Technische Details"
+/// note | Technische Details
In der OpenAPI-Spezifikation wird das <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Operationsobjekt</a> genannt.
Dieses *Pfadoperation*-spezifische OpenAPI-Schema wird normalerweise automatisch von **FastAPI** generiert, Sie können es aber auch erweitern.
-/// tip | "Tipp"
+/// tip | Tipp
Dies ist ein Low-Level Erweiterungspunkt.
///
-/// tip | "Tipp"
+/// tip | Tipp
Hier verwenden wir dasselbe Pydantic-Modell wieder.
{!../../docs_src/response_cookies/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass, wenn Sie eine Response direkt zurückgeben, anstatt den `Response`-Parameter zu verwenden, FastAPI diese direkt zurückgibt.
### Mehr Informationen
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden.
Tatsächlich können Sie jede `Response` oder jede Unterklasse davon zurückgeben.
-/// tip | "Tipp"
+/// tip | Tipp
`JSONResponse` selbst ist eine Unterklasse von `Response`.
{!../../docs_src/response_directly/tutorial001.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import JSONResponse` verwenden.
{!../../docs_src/response_headers/tutorial001.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden.
Neben den in [Tutorial – Benutzerhandbuch: Sicherheit](../../tutorial/security/index.md){.internal-link target=_blank} behandelten Funktionen gibt es noch einige zusätzliche Funktionen zur Handhabung der Sicherheit.
-/// tip | "Tipp"
+/// tip | Tipp
Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
In diesem Abschnitt erfahren Sie, wie Sie Authentifizierung und Autorisierung mit demselben OAuth2, mit Scopes in Ihrer **FastAPI**-Anwendung verwalten.
-/// warning | "Achtung"
+/// warning | Achtung
Dies ist ein mehr oder weniger fortgeschrittener Abschnitt. Wenn Sie gerade erst anfangen, können Sie ihn überspringen.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Und wir geben die Scopes als Teil des JWT-Tokens zurück.
-/// danger | "Gefahr"
+/// danger | Gefahr
Der Einfachheit halber fügen wir hier die empfangenen Scopes direkt zum Token hinzu.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
In diesem Fall erfordert sie den Scope `me` (sie könnte mehr als einen Scope erfordern).
-/// note | "Hinweis"
+/// note | Hinweis
Sie müssen nicht unbedingt an verschiedenen Stellen verschiedene Scopes hinzufügen.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// info | "Technische Details"
+/// info | Technische Details
`Security` ist tatsächlich eine Unterklasse von `Depends` und hat nur noch einen zusätzlichen Parameter, den wir später kennenlernen werden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
* `security_scopes.scopes` enthält `["me"]` für die *Pfadoperation* `read_users_me`, da das in der Abhängigkeit `get_current_active_user` deklariert ist.
* `security_scopes.scopes` wird `[]` (nichts) für die *Pfadoperation* `read_system_status` enthalten, da diese keine `Security` mit `scopes` deklariert hat, und deren Abhängigkeit `get_current_user` ebenfalls keinerlei `scopes` deklariert.
-/// tip | "Tipp"
+/// tip | Tipp
Das Wichtige und „Magische“ hier ist, dass `get_current_user` für jede *Pfadoperation* eine andere Liste von `scopes` hat, die überprüft werden.
Am sichersten ist der „Code“-Flow, die Implementierung ist jedoch komplexer, da mehr Schritte erforderlich sind. Da er komplexer ist, schlagen viele Anbieter letztendlich den „Implicit“-Flow vor.
-/// note | "Hinweis"
+/// note | Hinweis
Es ist üblich, dass jeder Authentifizierungsanbieter seine Flows anders benennt, um sie zu einem Teil seiner Marke zu machen.
## Umgebungsvariablen
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie bereits wissen, was „Umgebungsvariablen“ sind und wie man sie verwendet, können Sie gerne mit dem nächsten Abschnitt weiter unten fortfahren.
print(f"Hello {name} from Python")
```
-/// tip | "Tipp"
+/// tip | Tipp
Das zweite Argument für <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> ist der zurückzugebende Defaultwert.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Weitere Informationen dazu finden Sie unter <a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a>.
////
-/// tip | "Tipp"
+/// tip | Tipp
Für ein schnelles Copy-and-paste verwenden Sie nicht dieses Beispiel, sondern das letzte unten.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Um mehrere Umgebungsvariablen für einen einzelnen Befehl festzulegen, trennen Sie diese einfach durch ein Leerzeichen und fügen Sie alle vor dem Befehl ein.
{!../../docs_src/settings/app01/main.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie benötigen außerdem eine Datei `__init__.py`, wie in [Größere Anwendungen – mehrere Dateien](../tutorial/bigger-applications.md){.internal-link target=_blank} gesehen.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Wir werden das `@lru_cache` in Kürze besprechen.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Diese Praxis ist so weit verbreitet, dass sie einen Namen hat. Diese Umgebungsvariablen werden üblicherweise in einer Datei `.env` abgelegt und die Datei wird „dotenv“ genannt.
-/// tip | "Tipp"
+/// tip | Tipp
Eine Datei, die mit einem Punkt (`.`) beginnt, ist eine versteckte Datei in Unix-ähnlichen Systemen wie Linux und macOS.
Pydantic unterstützt das Lesen dieser Dateitypen mithilfe einer externen Bibliothek. Weitere Informationen finden Sie unter <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support" class="external-link" target="_blank">Pydantic Settings: Dotenv (.env) support</a>.
-/// tip | "Tipp"
+/// tip | Tipp
Damit das funktioniert, müssen Sie `pip install python-dotenv` ausführen.
{!> ../../docs_src/settings/app03_an/config.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter <a href="https://docs.pydantic.dev/latest/concepts/config/" class="external-link" target="_blank">Pydantic: Configuration</a>.
{!> ../../docs_src/settings/app03_an/config_pv1.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Die Klasse `Config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
{!../../docs_src/templates/tutorial001.py!}
```
-/// note | "Hinweis"
+/// note | Hinweis
Vor FastAPI 0.108.0 und Starlette 0.29.0 war `name` der erste Parameter.
///
-/// tip | "Tipp"
+/// tip | Tipp
Durch die Deklaration von `response_class=HTMLResponse` kann die Dokumentationsoberfläche erkennen, dass die Response HTML sein wird.
///
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.templating import Jinja2Templates` verwenden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Sie können eine Überschreibung für eine Abhängigkeit festlegen, die an einer beliebigen Stelle in Ihrer **FastAPI**-Anwendung verwendet wird.
app.dependency_overrides = {}
```
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie eine Abhängigkeit nur während einiger Tests überschreiben möchten, können Sie die Überschreibung zu Beginn des Tests (innerhalb der Testfunktion) festlegen und am Ende (am Ende der Testfunktion) zurücksetzen.
{!../../docs_src/app_testing/tutorial002.py!}
```
-/// note | "Hinweis"
+/// note | Hinweis
Weitere Informationen finden Sie in der Starlette-Dokumentation zum <a href="https://www.starlette.io/testclient/#testing-websocket-sessions" class="external-link" target="_blank">Testen von WebSockets</a>.
Durch die Deklaration eines *Pfadoperation-Funktionsparameters*, dessen Typ der `Request` ist, weiß **FastAPI**, dass es den `Request` diesem Parameter übergeben soll.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass wir in diesem Fall einen Pfad-Parameter zusätzlich zum Request-Parameter deklarieren.
Weitere Details zum <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request`-Objekt finden Sie in der offiziellen Starlette-Dokumentation</a>.
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.requests import Request` verwenden.
{!../../docs_src/websockets/tutorial001.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.websockets import WebSocket` verwenden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
* Die „Item ID“, die im Pfad verwendet wird.
* Das „Token“, das als Query-Parameter verwendet wird.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass der Query-„Token“ von einer Abhängigkeit verarbeitet wird.
Client #1596980209979 left the chat
```
-/// tip | "Tipp"
+/// tip | Tipp
Die obige Anwendung ist ein minimales und einfaches Beispiel, das zeigt, wie Nachrichten verarbeitet und an mehrere WebSocket-Verbindungen gesendet werden.
Es war eines der ersten Beispiele für **automatische API-Dokumentation**, und dies war insbesondere eine der ersten Ideen, welche „die Suche nach“ **FastAPI** inspirierten.
-/// note | "Hinweis"
+/// note | Hinweis
Das Django REST Framework wurde von Tom Christie erstellt. Derselbe Schöpfer von Starlette und Uvicorn, auf denen **FastAPI** basiert.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Eine automatische API-Dokumentationsoberfläche zu haben.
Angesichts der Einfachheit von Flask schien es eine gute Ergänzung zum Erstellen von APIs zu sein. Als Nächstes musste ein „Django REST Framework“ für Flask gefunden werden.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Ein Mikroframework zu sein. Es einfach zu machen, die benötigten Tools und Teile zu kombinieren.
Sehen Sie sich die Ähnlichkeiten in `requests.get(...)` und `@app.get(...)` an.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
* Über eine einfache und intuitive API zu verfügen.
* HTTP-Methodennamen (Operationen) direkt, auf einfache und intuitive Weise zu verwenden.
Aus diesem Grund spricht man bei Version 2.0 häufig von „Swagger“ und ab Version 3 von „OpenAPI“.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Einen offenen Standard für API-Spezifikationen zu übernehmen und zu verwenden, anstelle eines benutzerdefinierten Schemas.
Aber sie wurde erstellt, bevor Typhinweise in Python existierten. Um also ein <abbr title="die Definition, wie Daten geformt sein werden sollen">Schema</abbr> zu definieren, müssen Sie bestimmte Werkzeuge und Klassen verwenden, die von Marshmallow bereitgestellt werden.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Code zu verwenden, um „Schemas“ zu definieren, welche Datentypen und Validierung automatisch bereitstellen.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Eingehende Requestdaten automatisch zu validieren.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Den offenen Standard für APIs, OpenAPI, zu unterstützen.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Das OpenAPI-Schema automatisch zu generieren, aus demselben Code, welcher die Serialisierung und Validierung definiert.
Es kann nicht sehr gut mit verschachtelten Modellen umgehen. Wenn es sich beim JSON-Body in der Anfrage also um ein JSON-Objekt mit inneren Feldern handelt, die wiederum verschachtelte JSON-Objekte sind, kann er nicht richtig dokumentiert und validiert werden.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Python-Typen zu verwenden, um eine hervorragende Editorunterstützung zu erhalten.
Es war eines der ersten extrem schnellen Python-Frameworks, welches auf `asyncio` basierte. Es wurde so gestaltet, dass es Flask sehr ähnlich ist.
-/// note | "Technische Details"
+/// note | Technische Details
Es verwendete <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> anstelle der standardmäßigen Python-`asyncio`-Schleife. Das hat es so schnell gemacht.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Einen Weg zu finden, eine hervorragende Performanz zu haben.
Daher müssen Datenvalidierung, Serialisierung und Dokumentation im Code und nicht automatisch erfolgen. Oder sie müssen als Framework oberhalb von Falcon implementiert werden, so wie Hug. Dieselbe Unterscheidung findet auch in anderen Frameworks statt, die vom Design von Falcon inspiriert sind und ein Requestobjekt und ein Responseobjekt als Parameter haben.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Wege zu finden, eine großartige Performanz zu erzielen.
Routen werden an einer einzigen Stelle deklariert, indem Funktionen verwendet werden, die an anderen Stellen deklariert wurden (anstatt Dekoratoren zu verwenden, welche direkt über der Funktion platziert werden können, welche den Endpunkt verarbeitet). Dies ähnelt eher der Vorgehensweise von Django als der Vorgehensweise von Flask (und Starlette). Es trennt im Code Dinge, die relativ eng miteinander gekoppelt sind.
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Zusätzliche Validierungen für Datentypen zu definieren, mithilfe des „Default“-Werts von Modellattributen. Dies verbessert die Editorunterstützung und war zuvor in Pydantic nicht verfügbar.
///
-/// check | "Ideen, die **FastAPI** inspiriert haben"
+/// check | Ideen, die **FastAPI** inspiriert haben
Hug inspirierte Teile von APIStar und war eines der Tools, die ich am vielversprechendsten fand, neben APIStar.
///
-/// check | "Inspirierte **FastAPI**"
+/// check | Inspirierte **FastAPI**
Zu existieren.
Es ist vergleichbar mit Marshmallow. Obwohl es in Benchmarks schneller als Marshmallow ist. Und da es auf den gleichen Python-Typhinweisen basiert, ist die Editorunterstützung großartig.
-/// check | "**FastAPI** verwendet es, um"
+/// check | **FastAPI** verwendet es, um
Die gesamte Datenvalidierung, Datenserialisierung und automatische Modelldokumentation (basierend auf JSON Schema) zu erledigen.
Das ist eines der wichtigsten Dinge, welche **FastAPI** hinzufügt, alles basierend auf Python-Typhinweisen (mit Pydantic). Das, plus, das Dependency Injection System, Sicherheitswerkzeuge, OpenAPI-Schemagenerierung, usw.
-/// note | "Technische Details"
+/// note | Technische Details
ASGI ist ein neuer „Standard“, welcher von Mitgliedern des Django-Kernteams entwickelt wird. Es handelt sich immer noch nicht um einen „Python-Standard“ (ein PEP), obwohl sie gerade dabei sind, das zu tun.
///
-/// check | "**FastAPI** verwendet es, um"
+/// check | **FastAPI** verwendet es, um
Alle Kern-Webaspekte zu handhaben. Und fügt Funktionen obenauf.
Es ist der empfohlene Server für Starlette und **FastAPI**.
-/// check | "**FastAPI** empfiehlt es als"
+/// check | **FastAPI** empfiehlt es als
Hauptwebserver zum Ausführen von **FastAPI**-Anwendungen.
## Sehr technische Details
-/// warning | "Achtung"
+/// warning | Achtung
Das folgende können Sie wahrscheinlich überspringen.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Aktivieren Sie jedes Mal, wenn Sie ein neues Package mit `pip` in dieser Umgebung installieren, die Umgebung erneut.
Auf diese Weise müssen Sie Ihre lokale Version nicht „installieren“, um jede Änderung testen zu können.
-/// note | "Technische Details"
+/// note | Technische Details
Das geschieht nur, wenn Sie die Installation mit der enthaltenen `requirements.txt` durchführen, anstatt `pip install fastapi` direkt auszuführen.
Auf diese Weise können Sie die Dokumentation/Quelldateien bearbeiten und die Änderungen live sehen.
-/// tip | "Tipp"
+/// tip | Tipp
Alternativ können Sie die Schritte des Skripts auch manuell ausführen.
Und es gibt zusätzliche Tools/Skripte für Übersetzungen, in `./scripts/docs.py`.
-/// tip | "Tipp"
+/// tip | Tipp
Sie müssen sich den Code in `./scripts/docs.py` nicht anschauen, verwenden Sie ihn einfach in der Kommandozeile.
* Sehen Sie diese Pull Requests durch (Review), schlagen Sie Änderungen vor, oder segnen Sie sie ab (Approval). Bei den Sprachen, die ich nicht spreche, warte ich, bis mehrere andere die Übersetzung durchgesehen haben, bevor ich den Pull Request merge.
-/// tip | "Tipp"
+/// tip | Tipp
Sie können <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">Kommentare mit Änderungsvorschlägen</a> zu vorhandenen Pull Requests hinzufügen.
Im Spanischen lautet der Zwei-Buchstaben-Code `es`. Das Verzeichnis für spanische Übersetzungen befindet sich also unter `docs/es/`.
-/// tip | "Tipp"
+/// tip | Tipp
Die Haupt („offizielle“) Sprache ist Englisch und befindet sich unter `docs/en/`.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Alternativ können Sie die Schritte des Skripts auch manuell ausführen.
docs/es/docs/features.md
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass die einzige Änderung in Pfad und Dateiname der Sprachcode ist, von `en` zu `es`.
INHERIT: ../en/mkdocs.yml
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie können diese Datei mit diesem Inhalt auch einfach manuell erstellen.
Aber in den Fällen mit wirklich schwerwiegenden Fehlern, die den laufenden **Prozess** zum Absturz bringen, benötigen Sie eine externe Komponente, die den Prozess **neu startet**, zumindest ein paar Mal ...
-/// tip | "Tipp"
+/// tip | Tipp
... Obwohl es wahrscheinlich keinen Sinn macht, sie immer wieder neu zu starten, wenn die gesamte Anwendung einfach **sofort abstürzt**. Aber in diesen Fällen werden Sie es wahrscheinlich während der Entwicklung oder zumindest direkt nach dem Deployment bemerken.
* **Cloud-Dienste**, welche das für Sie erledigen
* Der Cloud-Dienst wird wahrscheinlich **die Replikation für Sie übernehmen**. Er würde Sie möglicherweise **einen auszuführenden Prozess** oder ein **zu verwendendes Container-Image** definieren lassen, in jedem Fall wäre es höchstwahrscheinlich **ein einzelner Uvicorn-Prozess**, und der Cloud-Dienst wäre auch verantwortlich für die Replikation.
-/// tip | "Tipp"
+/// tip | Tipp
Machen Sie sich keine Sorgen, wenn einige dieser Punkte zu **Containern**, Docker oder Kubernetes noch nicht viel Sinn ergeben.
Natürlich gibt es Fälle, in denen es kein Problem darstellt, die Vorab-Schritte mehrmals auszuführen. In diesem Fall ist die Handhabung viel einfacher.
-/// tip | "Tipp"
+/// tip | Tipp
Bedenken Sie außerdem, dass Sie, abhängig von Ihrer Einrichtung, in manchen Fällen **gar keine Vorab-Schritte** benötigen, bevor Sie die Anwendung starten.
* Ein Bash-Skript, das die Vorab-Schritte ausführt und dann Ihre Anwendung startet
* Sie benötigen immer noch eine Möglichkeit, *dieses* Bash-Skript zu starten/neu zu starten, Fehler zu erkennen, usw.
-/// tip | "Tipp"
+/// tip | Tipp
Konkretere Beispiele hierfür mit Containern gebe ich Ihnen in einem späteren Kapitel: [FastAPI in Containern – Docker](docker.md){.internal-link target=_blank}.
Die Verwendung von Linux-Containern bietet mehrere Vorteile, darunter **Sicherheit**, **Replizierbarkeit**, **Einfachheit** und andere.
-/// tip | "Tipp"
+/// tip | Tipp
Sie haben es eilig und kennen sich bereits aus? Springen Sie zum [`Dockerfile` unten 👇](#ein-docker-image-fur-fastapi-erstellen).
Da das Programm unter `/code` gestartet wird und sich darin das Verzeichnis `./app` mit Ihrem Code befindet, kann **Uvicorn** `app` sehen und aus `app.main` **importieren**.
-/// tip | "Tipp"
+/// tip | Tipp
Lernen Sie, was jede Zeile bewirkt, indem Sie auf die Zahlenblasen im Code klicken. 👆
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie das `.` am Ende, es entspricht `./` und teilt Docker mit, welches Verzeichnis zum Erstellen des Containerimages verwendet werden soll.
Es könnte sich um einen anderen Container handeln, zum Beispiel mit <a href="https://traefik.io/" class="external-link" target="_blank">Traefik</a>, welcher **HTTPS** und **automatischen** Erwerb von **Zertifikaten** handhabt.
-/// tip | "Tipp"
+/// tip | Tipp
Traefik verfügt über Integrationen mit Docker, Kubernetes und anderen, sodass Sie damit ganz einfach HTTPS für Ihre Container einrichten und konfigurieren können.
Da diese Komponente die **Last** an Requests aufnehmen und diese (hoffentlich) **ausgewogen** auf die Worker verteilen würde, wird sie üblicherweise auch **Load Balancer** – Lastverteiler – genannt.
-/// tip | "Tipp"
+/// tip | Tipp
Die gleiche **TLS-Terminierungsproxy**-Komponente, die für HTTPS verwendet wird, wäre wahrscheinlich auch ein **Load Balancer**.
* <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
-/// warning | "Achtung"
+/// warning | Achtung
Es besteht eine hohe Wahrscheinlichkeit, dass Sie dieses oder ein ähnliches Basisimage **nicht** benötigen und es besser wäre, wenn Sie das Image von Grund auf neu erstellen würden, wie [oben beschrieben in: Ein Docker-Image für FastAPI erstellen](#ein-docker-image-fur-fastapi-erstellen).
Es unterstützt auch die Ausführung von <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker#pre_start_path" class="external-link" target="_blank">**Vorab-Schritten vor dem Start** </a> mit einem Skript.
-/// tip | "Tipp"
+/// tip | Tipp
Um alle Konfigurationen und Optionen anzuzeigen, gehen Sie zur Docker-Image-Seite: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
11. Führe den Befehl `uvicorn` aus und weise ihn an, das aus `app.main` importierte `app`-Objekt zu verwenden.
-/// tip | "Tipp"
+/// tip | Tipp
Klicken Sie auf die Zahlenblasen, um zu sehen, was jede Zeile bewirkt.
Aber es ist viel komplexer als das.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie es eilig haben oder es Ihnen egal ist, fahren Sie mit den nächsten Abschnitten fort, um Schritt-für-Schritt-Anleitungen für die Einrichtung der verschiedenen Technologien zu erhalten.
Sie würden dies wahrscheinlich nur einmal tun, beim ersten Mal, wenn Sie alles einrichten.
-/// tip | "Tipp"
+/// tip | Tipp
Dieser Domainnamen-Aspekt liegt weit vor HTTPS, aber da alles von der Domain und der IP-Adresse abhängt, lohnt es sich, das hier zu erwähnen.
Und genau das ist **HTTPS**, es ist einfach **HTTP** innerhalb einer **sicheren TLS-Verbindung**, statt einer puren (unverschlüsselten) TCP-Verbindung.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass die Verschlüsselung der Kommunikation auf der **TCP-Ebene** und nicht auf der HTTP-Ebene erfolgt.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Durch das Hinzufügen von `standard` installiert und verwendet Uvicorn einige empfohlene zusätzliche Abhängigkeiten.
////
-/// warning | "Achtung"
+/// warning | Achtung
Denken Sie daran, die Option `--reload` zu entfernen, wenn Sie diese verwendet haben.
FastAPI folgt auch der Konvention, dass jede „PATCH“-Versionsänderung für Bugfixes und abwärtskompatible Änderungen gedacht ist.
-/// tip | "Tipp"
+/// tip | Tipp
Der „PATCH“ ist die letzte Zahl, zum Beispiel ist in `0.2.3` die PATCH-Version `3`.
Nicht abwärtskompatible Änderungen und neue Funktionen werden in „MINOR“-Versionen hinzugefügt.
-/// tip | "Tipp"
+/// tip | Tipp
„MINOR“ ist die Zahl in der Mitte, zum Beispiel ist in `0.2.3` die MINOR-Version `2`.
Treten Sie dem 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">Discord-Chatserver</a> 👥 bei und treffen Sie sich mit anderen Mitgliedern der FastAPI-Community.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie Fragen haben, stellen Sie sie bei <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">GitHub Diskussionen</a>, es besteht eine viel bessere Chance, dass Sie hier Hilfe von den [FastAPI-Experten](fastapi-people.md#experten){.internal-link target=_blank} erhalten.
{!../../docs_src/custom_docs_ui/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Die *Pfadoperation* für `swagger_ui_redirect` ist ein Hilfsmittel bei der Verwendung von OAuth2.
{!../../docs_src/custom_docs_ui/tutorial002.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Die *Pfadoperation* für `swagger_ui_redirect` ist ein Hilfsmittel bei der Verwendung von OAuth2.
Wenn Sie beispielsweise den Requestbody lesen oder manipulieren möchten, bevor er von Ihrer Anwendung verarbeitet wird.
-/// danger | "Gefahr"
+/// danger | Gefahr
Dies ist eine „fortgeschrittene“ Funktion.
### Eine benutzerdefinierte `GzipRequest`-Klasse erstellen
-/// tip | "Tipp"
+/// tip | Tipp
Dies ist nur ein einfaches Beispiel, um zu demonstrieren, wie es funktioniert. Wenn Sie Gzip-Unterstützung benötigen, können Sie die bereitgestellte [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} verwenden.
{!../../docs_src/custom_request_and_route/tutorial001.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Ein `Request` hat ein `request.scope`-Attribut, welches einfach ein Python-`dict` ist, welches die mit dem Request verbundenen Metadaten enthält.
## Zugriff auf den Requestbody in einem Exceptionhandler
-/// tip | "Tipp"
+/// tip | Tipp
Um dasselbe Problem zu lösen, ist es wahrscheinlich viel einfacher, den `body` in einem benutzerdefinierten Handler für `RequestValidationError` zu verwenden ([Fehlerbehandlung](../tutorial/handling-errors.md#den-requestvalidationerror-body-verwenden){.internal-link target=_blank}).
Sie können normale FastAPI-*Pfadoperationen* mit GraphQL in derselben Anwendung kombinieren.
-/// tip | "Tipp"
+/// tip | Tipp
**GraphQL** löst einige sehr spezifische Anwendungsfälle.
Das wurde von Starlette deprecated, aber wenn Sie Code haben, der das verwendet, können Sie einfach zu <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a> **migrieren**, welches denselben Anwendungsfall abdeckt und über eine **fast identische Schnittstelle** verfügt.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie GraphQL benötigen, würde ich Ihnen trotzdem empfehlen, sich <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a> anzuschauen, da es auf Typannotationen basiert, statt auf benutzerdefinierten Klassen und Typen.
Wenn etwas für Ihr Projekt interessant und nützlich erscheint, lesen Sie es, andernfalls überspringen Sie es einfach.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie strukturiert **FastAPI lernen** möchten (empfohlen), lesen Sie stattdessen Kapitel für Kapitel das [Tutorial – Benutzerhandbuch](../tutorial/index.md){.internal-link target=_blank}.
Aber selbst wenn Sie **FastAPI** nie verwenden, wird es für Sie nützlich sein, ein wenig darüber zu lernen.
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Sie ein Python-Experte sind und bereits alles über Typhinweise wissen, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
////
-/// tip | "Tipp"
+/// tip | Tipp
Die inneren Typen in den eckigen Klammern werden als „Typ-Parameter“ bezeichnet.
Das bedeutet: Die Variable `items` ist eine Liste – `list` – und jedes der Elemente in dieser Liste ist ein String – `str`.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie Python 3.9 oder höher verwenden, müssen Sie `List` nicht von `typing` importieren, Sie können stattdessen den regulären `list`-Typ verwenden.
Viel mehr von all dem werden Sie in praktischer Anwendung im [Tutorial - Benutzerhandbuch](tutorial/index.md){.internal-link target=_blank} sehen.
-/// tip | "Tipp"
+/// tip | Tipp
Pydantic verhält sich speziell, wenn Sie `Optional` oder `Union[Etwas, None]` ohne einen Default-Wert verwenden. Sie können darüber in der Pydantic Dokumentation unter <a href="https://docs.pydantic.dev/2.3/usage/models/#required-fields" class="external-link" target="_blank">Required fields</a> mehr erfahren.
Später werden Sie sehen, wie **mächtig** es sein kann.
-/// tip | "Tipp"
+/// tip | Tipp
Der Umstand, dass es **Standard-Python** ist, bedeutet, dass Sie immer noch die **bestmögliche Entwickler-Erfahrung** in ihrem Editor haben, sowie mit den Tools, die Sie nutzen, um ihren Code zu analysieren, zu refaktorisieren, usw. ✨
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
│ └── admin.py
```
-/// tip | "Tipp"
+/// tip | Tipp
Es gibt mehrere `__init__.py`-Dateien: eine in jedem Verzeichnis oder Unterverzeichnis.
Alle die gleichen `parameters`, `responses`, `dependencies`, `tags`, usw.
-/// tip | "Tipp"
+/// tip | Tipp
In diesem Beispiel heißt die Variable `router`, aber Sie können ihr einen beliebigen Namen geben.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Um dieses Beispiel zu vereinfachen, verwenden wir einen erfundenen Header.
Und wir können eine Liste von `dependencies` hinzufügen, die allen *Pfadoperationen* im Router hinzugefügt und für jeden an sie gerichteten Request ausgeführt/aufgelöst werden.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass ähnlich wie bei [Abhängigkeiten in *Pfadoperation-Dekoratoren*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} kein Wert an Ihre *Pfadoperation-Funktion* übergeben wird.
* Zuerst werden die Router-Abhängigkeiten ausgeführt, dann die [`dependencies` im Dekorator](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} und dann die normalen Parameterabhängigkeiten.
* Sie können auch [`Security`-Abhängigkeiten mit `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank} hinzufügen.
-/// tip | "Tipp"
+/// tip | Tipp
`dependencies` im `APIRouter` können beispielsweise verwendet werden, um eine Authentifizierung für eine ganze Gruppe von *Pfadoperationen* zu erfordern. Selbst wenn die Abhängigkeiten nicht jeder einzeln hinzugefügt werden.
#### Wie relative Importe funktionieren
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie genau wissen, wie Importe funktionieren, fahren Sie mit dem nächsten Abschnitt unten fort.
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Diese letzte Pfadoperation wird eine Kombination von Tags haben: `["items", "custom"]`.
Es wird alle Routen von diesem Router als Teil von dieser inkludieren.
-/// note | "Technische Details"
+/// note | Technische Details
Tatsächlich wird intern eine *Pfadoperation* für jede *Pfadoperation* erstellt, die im `APIRouter` deklariert wurde.
und es wird korrekt funktionieren, zusammen mit allen anderen *Pfadoperationen*, die mit `app.include_router()` hinzugefügt wurden.
-/// info | "Sehr technische Details"
+/// info | Sehr technische Details
**Hinweis**: Dies ist ein sehr technisches Detail, das Sie wahrscheinlich **einfach überspringen** können.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// warning | "Achtung"
+/// warning | Achtung
Beachten Sie, dass `Field` direkt von `pydantic` importiert wird, nicht von `fastapi`, wie die anderen (`Query`, `Path`, `Body`, usw.)
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
`Field` funktioniert genauso wie `Query`, `Path` und `Body`, es hat die gleichen Parameter, usw.
-/// note | "Technische Details"
+/// note | Technische Details
Tatsächlich erstellen `Query`, `Path` und andere, die sie kennenlernen werden, Instanzen von Unterklassen einer allgemeinen Klasse `Param`, die ihrerseits eine Unterklasse von Pydantics `FieldInfo`-Klasse ist.
///
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass jedes Modellattribut mit einem Typ, Defaultwert und `Field` die gleiche Struktur hat wie ein Parameter einer Pfadoperation-Funktion, nur mit `Field` statt `Path`, `Query`, `Body`.
Sie werden später mehr darüber lernen, wie man zusätzliche Information unterbringt, wenn Sie lernen, Beispiele zu deklarieren.
-/// warning | "Achtung"
+/// warning | Achtung
Extra-Schlüssel, die `Field` überreicht werden, werden auch im resultierenden OpenAPI-Schema Ihrer Anwendung gelistet. Da diese Schlüssel nicht notwendigerweise Teil der OpenAPI-Spezifikation sind, könnten einige OpenAPI-Tools, wie etwa [der OpenAPI-Validator](https://validator.swagger.io/), nicht mit Ihrem generierten Schema funktionieren.
{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass in diesem Fall das `item`, welches vom Body genommen wird, optional ist. Da es `None` als Defaultwert hat.
}
```
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass, obwohl `item` wie zuvor deklariert wurde, es nun unter einem Schlüssel `item` im Body erwartet wird.
////
-/// tip | "Tipp"
+/// tip | Tipp
Bedenken Sie, dass JSON nur `str` als Schlüssel unterstützt.
Das bedeutet, sie senden nur die Daten, die Sie aktualisieren wollen, der Rest bleibt unverändert.
-/// note | "Hinweis"
+/// note | Hinweis
`PATCH` wird seltener verwendet und ist weniger bekannt als `PUT`.
////
-/// tip | "Tipp"
+/// tip | Tipp
Sie können tatsächlich die gleiche Technik mit einer HTTP `PUT` Operation verwenden.
///
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass das hereinkommende Modell immer noch validiert wird.
<img src="/img/tutorial/body/image05.png">
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> als Ihren Editor verwenden, probieren Sie das <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a> aus.
* Wenn der Parameter ein **einfacher Typ** ist (wie `int`, `float`, `str`, `bool`, usw.), wird er als **Query**-Parameter interpretiert.
* Wenn der Parameter vom Typ eines **Pydantic-Modells** ist, wird er als Request**body** interpretiert.
-/// note | "Hinweis"
+/// note | Hinweis
FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, wegen des definierten Defaultwertes `= None`
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Technische Details"
+/// note | Technische Details
`Cookie` ist eine Schwesterklasse von `Path` und `Query`. Sie erbt von derselben gemeinsamen `Param`-Elternklasse.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
... und **FastAPI** wird wissen, was zu tun ist.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie das eher verwirrt, als Ihnen zu helfen, ignorieren Sie es, Sie *brauchen* es nicht.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Diese Abhängigkeiten werden auf die gleiche Weise wie normale Abhängigkeiten ausgeführt/aufgelöst. Aber ihr Wert (falls sie einen zurückgeben) wird nicht an Ihre *Pfadoperation-Funktion* übergeben.
-/// tip | "Tipp"
+/// tip | Tipp
Einige Editoren prüfen, ob Funktionsparameter nicht verwendet werden, und zeigen das als Fehler an.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Verwenden Sie dazu `yield` statt `return` und schreiben Sie die zusätzlichen Schritte / den zusätzlichen Code danach.
-/// tip | "Tipp"
+/// tip | Tipp
Stellen Sie sicher, dass Sie `yield` nur einmal pro Abhängigkeit verwenden.
///
-/// note | "Technische Details"
+/// note | Technische Details
Jede Funktion, die dekoriert werden kann mit:
{!../../docs_src/dependencies/tutorial007.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie können `async`hrone oder reguläre Funktionen verwenden.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
**FastAPI** stellt sicher, dass alles in der richtigen Reihenfolge ausgeführt wird.
-/// note | "Technische Details"
+/// note | Technische Details
Dieses funktioniert dank Pythons <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">Kontextmanager</a>.
Auf die gleiche Weise könnten Sie im Exit-Code nach dem `yield` eine `HTTPException` oder ähnliches auslösen.
-/// tip | "Tipp"
+/// tip | Tipp
Dies ist eine etwas fortgeschrittene Technik, die Sie in den meisten Fällen nicht wirklich benötigen, da Sie Exceptions (einschließlich `HTTPException`) innerhalb des restlichen Anwendungscodes auslösen können, beispielsweise in der *Pfadoperation-Funktion*.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
///
-/// tip | "Tipp"
+/// tip | Tipp
Obiges Diagramm verwendet `HTTPException`, aber Sie können auch jede andere Exception auslösen, die Sie in einer Abhängigkeit mit `yield` abfangen, oder mit einem [benutzerdefinierten Exceptionhandler](../handling-errors.md#benutzerdefinierte-exceptionhandler-definieren){.internal-link target=_blank} erstellt haben.
## Abhängigkeiten mit `yield`, `HTTPException` und Hintergrundtasks
-/// warning | "Achtung"
+/// warning | Achtung
Sie benötigen diese technischen Details höchstwahrscheinlich nicht, Sie können diesen Abschnitt überspringen und weiter unten fortfahren.
Da dies jedoch bedeuten würde, darauf zu warten, dass die Response durch das Netzwerk reist, während eine Ressource unnötigerweise in einer Abhängigkeit mit yield gehalten wird (z. B. eine Datenbankverbindung), wurde dies in FastAPI 0.106.0 geändert.
-/// tip | "Tipp"
+/// tip | Tipp
Darüber hinaus handelt es sich bei einem Hintergrundtask normalerweise um einen unabhängigen Satz von Logik, der separat behandelt werden sollte, mit eigenen Ressourcen (z. B. einer eigenen Datenbankverbindung).
### Kontextmanager in Abhängigkeiten mit `yield` verwenden
-/// warning | "Achtung"
+/// warning | Achtung
Dies ist mehr oder weniger eine „fortgeschrittene“ Idee.
{!../../docs_src/dependencies/tutorial010.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Andere Möglichkeiten, einen Kontextmanager zu erstellen, sind:
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Und diese Funktion akzeptiert Parameter auf die gleiche Weise wie *Pfadoperation-Funktionen*.
-/// tip | "Tipp"
+/// tip | Tipp
Im nächsten Kapitel erfahren Sie, welche anderen „Dinge“, außer Funktionen, Sie als Abhängigkeiten verwenden können.
////
-/// tip | "Tipp"
+/// tip | Tipp
Das ist schlicht Standard-Python, es wird als „Typalias“ bezeichnet und ist eigentlich nicht **FastAPI**-spezifisch.
Es spielt keine Rolle. **FastAPI** weiß, was zu tun ist.
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Ihnen das nichts sagt, lesen Sie den [Async: *„In Eile?“*](../../async.md#in-eile){.internal-link target=_blank}-Abschnitt über `async` und `await` in der Dokumentation.
//// tab | Python 3.10 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Dennoch ist es sehr mächtig und ermöglicht Ihnen die Deklaration beliebig tief verschachtelter Abhängigkeits-„Graphen“ (Bäume).
-/// tip | "Tipp"
+/// tip | Tipp
All dies scheint angesichts dieser einfachen Beispiele möglicherweise nicht so nützlich zu sein.
Es wird also kein großer `str` zurückgegeben, der die Daten im JSON-Format (als String) enthält. Es wird eine Python-Standarddatenstruktur (z. B. ein `dict`) zurückgegeben, mit Werten und Unterwerten, die alle mit JSON kompatibel sind.
-/// note | "Hinweis"
+/// note | Hinweis
`jsonable_encoder` wird tatsächlich von **FastAPI** intern verwendet, um Daten zu konvertieren. Aber es ist in vielen anderen Szenarien hilfreich.
* Das **herausgehende Modell** sollte kein Passwort haben.
* Das **Datenbankmodell** sollte wahrscheinlich ein <abbr title='Ein aus scheinbar zufälligen Zeichen bestehender „Fingerabdruck“ eines Textes. Der Inhalt des Textes kann nicht eingesehen werden.'>gehashtes</abbr> Passwort haben.
-/// danger | "Gefahr"
+/// danger | Gefahr
Speichern Sie niemals das Klartext-Passwort eines Benutzers. Speichern Sie immer den „sicheren Hash“, den Sie verifizieren können.
)
```
-/// warning | "Achtung"
+/// warning | Achtung
Die Hilfsfunktionen `fake_password_hasher` und `fake_save_user` demonstrieren nur den möglichen Fluss der Daten und bieten natürlich keine echte Sicherheit.
Um das zu tun, verwenden Sie Pythons Standard-Typhinweis <a href="https://docs.python.org/3/library/typing.html#typing.Union" class="external-link" target="_blank">`typing.Union`</a>:
-/// note | "Hinweis"
+/// note | Hinweis
Listen Sie, wenn Sie eine <a href="https://pydantic-docs.helpmanual.io/usage/types/#unions" class="external-link" target="_blank">`Union`</a> definieren, denjenigen Typ zuerst, der am spezifischsten ist, gefolgt von den weniger spezifischen Typen. Im Beispiel oben, in `Union[PlaneItem, CarItem]` also den spezifischeren `PlaneItem` vor dem weniger spezifischen `CarItem`.
</div>
-/// note | "Hinweis"
+/// note | Hinweis
Der Befehl `uvicorn main:app` bezieht sich auf:
`FastAPI` ist eine Python-Klasse, die die gesamte Funktionalität für Ihre API bereitstellt.
-/// note | "Technische Details"
+/// note | Technische Details
`FastAPI` ist eine Klasse, die direkt von `Starlette` erbt.
* den Pfad `/`
* unter der Verwendung der <abbr title="eine HTTP GET Methode"><code>get</code>-Operation</abbr> gehen
-/// info | "`@decorator` Information"
+/// info | `@decorator` Information
Diese `@something`-Syntax wird in Python „Dekorator“ genannt.
* `@app.patch()`
* `@app.trace()`
-/// tip | "Tipp"
+/// tip | Tipp
Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es möchten.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Sie den Unterschied nicht kennen, lesen Sie [Async: *„In Eile?“*](../async.md#in-eile){.internal-link target=_blank}.
}
```
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie eine `HTTPException` auslösen, können Sie dem Parameter `detail` jeden Wert übergeben, der nach JSON konvertiert werden kann, nicht nur `str`.
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.requests import Request` und `from starlette.responses import JSONResponse` verwenden.
#### `RequestValidationError` vs. `ValidationError`
-/// warning | "Achtung"
+/// warning | Achtung
Das folgende sind technische Details, die Sie überspringen können, wenn sie für Sie nicht wichtig sind.
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import PlainTextResponse` verwenden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Technische Details"
+/// note | Technische Details
`Header` ist eine Schwesterklasse von `Path`, `Query` und `Cookie`. Sie erbt von derselben gemeinsamen `Param`-Elternklasse.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// warning | "Achtung"
+/// warning | Achtung
Bevor Sie `convert_underscores` auf `False` setzen, bedenken Sie, dass manche HTTP-Proxys und Server die Verwendung von Headern mit Unterstrichen nicht erlauben.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
... das beinhaltet auch `uvicorn`, welchen Sie als Server verwenden können, der ihren Code ausführt.
-/// note | "Hinweis"
+/// note | Hinweis
Sie können die einzelnen Teile auch separat installieren.
{!../../docs_src/metadata/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie können Markdown in das Feld `description` schreiben und es wird in der Ausgabe gerendert.
Beachten Sie, dass Sie Markdown in den Beschreibungen verwenden können. Beispielsweise wird „login“ in Fettschrift (**login**) und „fancy“ in Kursivschrift (_fancy_) angezeigt.
-/// tip | "Tipp"
+/// tip | Tipp
Sie müssen nicht für alle von Ihnen verwendeten Tags Metadaten hinzufügen.
* Sie kann etwas mit dieser **Response** tun oder beliebigen Code ausführen.
* Dann gibt sie die **Response** zurück.
-/// note | "Technische Details"
+/// note | Technische Details
Wenn Sie Abhängigkeiten mit `yield` haben, wird der Exit-Code *nach* der Middleware ausgeführt.
{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass benutzerdefinierte proprietäre Header hinzugefügt werden können. <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">Verwenden Sie dafür das Präfix 'X-'</a>.
///
-/// note | "Technische Details"
+/// note | Technische Details
Sie könnten auch `from starlette.requests import Request` verwenden.
Es gibt mehrere Konfigurations-Parameter, die Sie Ihrem *Pfadoperation-Dekorator* übergeben können.
-/// warning | "Achtung"
+/// warning | Achtung
Beachten Sie, dass diese Parameter direkt dem *Pfadoperation-Dekorator* übergeben werden, nicht der *Pfadoperation-Funktion*.
Dieser Statuscode wird in der Response verwendet und zum OpenAPI-Schema hinzugefügt.
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette import status` verwenden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Hinweis"
+/// note | Hinweis
Ein Pfad-Parameter ist immer erforderlich, weil er Teil des Pfads sein muss.
## Sortieren Sie die Parameter, wie Sie möchten
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
//// tab | Python 3.8 nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
## Sortieren Sie die Parameter wie Sie möchten: Tricks
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
///
-/// note | "Technische Details"
+/// note | Technische Details
`Query`, `Path` und andere, die Sie von `fastapi` importieren, sind tatsächlich Funktionen.
///
-/// tip | "Tipp"
+/// tip | Tipp
Falls Sie sich fragen, was „AlexNet“, „ResNet“ und „LeNet“ ist, das sind Namen von <abbr title="Genau genommen, Deep-Learning-Modellarchitekturen">Modellen</abbr> für maschinelles Lernen.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Sie können den Wert `"lenet"` außerdem mittels `ModelName.lenet.value` abrufen.
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Der Parameter könnte einen führenden Schrägstrich (`/`) haben, wie etwa in `/home/johndoe/myfile.txt`.
Der Query-Parameter `q` hat den Typ `Union[str, None]` (oder `str | None` in Python 3.10), was bedeutet, er ist entweder ein `str` oder `None`. Der Defaultwert ist `None`, also weiß FastAPI, der Parameter ist nicht erforderlich.
-/// note | "Hinweis"
+/// note | Hinweis
FastAPI weiß nur dank des definierten Defaultwertes `=None`, dass der Wert von `q` nicht erforderlich ist
Frühere Versionen von FastAPI (vor <abbr title="vor 2023-03">0.95.0</abbr>) benötigten `Query` als Defaultwert des Parameters, statt es innerhalb von `Annotated` unterzubringen. Die Chance ist groß, dass Sie Quellcode sehen, der das immer noch so macht, darum erkläre ich es Ihnen.
-/// tip | "Tipp"
+/// tip | Tipp
Verwenden Sie für neuen Code, und wann immer möglich, `Annotated`, wie oben erklärt. Es gibt mehrere Vorteile (unten erläutert) und keine Nachteile. 🍰
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Hinweis"
+/// note | Hinweis
Ein Parameter ist optional (nicht erforderlich), wenn er irgendeinen Defaultwert, auch `None`, hat.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
{!> ../../docs_src/query_params_str_validations/tutorial006.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass, obwohl in diesem Fall `Query()` der Funktionsparameter-Defaultwert ist, wir nicht `default=None` zu `Query()` hinzufügen.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Pydantic, welches die gesamte Datenvalidierung und Serialisierung in FastAPI antreibt, hat ein spezielles Verhalten, wenn Sie `Optional` oder `Union[Something, None]` ohne Defaultwert verwenden, Sie können mehr darüber in der Pydantic-Dokumentation unter <a href="https://docs.pydantic.dev/2.3/usage/models/#required-fields" class="external-link" target="_blank">Required fields</a> erfahren.
///
-/// tip | "Tipp"
+/// tip | Tipp
Denken Sie daran, dass Sie in den meisten Fällen, wenn etwas erforderlich ist, einfach den Defaultwert weglassen können. Sie müssen also normalerweise `...` nicht verwenden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
}
```
-/// tip | "Tipp"
+/// tip | Tipp
Um einen Query-Parameter vom Typ `list` zu deklarieren, wie im Beispiel oben, müssen Sie explizit `Query` verwenden, sonst würde der Parameter als Requestbody interpretiert werden.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass FastAPI in diesem Fall den Inhalt der Liste nicht überprüft.
Diese Informationen werden zur generierten OpenAPI hinzugefügt, und von den Dokumentations-Oberflächen und von externen Tools verwendet.
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass verschiedene Tools OpenAPI möglicherweise unterschiedlich gut unterstützen.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
* `skip`, ein `int` mit einem Defaultwert `0`.
* `limit`, ein optionales `int`.
-/// tip | "Tipp"
+/// tip | Tipp
Sie können auch `Enum`s verwenden, auf die gleiche Weise wie mit [Pfad-Parametern](path-params.md#vordefinierte-parameterwerte){.internal-link target=_blank}.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
///
-/// tip | "Tipp"
+/// tip | Tipp
Um Dateibodys zu deklarieren, müssen Sie `File` verwenden, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
contents = myfile.file.read()
```
-/// note | "Technische Details zu `async`"
+/// note | Technische Details zu `async`
Wenn Sie die `async`-Methoden verwenden, führt **FastAPI** die Datei-Methoden in einem <abbr title="Mehrere unabhängige Kindprozesse">Threadpool</abbr> aus und erwartet sie.
///
-/// note | "Technische Details zu Starlette"
+/// note | Technische Details zu Starlette
**FastAPI**s `UploadFile` erbt direkt von **Starlette**s `UploadFile`, fügt aber ein paar notwendige Teile hinzu, um es kompatibel mit **Pydantic** und anderen Teilen von FastAPI zu machen.
**FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten.
-/// note | "Technische Details"
+/// note | Technische Details
Daten aus Formularen werden, wenn es keine Dateien sind, normalerweise mit dem <abbr title='Media type – Medientyp, Typ des Mediums'>„media type“</abbr> `application/x-www-form-urlencoded` kodiert.
///
-/// warning | "Achtung"
+/// warning | Achtung
Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Sie erhalten, wie deklariert, eine `list`e von `bytes` oder `UploadFile`s.
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette.responses import HTMLResponse` verwenden.
//// tab | Python 3.9+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Und Sie können einige der Dateien als `bytes` und einige als `UploadFile` deklarieren.
-/// warning | "Achtung"
+/// warning | Achtung
Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
///
-/// tip | "Tipp"
+/// tip | Tipp
Um Formularbodys zu deklarieren, verwenden Sie explizit `Form`, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
**FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten.
-/// note | "Technische Details"
+/// note | Technische Details
Daten aus Formularen werden normalerweise mit dem <abbr title='Media type – Medientyp, Typ des Mediums'>„media type“</abbr> `application/x-www-form-urlencoded` kodiert.
///
-/// warning | "Achtung"
+/// warning | Achtung
Sie können mehrere `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `application/x-www-form-urlencoded` statt `application/json` kodiert.
////
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter.
FastAPI wird dieses `response_model` nehmen, um die Daten zu dokumentieren, validieren, usw. und auch, um **die Ausgabedaten** entsprechend der Typdeklaration **zu konvertieren und filtern**.
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als <abbr title='„Irgend etwas“'>`Any`</abbr> deklarieren.
Aber wenn wir dasselbe Modell für eine andere *Pfadoperation* verwenden, könnten wir das Passwort dieses Benutzers zu jedem Client schicken.
-/// danger | "Gefahr"
+/// danger | Gefahr
Speichern Sie niemals das Klartext-Passwort eines Benutzers, oder versenden Sie es in einer Response wie dieser, wenn Sie sich nicht der resultierenden Gefahren bewusst sind und nicht wissen, was Sie tun.
Diese Felder werden also in der JSON-Response enthalten sein.
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass Defaultwerte alles Mögliche sein können, nicht nur `None`.
Das kann als schnelle Abkürzung verwendet werden, wenn Sie nur ein Pydantic-Modell haben und ein paar Daten von der Ausgabe ausschließen wollen.
-/// tip | "Tipp"
+/// tip | Tipp
Es wird dennoch empfohlen, dass Sie die Ideen von oben verwenden, also mehrere Klassen statt dieser Parameter.
////
-/// tip | "Tipp"
+/// tip | Tipp
Die Syntax `{"name", "description"}` erzeugt ein `set` mit diesen zwei Werten.
{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie, dass `status_code` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter und der Body.
<img src="/img/tutorial/response-status-code/image01.png">
-/// note | "Hinweis"
+/// note | Hinweis
Einige Responsecodes (siehe nächster Abschnitt) kennzeichnen, dass die Response keinen Body hat.
## Über HTTP-Statuscodes
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Sie bereits wissen, was HTTP-Statuscodes sind, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
* Für allgemeine Fehler beim Client können Sie einfach `400` verwenden.
* `500` und darüber stehen für Server-Fehler. Diese verwenden Sie fast nie direkt. Wenn etwas an irgendeiner Stelle in Ihrem Anwendungscode oder im Server schiefläuft, wird automatisch einer dieser Fehler-Statuscodes zurückgegeben.
-/// tip | "Tipp"
+/// tip | Tipp
Um mehr über Statuscodes zu lernen, und welcher wofür verwendet wird, lesen Sie die <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network – Mozilla-Entwickler-Netzwerk">MDN</abbr> Dokumentation über HTTP-Statuscodes</a>.
<img src="/img/tutorial/response-status-code/image02.png">
-/// note | "Technische Details"
+/// note | Technische Details
Sie können auch `from starlette import status` verwenden.
////
-/// tip | "Tipp"
+/// tip | Tipp
Mit derselben Technik können Sie das JSON-Schema erweitern und Ihre eigenen benutzerdefinierten Zusatzinformationen hinzufügen.
## Technische Details
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie bereits **FastAPI** Version **0.99.0 oder höher** verwenden, können Sie diese Details wahrscheinlich **überspringen**.
///
-/// warning | "Achtung"
+/// warning | Achtung
Dies sind sehr technische Details zu den Standards **JSON Schema** und **OpenAPI**.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
<img src="/img/tutorial/security/image01.png">
-/// check | "Authorize-Button!"
+/// check | Authorize-Button!
Sie haben bereits einen glänzenden, neuen „Authorize“-Button.
<img src="/img/tutorial/security/image02.png">
-/// note | "Hinweis"
+/// note | Hinweis
Es spielt keine Rolle, was Sie in das Formular eingeben, es wird noch nicht funktionieren. Wir kommen dahin.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Hier bezieht sich `tokenUrl="token"` auf eine relative URL `token`, die wir noch nicht erstellt haben. Da es sich um eine relative URL handelt, entspricht sie `./token`.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
**FastAPI** weiß, dass es diese Abhängigkeit verwenden kann, um ein „Sicherheitsschema“ im OpenAPI-Schema (und der automatischen API-Dokumentation) zu definieren.
-/// info | "Technische Details"
+/// info | Technische Details
**FastAPI** weiß, dass es die Klasse `OAuth2PasswordBearer` (deklariert in einer Abhängigkeit) verwenden kann, um das Sicherheitsschema in OpenAPI zu definieren, da es von `fastapi.security.oauth2.OAuth2` erbt, das wiederum von `fastapi.security.base.SecurityBase` erbt.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
Das wird uns innerhalb der Funktion bei Codevervollständigung und Typprüfungen helfen.
-/// tip | "Tipp"
+/// tip | Tipp
Sie erinnern sich vielleicht, dass Requestbodys ebenfalls mit Pydantic-Modellen deklariert werden.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
OAuth2 spezifiziert nicht, wie die Kommunikation verschlüsselt werden soll, sondern erwartet, dass Ihre Anwendung mit HTTPS bereitgestellt wird.
-/// tip | "Tipp"
+/// tip | Tipp
Im Abschnitt über **Deployment** erfahren Sie, wie Sie HTTPS mithilfe von Traefik und Let's Encrypt kostenlos einrichten.
* Diese automatische Erkennung ist es, die in der OpenID Connect Spezifikation definiert ist.
-/// tip | "Tipp"
+/// tip | Tipp
Auch die Integration anderer Authentifizierungs-/Autorisierungsanbieter wie Google, Facebook, Twitter, GitHub, usw. ist möglich und relativ einfach.
Hier verwenden wir das empfohlene: <a href="https://cryptography.io/" class="external-link" target="_blank">pyca/cryptography</a>.
-/// tip | "Tipp"
+/// tip | Tipp
Dieses Tutorial verwendete zuvor <a href="https://pyjwt.readthedocs.io/" class="external-link" target="_blank">PyJWT</a>.
</div>
-/// tip | "Tipp"
+/// tip | Tipp
Mit `passlib` können Sie sogar konfigurieren, Passwörter zu lesen, die von **Django**, einem **Flask**-Sicherheit-Plugin, oder vielen anderen erstellt wurden.
Erstellen Sie einen PassLib-„Kontext“. Der wird für das Hashen und Verifizieren von Passwörtern verwendet.
-/// tip | "Tipp"
+/// tip | Tipp
Der PassLib-Kontext kann auch andere Hashing-Algorithmen verwenden, einschließlich deprecateter Alter, um etwa nur eine Verifizierung usw. zu ermöglichen.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// note | "Hinweis"
+/// note | Hinweis
Wenn Sie sich die neue (gefakte) Datenbank `fake_users_db` anschauen, sehen Sie, wie das gehashte Passwort jetzt aussieht: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
<img src="/img/tutorial/security/image10.png">
-/// note | "Hinweis"
+/// note | Hinweis
Beachten Sie den Header `Authorization` mit einem Wert, der mit `Bearer` beginnt.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
* Einem optionalen `scope`-Feld als langem String, bestehend aus durch Leerzeichen getrennten Strings.
* Einem optionalen `grant_type` („Art der Anmeldung“).
-/// tip | "Tipp"
+/// tip | Tipp
Die OAuth2-Spezifikation *erfordert* tatsächlich ein Feld `grant_type` mit dem festen Wert `password`, aber `OAuth2PasswordRequestForm` erzwingt dies nicht.
### Die Formulardaten verwenden
-/// tip | "Tipp"
+/// tip | Tipp
Die Instanz der Klassenabhängigkeit `OAuth2PasswordRequestForm` verfügt, statt eines Attributs `scope` mit dem durch Leerzeichen getrennten langen String, über das Attribut `scopes` mit einer tatsächlichen Liste von Strings, einem für jeden gesendeten Scope.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
In diesem einfachen Beispiel gehen wir einfach völlig unsicher vor und geben denselben `username` wie der Token zurück.
-/// tip | "Tipp"
+/// tip | Tipp
Im nächsten Kapitel sehen Sie eine wirklich sichere Implementierung mit Passwort-Hashing und <abbr title="JSON Web Tokens">JWT</abbr>-Tokens.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
////
-/// tip | "Tipp"
+/// tip | Tipp
Gemäß der Spezifikation sollten Sie ein JSON mit einem `access_token` und einem `token_type` zurückgeben, genau wie in diesem Beispiel.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "Technische Details"
+/// note | Technische Details
Sie könnten auch `from starlette.staticfiles import StaticFiles` verwenden.
{!../../docs_src/app_testing/tutorial001.py!}
```
-/// tip | "Tipp"
+/// tip | Tipp
Beachten Sie, dass die Testfunktionen normal `def` und nicht `async def` sind.
///
-/// note | "Technische Details"
+/// note | Technische Details
Sie könnten auch `from starlette.testclient import TestClient` verwenden.
///
-/// tip | "Tipp"
+/// tip | Tipp
Wenn Sie in Ihren Tests neben dem Senden von Anfragen an Ihre FastAPI-Anwendung auch `async`-Funktionen aufrufen möchten (z. B. asynchrone Datenbankfunktionen), werfen Sie einen Blick auf die [Async-Tests](../advanced/async-tests.md){.internal-link target=_blank} im Handbuch für fortgeschrittene Benutzer.
//// tab | Python 3.10+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
//// tab | Python 3.8+ nicht annotiert
-/// tip | "Tipp"
+/// tip | Tipp
Bevorzugen Sie die `Annotated`-Version, falls möglich.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
🚥 👆 ⚙️ Hypercorn, ⚫️ ✔️ 🎛 `--root-path`.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🔫 🔧 🔬 `root_path` 👉 ⚙️ 💼.
✔️ 🤯 👈 👆 💪 ⚙️ `Response` 📨 🕳 🙆, ⚖️ ✍ 🛃 🎧-🎓.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
**FastAPI** 🔌 📚 🛠️ ⚠ ⚙️ 💼, 👥 🔜 👀 ⏭ ❔ ⚙️ 👫.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
⏭ 🖼, 👆 💪 ⚙️ `from starlette.middleware.something import SomethingMiddleware`.
🕐❔ 👆 📣 *➡ 🛠️* 👆 🈸, **FastAPI** 🔁 🏗 🔗 🗃 🔃 👈 *➡ 🛠️* 🔌 🗄 🔗.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🗄 🔧 ⚫️ 🤙 <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">🛠️ 🎚</a>.
### 🌅 ℹ
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
{!../../docs_src/response_directly/tutorial001.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
{!../../docs_src/response_headers/tutorial001.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
{!../../docs_src/security/tutorial005.py!}
```
-/// info | "📡 ℹ"
+/// info | 📡 ℹ
`Security` 🤙 🏿 `Depends`, & ⚫️ ✔️ 1️⃣ ➕ 🔢 👈 👥 🔜 👀 ⏪.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.templating import Jinja2Templates`.
👆 💪 ✍ 🌅 ℹ 🔃 <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request` 🎚 🛂 💃 🧾 🕸</a>.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.requests import Request`.
{!../../docs_src/websockets/tutorial001.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.websockets import WebSocket`.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
✔️ 🏧 🛠️ 🧾 🕸 👩💻 🔢.
👐 🦁 🏺, ⚫️ 😑 💖 👍 🏏 🏗 🔗. ⏭ 👜 🔎 "✳ 🎂 🛠️" 🏺.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
◾-🛠️. ⚒ ⚫️ ⏩ 🌀 & 🏏 🧰 & 🍕 💪.
👀 🔀 `requests.get(...)` & `@app.get(...)`.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
* ✔️ 🙅 & 🏋️ 🛠️.
* ⚙️ 🇺🇸🔍 👩🔬 📛 (🛠️) 🔗, 🎯 & 🏋️ 🌌.
👈 ⚫️❔ 🕐❔ 💬 🔃 ⏬ 2️⃣.0️⃣ ⚫️ ⚠ 💬 "🦁", & ⏬ 3️⃣ ➕ "🗄".
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🛠️ & ⚙️ 📂 🐩 🛠️ 🔧, ↩️ 🛃 🔗.
✋️ ⚫️ ✍ ⏭ 📤 🔀 🐍 🆎 🔑. , 🔬 🔠 <abbr title="the definition of how data should be formed">🔗</abbr> 👆 💪 ⚙️ 🎯 🇨🇻 & 🎓 🚚 🍭.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
⚙️ 📟 🔬 "🔗" 👈 🚚 💽 🆎 & 🔬, 🔁.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
✔️ 🏧 🔬 📨 📨 💽.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🐕🦺 📂 🐩 🛠️, 🗄.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🏗 🗄 🔗 🔁, ⚪️➡️ 🎏 📟 👈 🔬 🛠️ & 🔬.
⚫️ 💪 🚫 🍵 🔁 🏷 📶 👍. , 🚥 🎻 💪 📨 🎻 🎚 👈 ✔️ 🔘 🏑 👈 🔄 🐦 🎻 🎚, ⚫️ 🚫🔜 ☑ 📄 & ✔.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
⚙️ 🐍 🆎 ✔️ 👑 👨🎨 🐕🦺.
⚫️ 🕐 🥇 📶 ⏩ 🐍 🛠️ ⚓️ 🔛 `asyncio`. ⚫️ ⚒ 📶 🎏 🏺.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
⚫️ ⚙️ <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> ↩️ 🔢 🐍 `asyncio` ➰. 👈 ⚫️❔ ⚒ ⚫️ ⏩.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🔎 🌌 ✔️ 😜 🎭.
, 💽 🔬, 🛠️, & 🧾, ✔️ ⌛ 📟, 🚫 🔁. ⚖️ 👫 ✔️ 🛠️ 🛠️ 🔛 🔝 🦅, 💖 🤗. 👉 🎏 🔺 🔨 🎏 🛠️ 👈 😮 🦅 🔧, ✔️ 1️⃣ 📨 🎚 & 1️⃣ 📨 🎚 🔢.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🔎 🌌 🤚 👑 🎭.
🛣 📣 👁 🥉, ⚙️ 🔢 📣 🎏 🥉 (↩️ ⚙️ 👨🎨 👈 💪 🥉 ▶️️ 🔛 🔝 🔢 👈 🍵 🔗). 👉 🔐 ❔ ✳ 🔨 ⚫️ 🌘 ❔ 🏺 (& 💃) 🔨 ⚫️. ⚫️ 🎏 📟 👜 👈 📶 😆 🔗.
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🔬 ➕ 🔬 💽 🆎 ⚙️ "🔢" 💲 🏷 🔢. 👉 📉 👨🎨 🐕🦺, & ⚫️ 🚫 💪 Pydantic ⏭.
///
-/// check | "💭 😮 **FastAPI**"
+/// check | 💭 😮 **FastAPI**
🤗 😮 🍕 APIStar, & 1️⃣ 🧰 👤 🔎 🏆 👍, 🌟 APIStar.
///
-/// check | "😮 **FastAPI** "
+/// check | 😮 **FastAPI**
🔀.
⚫️ ⭐ 🍭. 👐 ⚫️ ⏩ 🌘 🍭 📇. & ⚫️ ⚓️ 🔛 🎏 🐍 🆎 🔑, 👨🎨 🐕🦺 👑.
-/// check | "**FastAPI** ⚙️ ⚫️"
+/// check | **FastAPI** ⚙️ ⚫️
🍵 🌐 💽 🔬, 💽 🛠️ & 🏧 🏷 🧾 (⚓️ 🔛 🎻 🔗).
👈 1️⃣ 👑 👜 👈 **FastAPI** 🚮 🔛 🔝, 🌐 ⚓️ 🔛 🐍 🆎 🔑 (⚙️ Pydantic). 👈, ➕ 🔗 💉 ⚙️, 💂♂ 🚙, 🗄 🔗 ⚡, ♒️.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🔫 🆕 "🐩" ➖ 🛠️ ✳ 🐚 🏉 👨🎓. ⚫️ 🚫 "🐍 🐩" (🇩🇬), 👐 👫 🛠️ 🔨 👈.
///
-/// check | "**FastAPI** ⚙️ ⚫️"
+/// check | **FastAPI** ⚙️ ⚫️
🍵 🌐 🐚 🕸 🍕. ❎ ⚒ 🔛 🔝.
⚫️ 👍 💽 💃 & **FastAPI**.
-/// check | "**FastAPI** 👍 ⚫️"
+/// check | **FastAPI** 👍 ⚫️
👑 🕸 💽 🏃 **FastAPI** 🈸.
{!../../docs_src/custom_request_and_route/tutorial001.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
`Request` ✔️ `request.scope` 🔢, 👈 🐍 `dict` ⚗ 🗃 🔗 📨.
⚫️ 🔜 🔌 🌐 🛣 ⚪️➡️ 👈 📻 🍕 ⚫️.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
⚫️ 🔜 🤙 🔘 ✍ *➡ 🛠️* 🔠 *➡ 🛠️* 👈 📣 `APIRouter`.
& ⚫️ 🔜 👷 ☑, 👯♂️ ⏮️ 🌐 🎏 *➡ 🛠️* 🚮 ⏮️ `app.include_router()`.
-/// info | "📶 📡 ℹ"
+/// info | 📶 📡 ℹ
**🗒**: 👉 📶 📡 ℹ 👈 👆 🎲 💪 **🚶**.
`Field` 👷 🎏 🌌 `Query`, `Path` & `Body`, ⚫️ ✔️ 🌐 🎏 🔢, ♒️.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🤙, `Query`, `Path` & 🎏 👆 🔜 👀 ⏭ ✍ 🎚 🏿 ⚠ `Param` 🎓, ❔ ⚫️ 🏿 Pydantic `FieldInfo` 🎓.
////
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
`Cookie` "👭" 🎓 `Path` & `Query`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
🌖 ℹ 🔃 <abbr title="Cross-Origin Resource Sharing">⚜</abbr>, ✅ <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">🦎 ⚜ 🧾</a>.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.middleware.cors import CORSMiddleware`.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🙆 🔢 👈 ☑ ⚙️ ⏮️:
**FastAPI** 🔜 ⚒ 💭 🌐 🏃 ☑ ✔.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👉 👷 👏 🐍 <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">🔑 👨💼</a>.
`FastAPI` 🐍 🎓 👈 🚚 🌐 🛠️ 👆 🛠️.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
`FastAPI` 🎓 👈 😖 🔗 ⚪️➡️ `Starlette`.
* ➡ `/`
* ⚙️ <abbr title="an HTTP GET method"><code>get</code> 🛠️</abbr>
-/// info | "`@decorator` ℹ"
+/// info | `@decorator` ℹ
👈 `@something` ❕ 🐍 🤙 "👨🎨".
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.requests import Request` & `from starlette.responses import JSONResponse`.
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import PlainTextResponse`.
////
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
`Header` "👭" 🎓 `Path`, `Query` & `Cookie`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
* ⚫️ 💪 🕳 👈 **📨** ⚖️ 🏃 🙆 💪 📟.
* ⤴️ ⚫️ 📨 **📨**.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🚥 👆 ✔️ 🔗 ⏮️ `yield`, 🚪 📟 🔜 🏃 *⏮️* 🛠️.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.requests import Request`.
👈 👔 📟 🔜 ⚙️ 📨 & 🔜 🚮 🗄 🔗.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette import status`.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
🕐❔ 👆 🗄 `Query`, `Path` & 🎏 ⚪️➡️ `fastapi`, 👫 🤙 🔢.
contents = myfile.file.read()
```
-/// note | "`async` 📡 ℹ"
+/// note | `async` 📡 ℹ
🕐❔ 👆 ⚙️ `async` 👩🔬, **FastAPI** 🏃 📁 👩🔬 🧵 & ⌛ 👫.
///
-/// note | "💃 📡 ℹ"
+/// note | 💃 📡 ℹ
**FastAPI**'Ⓜ `UploadFile` 😖 🔗 ⚪️➡️ **💃**'Ⓜ `UploadFile`, ✋️ 🚮 💪 🍕 ⚒ ⚫️ 🔗 ⏮️ **Pydantic** & 🎏 🍕 FastAPI.
**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded` 🕐❔ ⚫️ 🚫 🔌 📁.
👆 🔜 📨, 📣, `list` `bytes` ⚖️ `UploadFile`Ⓜ.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded`.
<img src="/img/tutorial/response-status-code/image02.png">
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette import status`.
<img src="/img/tutorial/security/image01.png">
-/// check | "✔ 🔼 ❗"
+/// check | ✔ 🔼 ❗
👆 ⏪ ✔️ ✨ 🆕 "✔" 🔼.
**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 👉 🔗 🔬 "💂♂ ⚖" 🗄 🔗 (& 🏧 🛠️ 🩺).
-/// info | "📡 ℹ"
+/// info | 📡 ℹ
**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 🎓 `OAuth2PasswordBearer` (📣 🔗) 🔬 💂♂ ⚖ 🗄 ↩️ ⚫️ 😖 ⚪️➡️ `fastapi.security.oauth2.OAuth2`, ❔ 🔄 😖 ⚪️➡️ `fastapi.security.base.SecurityBase`.
...💪 🕴 `SQLite`. ⚫️ 🚫 💪 🎏 💽.
-/// info | "📡 ℹ"
+/// info | 📡 ℹ
🔢 🗄 🔜 🕴 ✔ 1️⃣ 🧵 🔗 ⏮️ ⚫️, 🤔 👈 🔠 🧵 🔜 🍵 🔬 📨.
////
-/// info | "📡 ℹ"
+/// info | 📡 ℹ
🔢 `db` 🤙 🆎 `SessionLocal`, ✋️ 👉 🎓 (✍ ⏮️ `sessionmaker()`) "🗳" 🇸🇲 `Session`,, 👨🎨 🚫 🤙 💭 ⚫️❔ 👩🔬 🚚.
///
-/// note | "📶 📡 ℹ"
+/// note | 📶 📡 ℹ
🚥 👆 😟 & ✔️ ⏬ 📡 💡, 👆 💪 ✅ 📶 📡 ℹ ❔ 👉 `async def` 🆚 `def` 🍵 [🔁](../async.md#i_2){.internal-link target=_blank} 🩺.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.staticfiles import StaticFiles`.
///
-/// note | "📡 ℹ"
+/// note | 📡 ℹ
👆 💪 ⚙️ `from starlette.testclient import TestClient`.
///
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import JSONResponse`.
If you use Hypercorn, it also has the option `--root-path`.
-/// note | "Technical Details"
+/// note | Technical Details
The ASGI specification defines a `root_path` for this use case.
Keep in mind that you can use `Response` to return anything else, or even create a custom sub-class.
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import HTMLResponse`.
**FastAPI** includes several middlewares for common use cases, we'll see next how to use them.
-/// note | "Technical Details"
+/// note | Technical Details
For the next examples, you could also use `from starlette.middleware.something import SomethingMiddleware`.
When you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema.
-/// note | "Technical details"
+/// note | Technical details
In the OpenAPI specification it is called the <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Operation Object</a>.
### More info
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import JSONResponse`.
{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
-/// info | "Technical Details"
+/// info | Technical Details
`Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
///
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.templating import Jinja2Templates`.
You can read more details about the <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request` object in the official Starlette documentation site</a>.
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.requests import Request`.
{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *}
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.websockets import WebSocket`.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Have an automatic API documentation web user interface.
Given the simplicity of Flask, it seemed like a good match for building APIs. The next thing to find was a "Django REST Framework" for Flask.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Be a micro-framework. Making it easy to mix and match the tools and parts needed.
See the similarities in `requests.get(...)` and `@app.get(...)`.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
* Have a simple and intuitive API.
* Use HTTP method names (operations) directly, in a straightforward and intuitive way.
That's why when talking about version 2.0 it's common to say "Swagger", and for version 3+ "OpenAPI".
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Adopt and use an open standard for API specifications, instead of a custom schema.
But it was created before there existed Python type hints. So, to define every <abbr title="the definition of how data should be formed">schema</abbr> you need to use specific utils and classes provided by Marshmallow.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Use code to define "schemas" that provide data types and validation, automatically.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Have automatic validation of incoming request data.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Support the open standard for APIs, OpenAPI.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Generate the OpenAPI schema automatically, from the same code that defines serialization and validation.
It can't handle nested models very well. So, if the JSON body in the request is a JSON object that has inner fields that in turn are nested JSON objects, it cannot be properly documented and validated.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Use Python types to have great editor support.
It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask.
-/// note | "Technical Details"
+/// note | Technical Details
It used <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> instead of the default Python `asyncio` loop. That's what made it so fast.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Find a way to have a crazy performance.
So, data validation, serialization, and documentation, have to be done in code, not automatically. Or they have to be implemented as a framework on top of Falcon, like Hug. This same distinction happens in other frameworks that are inspired by Falcon's design, of having one request object and one response object as parameters.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Find ways to get great performance.
Routes are declared in a single place, using functions declared in other places (instead of using decorators that can be placed right on top of the function that handles the endpoint). This is closer to how Django does it than to how Flask (and Starlette) does it. It separates in the code things that are relatively tightly coupled.
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Define extra validations for data types using the "default" value of model attributes. This improves editor support, and it was not available in Pydantic before.
///
-/// check | "Ideas inspiring **FastAPI**"
+/// check | Ideas inspiring **FastAPI**
Hug inspired parts of APIStar, and was one of the tools I found most promising, alongside APIStar.
///
-/// check | "Inspired **FastAPI** to"
+/// check | Inspired **FastAPI** to
Exist.
It is comparable to Marshmallow. Although it's faster than Marshmallow in benchmarks. And as it is based on the same Python type hints, the editor support is great.
-/// check | "**FastAPI** uses it to"
+/// check | **FastAPI** uses it to
Handle all the data validation, data serialization and automatic model documentation (based on JSON Schema).
That's one of the main things that **FastAPI** adds on top, all based on Python type hints (using Pydantic). That, plus the dependency injection system, security utilities, OpenAPI schema generation, etc.
-/// note | "Technical Details"
+/// note | Technical Details
ASGI is a new "standard" being developed by Django core team members. It is still not a "Python standard" (a PEP), although they are in the process of doing that.
///
-/// check | "**FastAPI** uses it to"
+/// check | **FastAPI** uses it to
Handle all the core web parts. Adding features on top.
It is the recommended server for Starlette and **FastAPI**.
-/// check | "**FastAPI** recommends it as"
+/// check | **FastAPI** recommends it as
The main web server to run **FastAPI** applications.
That way, you don't have to "install" your local version to be able to test every change.
-/// note | "Technical Details"
+/// note | Technical Details
This only happens when you install using this included `requirements.txt` instead of running `pip install fastapi` directly.
{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
-/// note | "Technical Details"
+/// note | Technical Details
A `Request` has a `request.scope` attribute, that's just a Python `dict` containing the metadata related to the request.
Those don't have to be translated, but if they are, they need to be written as:
```
-/// tip | "consejo"
+/// tip | consejo
Esto es un consejo.
Which looks like:
-/// tip | "consejo"
+/// tip | consejo
Esto es un consejo.
It will include all the routes from that router as part of it.
-/// note | "Technical Details"
+/// note | Technical Details
It will actually internally create a *path operation* for each *path operation* that was declared in the `APIRouter`.
and it will work correctly, together with all the other *path operations* added with `app.include_router()`.
-/// info | "Very Technical Details"
+/// info | Very Technical Details
**Note**: this is a very technical detail that you probably can **just skip**.
`Field` works the same way as `Query`, `Path` and `Body`, it has all the same parameters, etc.
-/// note | "Technical Details"
+/// note | Technical Details
Actually, `Query`, `Path` and others you'll see next create objects of subclasses of a common `Param` class, which is itself a subclass of Pydantic's `FieldInfo` class.
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
-/// note | "Technical Details"
+/// note | Technical Details
`Cookie` is a "sister" class of `Path` and `Query`. It also inherits from the same common `Param` class.
For more info about <abbr title="Cross-Origin Resource Sharing">CORS</abbr>, check the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS documentation</a>.
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.middleware.cors import CORSMiddleware`.
///
-/// note | "Technical Details"
+/// note | Technical Details
Any function that is valid to use with:
**FastAPI** will make sure everything is run in the correct order.
-/// note | "Technical Details"
+/// note | Technical Details
This works thanks to Python's <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">Context Managers</a>.
`FastAPI` is a Python class that provides all the functionality for your API.
-/// note | "Technical Details"
+/// note | Technical Details
`FastAPI` is a class that inherits directly from `Starlette`.
* the path `/`
* using a <abbr title="an HTTP GET method"><code>get</code> operation</abbr>
-/// info | "`@decorator` Info"
+/// info | `@decorator` Info
That `@something` syntax in Python is called a "decorator".
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import PlainTextResponse`.
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *}
-/// note | "Technical Details"
+/// note | Technical Details
`Header` is a "sister" class of `Path`, `Query` and `Cookie`. It also inherits from the same common `Param` class.
* It can do something to that **response** or run any needed code.
* Then it returns the **response**.
-/// note | "Technical Details"
+/// note | Technical Details
If you have dependencies with `yield`, the exit code will run *after* the middleware.
///
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.requests import Request`.
That status code will be used in the response and will be added to the OpenAPI schema.
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette import status`.
///
-/// note | "Technical Details"
+/// note | Technical Details
When you import `Query`, `Path` and others from `fastapi`, they are actually functions.
contents = myfile.file.read()
```
-/// note | "`async` Technical Details"
+/// note | `async` Technical Details
When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them.
///
-/// note | "Starlette Technical Details"
+/// note | Starlette Technical Details
**FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI.
**FastAPI** will make sure to read that data from the right place instead of JSON.
-/// note | "Technical Details"
+/// note | Technical Details
Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded` when it doesn't include files.
You will receive, as declared, a `list` of `bytes` or `UploadFile`s.
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.responses import HTMLResponse`.
**FastAPI** will make sure to read that data from the right place instead of JSON.
-/// note | "Technical Details"
+/// note | Technical Details
Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded`.
<img src="/img/tutorial/response-status-code/image02.png">
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette import status`.
<img src="/img/tutorial/security/image01.png">
-/// check | "Authorize button!"
+/// check | Authorize button!
You already have a shiny new "Authorize" button.
**FastAPI** will know that it can use this dependency to define a "security scheme" in the OpenAPI schema (and the automatic API docs).
-/// info | "Technical Details"
+/// info | Technical Details
**FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`.
{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.staticfiles import StaticFiles`.
///
-/// note | "Technical Details"
+/// note | Technical Details
You could also use `from starlette.testclient import TestClient`.
## OpenAPI operationId
-/// warning | "Advertencia"
+/// warning | Advertencia
Si no eres una persona "experta" en OpenAPI, probablemente no necesitas leer esto.
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9]*}
-/// note | "Detalles Técnicos"
+/// note | Detalles Técnicos
`Cookie` es una clase "hermana" de `Path` y `Query`. También hereda de la misma clase común `Param`.
...eso también incluye `uvicorn` que puedes usar como el servidor que ejecuta tu código.
-/// note | "Nota"
+/// note | Nota
También puedes instalarlo parte por parte.
* می تواند کاری با **پاسخ** انجام دهید یا هر کد مورد نیازتان را اجرا کند.
* سپس **پاسخ** را برمی گرداند.
-/// توجه | "جزئیات فنی"
+/// توجه | جزئیات فنی
در صورت وجود وابستگی هایی با `yield`، کد خروجی **پس از** اجرای میانافزار اجرا خواهد شد.
///
-/// توجه | "جزئیات فنی"
+/// توجه | جزئیات فنی
شما همچنین میتوانید از `from starlette.requests import Request` استفاده کنید.
# Réponses supplémentaires dans OpenAPI
-/// warning | "Attention"
+/// warning | Attention
Ceci concerne un sujet plutôt avancé.
{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-/// note | "Remarque"
+/// note | Remarque
Gardez à l'esprit que vous devez renvoyer directement `JSONResponse`.
{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-/// note | "Remarque"
+/// note | Remarque
Notez que vous devez retourner l'image en utilisant directement un `FileResponse`.
{!../../docs_src/additional_status_codes/tutorial001.py!}
```
-/// warning | "Attention"
+/// warning | Attention
Lorsque vous renvoyez une `Response` directement, comme dans l'exemple ci-dessus, elle sera renvoyée directement.
///
-/// note | "Détails techniques"
+/// note | Détails techniques
Vous pouvez également utiliser `from starlette.responses import JSONResponse`.
Dans les sections suivantes, vous verrez des options, configurations et fonctionnalités supplémentaires.
-/// note | "Remarque"
+/// note | Remarque
Les sections de ce chapitre ne sont **pas nécessairement "avancées"**.
## ID d'opération OpenAPI
-/// warning | "Attention"
+/// warning | Attention
Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin.
{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-/// tip | "Astuce"
+/// tip | Astuce
Si vous appelez manuellement `app.openapi()`, vous devez mettre à jour les `operationId` avant.
///
-/// warning | "Attention"
+/// warning | Attention
Pour faire cela, vous devez vous assurer que chacun de vos *chemin* ait un nom unique.
Lorsque vous déclarez un *chemin* dans votre application, **FastAPI** génère automatiquement les métadonnées concernant ce *chemin* à inclure dans le schéma OpenAPI.
-/// note | "Détails techniques"
+/// note | Détails techniques
La spécification OpenAPI appelle ces métadonnées des <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Objets d'opération</a>.
Ce schéma OpenAPI spécifique aux *operations* est normalement généré automatiquement par **FastAPI**, mais vous pouvez également l'étendre.
-/// tip | "Astuce"
+/// tip | Astuce
Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les [réponses supplémentaires dans OpenAPI](additional-responses.md){.internal-link target=_blank}.
{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-/// tip | "Astuce"
+/// tip | Astuce
Ici, nous réutilisons le même modèle Pydantic.
En fait, vous pouvez retourner n'importe quelle `Response` ou n'importe quelle sous-classe de celle-ci.
-/// note | "Remarque"
+/// note | Remarque
`JSONResponse` est elle-même une sous-classe de `Response`.
{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-/// note | "Détails techniques"
+/// note | Détails techniques
Vous pouvez aussi utiliser `from starlette.responses import JSONResponse`.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Avoir une interface de documentation automatique de l'API.
Compte tenu de la simplicité de Flask, il semblait bien adapté à la création d'API. La prochaine chose à trouver était un "Django REST Framework" pour Flask.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Être un micro-framework. Il est donc facile de combiner les outils et les pièces nécessaires.
Notez les similitudes entre `requests.get(...)` et `@app.get(...)`.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Avoir une API simple et intuitive.
C'est pourquoi, lorsqu'on parle de la version 2.0, il est courant de dire "Swagger", et pour la version 3+ "OpenAPI".
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Adopter et utiliser une norme ouverte pour les spécifications des API, au lieu d'un schéma personnalisé.
Mais elle a été créée avant que les type hints n'existent en Python. Ainsi, pour définir chaque <abbr title="la définition de
la façon dont les données doivent être formées">schéma</abbr>, vous devez utiliser des utilitaires et des classes spécifiques fournies par Marshmallow.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Utilisez du code pour définir des "schémas" qui fournissent automatiquement les types de données et la validation.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Disposer d'une validation automatique des données des requêtes entrantes.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Supporter la norme ouverte pour les API, OpenAPI.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Générer le schéma OpenAPI automatiquement, à partir du même code qui définit la sérialisation et la validation.
Il ne peut pas très bien gérer les modèles imbriqués. Ainsi, si le corps JSON de la requête est un objet JSON comportant des champs internes qui sont à leur tour des objets JSON imbriqués, il ne peut pas être correctement documenté et validé.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Utiliser les types Python pour bénéficier d'un excellent support de l'éditeur.
C'était l'un des premiers frameworks Python extrêmement rapides basés sur `asyncio`. Il a été conçu pour être très similaire à Flask.
-/// note | "Détails techniques"
+/// note | Détails techniques
Il utilisait <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> au lieu du système par défaut de Python `asyncio`. C'est ce qui l'a rendu si rapide.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Trouvez un moyen d'avoir une performance folle.
Ainsi, la validation, la sérialisation et la documentation des données doivent être effectuées dans le code, et non pas automatiquement. Ou bien elles doivent être implémentées comme un framework au-dessus de Falcon, comme Hug. Cette même distinction se retrouve dans d'autres frameworks qui s'inspirent de la conception de Falcon, qui consiste à avoir un objet de requête et un objet de réponse comme paramètres.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Trouver des moyens d'obtenir de bonnes performances.
méthode est plus proche de celle de Django que de celle de Flask (et Starlette). Il sépare dans le code des choses
qui sont relativement fortement couplées.
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Définir des validations supplémentaires pour les types de données utilisant la valeur "par défaut" des attributs du modèle. Ceci améliore le support de l'éditeur, et n'était pas disponible dans Pydantic auparavant.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Hug a inspiré certaines parties d'APIStar, et était l'un des outils que je trouvais les plus prometteurs, à côté d'APIStar.
///
-/// check | "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
Exister.
Il est comparable à Marshmallow. Bien qu'il soit plus rapide que Marshmallow dans les benchmarks. Et comme il est
basé sur les mêmes type hints Python, le support de l'éditeur est grand.
-/// check | "**FastAPI** l'utilise pour"
+/// check | **FastAPI** l'utilise pour
Gérer toute la validation des données, leur sérialisation et la documentation automatique du modèle (basée sur le schéma JSON).
C'est l'une des principales choses que **FastAPI** ajoute par-dessus, le tout basé sur les type hints Python (en utilisant Pydantic). Cela, plus le système d'injection de dépendances, les utilitaires de sécurité, la génération de schémas OpenAPI, etc.
-/// note | "Détails techniques"
+/// note | Détails techniques
ASGI est une nouvelle "norme" développée par les membres de l'équipe principale de Django. Il ne s'agit pas encore d'une "norme Python" (un PEP), bien qu'ils soient en train de le faire.
///
-/// check | "**FastAPI** l'utilise pour"
+/// check | **FastAPI** l'utilise pour
Gérer toutes les parties web de base. Ajouter des fonctionnalités par-dessus.
C'est le serveur recommandé pour Starlette et **FastAPI**.
-/// check | "**FastAPI** le recommande comme"
+/// check | **FastAPI** le recommande comme
Le serveur web principal pour exécuter les applications **FastAPI**.
## Détails très techniques
-/// warning | "Attention !"
+/// warning | Attention !
Vous pouvez probablement ignorer cela.
Mais vous pouvez toujours changer et mettre à jour toutes les configurations avec des variables d'environnement ou des fichiers de configuration.
-/// tip | "Astuce"
+/// tip | Astuce
Pour voir toutes les configurations et options, rendez-vous sur la page de l'image Docker : <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
</div>
-/// tip | "Astuce"
+/// tip | Astuce
En ajoutant `standard`, Uvicorn va installer et utiliser quelques dépendances supplémentaires recommandées.
FastAPI suit également la convention que tout changement de version "PATCH" est pour des corrections de bogues et
des changements rétrocompatibles.
-/// tip | "Astuce"
+/// tip | Astuce
Le "PATCH" est le dernier chiffre, par exemple, dans `0.2.3`, la version PATCH est `3`.
Les changements non rétrocompatibles et les nouvelles fonctionnalités sont ajoutés dans les versions "MINOR".
-/// tip | "Astuce"
+/// tip | Astuce
Le "MINOR" est le numéro au milieu, par exemple, dans `0.2.3`, la version MINOR est `2`.
{*../../docs_src/python_types/tutorial006.py hl[4] *}
-/// tip | "Astuce"
+/// tip | Astuce
Ces types internes entre crochets sont appelés des "paramètres de type".
<img src="/img/tutorial/body/image05.png">
-/// tip | "Astuce"
+/// tip | Astuce
Si vous utilisez <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> comme éditeur, vous pouvez utiliser le Plugin <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>.
`FastAPI` est une classe Python qui fournit toutes les fonctionnalités nécessaires au lancement de votre API.
-/// note | "Détails techniques"
+/// note | Détails techniques
`FastAPI` est une classe héritant directement de `Starlette`.
* le chemin `/`
* en utilisant une <abbr title="une méthode GET HTTP">opération <code>get</code></abbr>
-/// info | "`@décorateur` Info"
+/// info | `@décorateur` Info
Cette syntaxe `@something` en Python est appelée un "décorateur".
* `@app.patch()`
* `@app.trace()`
-/// tip | "Astuce"
+/// tip | Astuce
Vous êtes libres d'utiliser chaque opération (méthode HTTP) comme vous le désirez.
///
-/// note | "Détails techniques"
+/// note | Détails techniques
Lorsque vous importez `Query`, `Path` et d'autres de `fastapi`, ce sont en fait des fonctions.
Ici, `item_id` est déclaré comme `int`.
-/// check | "vérifier"
+/// check | vérifier
Ceci vous permettra d'obtenir des fonctionnalités de l'éditeur dans votre fonction, telles
que des vérifications d'erreur, de l'auto-complétion, etc.
{"item_id":3}
```
-/// check | "vérifier"
+/// check | vérifier
Comme vous l'avez remarqué, la valeur reçue par la fonction (et renvoyée ensuite) est `3`,
en tant qu'entier (`int`) Python, pas la chaîne de caractères (`string`) `"3"`.
<a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>.
-/// check | "vérifier"
+/// check | vérifier
Donc, avec ces mêmes déclarations de type Python, **FastAPI** vous fournit de la validation de données.
///
-/// tip | "Astuce"
+/// tip | Astuce
Pour ceux qui se demandent, "AlexNet", "ResNet", et "LeNet" sont juste des noms de <abbr title="Techniquement, des architectures de modèles">modèles</abbr> de Machine Learning.
{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-/// tip | "Astuce"
+/// tip | Astuce
Vous pouvez aussi accéder la valeur `"lenet"` avec `ModelName.lenet.value`.
{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-/// tip | "Astuce"
+/// tip | Astuce
Vous pourriez avoir besoin que le paramètre contienne `/home/johndoe/myfile.txt`, avec un slash au début (`/`).
{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
-/// note | "Rappel"
+/// note | Rappel
Avoir une valeur par défaut rend le paramètre optionnel.
}
```
-/// tip | "Astuce"
+/// tip | Astuce
Pour déclarer un paramètre de requête de type `list`, comme dans l'exemple ci-dessus, il faut explicitement utiliser `Query`, sinon cela sera interprété comme faisant partie du corps de la requête.
Ici, le paramètre `q` sera optionnel, et aura `None` comme valeur par défaut.
-/// check | "Remarque"
+/// check | Remarque
On peut voir que **FastAPI** est capable de détecter que le paramètre de chemin `item_id` est un paramètre de chemin et que `q` n'en est pas un, c'est donc un paramètre de requête.
* `skip`, un `int` avec comme valeur par défaut `0`.
* `limit`, un `int` optionnel.
-/// tip | "Astuce"
+/// tip | Astuce
Vous pouvez utiliser les `Enum`s de la même façon qu'avec les [Paramètres de chemin](path-params.md#valeurs-predefinies){.internal-link target=_blank}.
...yang juga termasuk `uvicorn`, yang dapat kamu gunakan sebagai server yang menjalankan kodemu.
-/// note | "Catatan"
+/// note | Catatan
Kamu juga dapat meng-installnya bagian demi bagian.
{!../../docs_src/additional_status_codes/tutorial001.py!}
```
-/// warning | "注意"
+/// warning | 注意
上記の例のように `Response` を明示的に返す場合、それは直接返されます。
///
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.responses import JSONResponse` を利用することもできます。
そしてもし、`Response` が、`JSONResponse` や `UJSONResponse` の場合のようにJSONメディアタイプ (`application/json`) ならば、データは *path operationデコレータ* に宣言したPydantic `response_model` により自動的に変換 (もしくはフィルタ) されます。
-/// note | "備考"
+/// note | 備考
メディアタイプを指定せずにレスポンスクラスを利用すると、FastAPIは何もコンテンツがないことを期待します。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットが記載されません。
{!../../docs_src/custom_response/tutorial001b.py!}
```
-/// info | "情報"
+/// info | 情報
パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用することもできます。
///
-/// tip | "豆知識"
+/// tip | 豆知識
`ORJSONResponse` は、現在はFastAPIのみで利用可能で、Starletteでは利用できません。
{!../../docs_src/custom_response/tutorial002.py!}
```
-/// info | "情報"
+/// info | 情報
パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用されます。
{!../../docs_src/custom_response/tutorial003.py!}
```
-/// warning | "注意"
+/// warning | 注意
*path operation関数* から直接返される `Response` は、OpenAPIにドキュメントされず (例えば、 `Content-Type` がドキュメントされない) 、自動的な対話的ドキュメントからも閲覧できません。
///
-/// info | "情報"
+/// info | 情報
もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返された `Response` オブジェクトに由来しています。
`Response` を使って他の何かを返せますし、カスタムのサブクラスも作れることを覚えておいてください。
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.responses import HTMLResponse` も利用できます。
<a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>を使った、代替のJSONレスポンスです。
-/// warning | "注意"
+/// warning | 注意
`ujson` は、いくつかのエッジケースの取り扱いについて、Pythonにビルトインされた実装よりも作りこまれていません。
{!../../docs_src/custom_response/tutorial001.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`ORJSONResponse` のほうが高速な代替かもしれません。
{!../../docs_src/custom_response/tutorial008.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
ここでは `async` や `await` をサポートしていない標準の `open()` を使っているので、通常の `def` でpath operationを宣言していることに注意してください。
{!../../docs_src/custom_response/tutorial010.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
前に見たように、 *path operation* の中で `response_class` をオーバーライドできます。
以降のセクションでは、チュートリアルでは説明しきれなかったオプションや設定、および機能について説明します。
-/// tip | "豆知識"
+/// tip | 豆知識
以降のセクションは、 **必ずしも"応用編"ではありません**。
## OpenAPI operationId
-/// warning | "注意"
+/// warning | 注意
あなたがOpenAPIの「エキスパート」でなければ、これは必要ないかもしれません。
{!../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`app.openapi()` を手動でコールする場合、その前に`operationId`を更新する必要があります。
///
-/// warning | "注意"
+/// warning | 注意
この方法をとる場合、各 *path operation関数* が一意な名前である必要があります。
実際は、`Response` やそのサブクラスを返すことができます。
-/// tip | "豆知識"
+/// tip | 豆知識
`JSONResponse` それ自体は、 `Response` のサブクラスです。
{!../../docs_src/response_directly/tutorial001.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
また、`from starlette.responses import JSONResponse` も利用できます。
{!../../docs_src/websockets/tutorial001.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.websockets import WebSocket` を使用しても構いません.
{!../../docs_src/websockets/tutorial002.py!}
```
-/// info | "情報"
+/// info | 情報
WebSocket で `HTTPException` を発生させることはあまり意味がありません。したがって、WebSocketの接続を直接閉じる方がよいでしょう。
* パスで使用される「Item ID」
* クエリパラメータとして使用される「Token」
-/// tip | "豆知識"
+/// tip | 豆知識
クエリ `token` は依存パッケージによって処理されることに注意してください。
Client #1596980209979 left the chat
```
-/// tip | "豆知識"
+/// tip | 豆知識
上記のアプリは、複数の WebSocket 接続に対してメッセージを処理し、ブロードキャストする方法を示すための最小限のシンプルな例です。
これは**自動的なAPIドキュメント生成**の最初の例であり、これは**FastAPI**に向けた「調査」を触発した最初のアイデアの一つでした。
-/// note | "備考"
+/// note | 備考
Django REST Framework は Tom Christie によって作成されました。StarletteとUvicornの生みの親であり、**FastAPI**のベースとなっています。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
自動でAPIドキュメントを生成するWebユーザーインターフェースを持っている点。
Flaskのシンプルさを考えると、APIを構築するのに適しているように思えました。次に見つけるべきは、Flask 用の「Django REST Framework」でした。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
マイクロフレームワークであること。ツールやパーツを目的に合うように簡単に組み合わせられる点。
`requests.get(...)` と`@app.get(...)` には類似点が見受けられます。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
* シンプルで直感的なAPIを持っている点。
* HTTPメソッド名を直接利用し、単純で直感的である。
そのため、バージョン2.0では「Swagger」、バージョン3以上では「OpenAPI」と表記するのが一般的です。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
独自のスキーマの代わりに、API仕様のオープンな標準を採用しました。
しかし、それはPythonの型ヒントが存在する前に作られたものです。そのため、すべての<abbr title="データがどのように形成されるべきかの定義">スキーマ</abbr>を定義するためには、Marshmallowが提供する特定のユーティリティやクラスを使用する必要があります。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
コードで「スキーマ」を定義し、データの型やバリデーションを自動で提供する点。
素晴らしいツールで、私も**FastAPI**を持つ前はよく使っていました。
-/// info | "情報"
+/// info | 情報
Webargsは、Marshmallowと同じ開発者により作られました。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
受信したデータに対する自動的なバリデーションを持っている点。
エディタでは、この問題を解決することはできません。また、パラメータやMarshmallowスキーマを変更したときに、YAMLのdocstringを変更するのを忘れてしまうと、生成されたスキーマが古くなってしまいます。
-/// info | "情報"
+/// info | 情報
APISpecは、Marshmallowと同じ開発者により作成されました。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
OpenAPIという、APIについてのオープンな標準をサポートしている点。
そして、これらのフルスタックジェネレーターは、[**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}の元となっていました。
-/// info | "情報"
+/// info | 情報
Flask-apispecはMarshmallowと同じ開発者により作成されました。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
シリアライゼーションとバリデーションを定義したコードから、OpenAPIスキーマを自動的に生成する点。
入れ子になったモデルをうまく扱えません。そのため、リクエストのJSONボディが内部フィールドを持つJSONオブジェクトで、それが順番にネストされたJSONオブジェクトになっている場合、適切にドキュメント化やバリデーションをすることができません。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
素晴らしいエディターの補助を得るために、Pythonの型ヒントを利用している点。
`asyncio`に基づいた、Pythonのフレームワークの中でも非常に高速なものの一つです。Flaskと非常に似た作りになっています。
-/// note | "技術詳細"
+/// note | 技術詳細
Pythonの`asyncio`ループの代わりに、`uvloop`が利用されています。それにより、非常に高速です。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
物凄い性能を出す方法を見つけた点。
そのため、データのバリデーション、シリアライゼーション、ドキュメント化は、自動的にできずコードの中で行わなければなりません。あるいは、HugのようにFalconの上にフレームワークとして実装されなければなりません。このような分断は、パラメータとして1つのリクエストオブジェクトと1つのレスポンスオブジェクトを持つというFalconのデザインにインスピレーションを受けた他のフレームワークでも起こります。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
素晴らしい性能を得るための方法を見つけた点。
ルーティングは一つの場所で宣言され、他の場所で宣言された関数を使用します (エンドポイントを扱う関数のすぐ上に配置できるデコレータを使用するのではなく) 。これはFlask (やStarlette) よりも、Djangoに近いです。これは、比較的緊密に結合されているものをコードの中で分離しています。
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
モデルの属性の「デフォルト」値を使用したデータ型の追加バリデーションを定義します。これはエディタの補助を改善するもので、以前はPydanticでは利用できませんでした。
以前のPythonの同期型Webフレームワーク標準 (WSGI) をベースにしているため、Websocketなどは扱えませんが、それでも高性能です。
-/// info | "情報"
+/// info | 情報
HugはTimothy Crosleyにより作成されました。彼は<a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>など、Pythonのファイル内のインポートの並び替えを自動的におこうなう素晴らしいツールの開発者です。
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
HugはAPIStarに部分的なインスピレーションを与えており、私が発見した中ではAPIStarと同様に最も期待の持てるツールの一つでした。
今ではAPIStarはOpenAPI仕様を検証するためのツールセットであり、ウェブフレームワークではありません。
-/// info | "情報"
+/// info | 情報
APIStarはTom Christieにより開発されました。以下の開発者でもあります:
///
-/// check | "**FastAPI**へ与えたインスピレーション"
+/// check | **FastAPI**へ与えたインスピレーション
存在そのもの。
Marshmallowに匹敵しますが、ベンチマークではMarshmallowよりも高速です。また、Pythonの型ヒントを元にしているので、エディタの補助が素晴らしいです。
-/// check | "**FastAPI**での使用用途"
+/// check | **FastAPI**での使用用途
データのバリデーション、データのシリアライゼーション、自動的なモデルの (JSON Schemaに基づいた) ドキュメント化の全てを扱えます。
これは **FastAPI** が追加する主な機能の一つで、すべての機能は Pythonの型ヒントに基づいています (Pydanticを使用しています) 。これに加えて、依存性注入の仕組み、セキュリティユーティリティ、OpenAPIスキーマ生成などがあります。
-/// note | "技術詳細"
+/// note | 技術詳細
ASGIはDjangoのコアチームメンバーにより開発された新しい「標準」です。まだ「Pythonの標準 (PEP) 」ではありませんが、現在そうなるように進めています。
///
-/// check | "**FastAPI**での使用用途"
+/// check | **FastAPI**での使用用途
webに関するコアな部分を全て扱います。その上に機能を追加します。
Starletteや**FastAPI**のサーバーとして推奨されています。
-/// check | "**FastAPI**が推奨する理由"
+/// check | **FastAPI**が推奨する理由
**FastAPI**アプリケーションを実行するメインのウェブサーバーである点。
return results
```
-/// note | "備考"
+/// note | 備考
`async def` を使用して作成された関数の内部でしか `await` は使用できません。
## 非常に発展的な技術的詳細
-/// warning | "注意"
+/// warning | 注意
恐らくスキップしても良いでしょう。
`env/bin/pip`に`pip`バイナリが表示される場合は、正常に機能しています。🎉
-/// tip | "豆知識"
+/// tip | 豆知識
この環境で`pip`を使って新しいパッケージをインストールするたびに、仮想環境を再度有効化します。
そして、翻訳を処理するためのツール/スクリプトが、`./scripts/docs.py`に用意されています。
-/// tip | "豆知識"
+/// tip | 豆知識
`./scripts/docs.py`のコードを見る必要はなく、コマンドラインからただ使うだけです。
* あなたの言語の<a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">今あるプルリクエスト</a>を確認し、変更や承認をするレビューを追加します。
-/// tip | "豆知識"
+/// tip | 豆知識
すでにあるプルリクエストに<a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">修正提案つきのコメントを追加</a>できます。
スペイン語の場合、2文字のコードは`es`です。したがって、スペイン語のディレクトリは`docs/es/`です。
-/// tip | "豆知識"
+/// tip | 豆知識
メイン (「公式」) 言語は英語で、`docs/en/`にあります。
docs/es/docs/features.md
```
-/// tip | "豆知識"
+/// tip | 豆知識
パスとファイル名の変更は、`en`から`es`への言語コードだけであることに注意してください。
これで、新しく作成された`docs/ht/`ディレクトリをコードエディターから確認できます。
-/// tip | "豆知識"
+/// tip | 豆知識
翻訳を追加する前に、これだけで最初のプルリクエストを作成し、新しい言語の設定をセットアップします。
////
-/// tip | "豆知識"
+/// tip | 豆知識
`standard` を加えることで、Uvicornがインストールされ、いくつかの推奨される依存関係を利用するようになります。
FastAPIでは「パッチ」バージョンはバグ修正と非破壊的な変更に留めるという規約に従っています。
-/// tip | "豆知識"
+/// tip | 豆知識
「パッチ」は最後の数字を指します。例えば、`0.2.3` ではパッチバージョンは `3` です。
破壊的な変更と新機能実装は「マイナー」バージョンで加えられます。
-/// tip | "豆知識"
+/// tip | 豆知識
「マイナー」は真ん中の数字です。例えば、`0.2.3` ではマイナーバージョンは `2` です。
my_second_user: User = User(**second_user_data)
```
-/// info | "情報"
+/// info | 情報
`**second_user_data` は以下を意味します：
しかしたとえまったく **FastAPI** を使用しない場合でも、それらについて少し学ぶことで利点を得ることができるでしょう。
-/// note | "備考"
+/// note | 備考
もしあなたがPythonの専門家で、すでに型ヒントについてすべて知っているのであれば、次の章まで読み飛ばしてください。
{!../../docs_src/python_types/tutorial006.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
角括弧内の内部の型は「型パラメータ」と呼ばれています。
{!../../docs_src/python_types/tutorial011.py!}
```
-/// info | "情報"
+/// info | 情報
Pydanticについてより学びたい方は<a href="https://docs.pydantic.dev/" class="external-link" target="_blank">ドキュメントを参照してください</a>.
重要なのは、Pythonの標準的な型を使うことで、（クラスやデコレータなどを追加するのではなく）１つの場所で **FastAPI** が多くの作業を代わりにやってくれているということです。
-/// info | "情報"
+/// info | 情報
すでにすべてのチュートリアルを終えて、型についての詳細を見るためにこのページに戻ってきた場合は、<a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">`mypy`のチートシートを参照してください</a>
{!../../docs_src/body_fields/tutorial001.py!}
```
-/// warning | "注意"
+/// warning | 注意
`Field`は他の全てのもの（`Query`、`Path`、`Body`など）とは違い、`fastapi`からではなく、`pydantic`から直接インポートされていることに注意してください。
`Field`は`Query`や`Path`、`Body`と同じように動作し、全く同様のパラメータなどを持ちます。
-/// note | "技術詳細"
+/// note | 技術詳細
実際には次に見る`Query`や`Path`などは、共通の`Param`クラスのサブクラスのオブジェクトを作成しますが、それ自体はPydanticの`FieldInfo`クラスのサブクラスです。
///
-/// tip | "豆知識"
+/// tip | 豆知識
型、デフォルト値、`Field`を持つ各モデルの属性が、`Path`や`Query`、`Body`の代わりに`Field`を持つ、*path operation 関数の*パラメータと同じ構造になっていることに注目してください。
{!../../docs_src/body_multiple_params/tutorial001.py!}
```
-/// note | "備考"
+/// note | 備考
この場合、ボディから取得する`item`はオプションであることに注意してください。デフォルト値は`None`です。
}
```
-/// note | "備考"
+/// note | 備考
以前と同じように`item`が宣言されていたにもかかわらず、`item`はキー`item`を持つボディの内部にあることが期待されていることに注意してください。
{!../../docs_src/body_multiple_params/tutorial004.py!}
```
-/// info | "情報"
+/// info | 情報
`Body`もまた、後述する `Query` や `Path` などと同様に、すべての検証パラメータとメタデータパラメータを持っています。
}
```
-/// info | "情報"
+/// info | 情報
`images`キーが画像オブジェクトのリストを持つようになったことに注目してください。
{!../../docs_src/body_nested_models/tutorial007.py!}
```
-/// info | "情報"
+/// info | 情報
`Offer`は`Item`のリストであり、オプションの`Image`のリストを持っていることに注目してください。
{!../../docs_src/body_nested_models/tutorial009.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
JSONはキーとして`str`しかサポートしていないことに注意してください。
つまり、更新したいデータだけを送信して、残りはそのままにしておくことができます。
-/// note | "備考"
+/// note | 備考
`PATCH`は`PUT`よりもあまり使われておらず、知られていません。
{!../../docs_src/body_updates/tutorial002.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
実際には、HTTPの`PUT`操作でも同じテクニックを使用することができます。
///
-/// note | "備考"
+/// note | 備考
入力モデルがまだ検証されていることに注目してください。
**リクエスト** ボディを宣言するために <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> モデルを使用します。そして、その全てのパワーとメリットを利用します。
-/// info | "情報"
+/// info | 情報
データを送るには、`POST` (もっともよく使われる)、`PUT`、`DELETE` または `PATCH` を使うべきです。
<img src="/img/tutorial/body/image05.png">
-/// tip | "豆知識"
+/// tip | 豆知識
<a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>エディタを使用している場合は、<a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>が使用可能です。
* パラメータが**単数型** (`int`、`float`、`str`、`bool` など)の場合は**クエリ**パラメータとして解釈されます。
* パラメータが **Pydantic モデル**型で宣言された場合、リクエスト**ボディ**として解釈されます。
-/// note | "備考"
+/// note | 備考
FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。
{!../../docs_src/cookie_params/tutorial001.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
`Cookie`は`Path`と`Query`の「姉妹」クラスです。また、同じ共通の`Param`クラスを継承しています。
///
-/// info | "情報"
+/// info | 情報
クッキーを宣言するには、`Cookie`を使う必要があります。なぜなら、そうしないとパラメータがクエリのパラメータとして解釈されてしまうからです。
<abbr title="Cross-Origin Resource Sharing (オリジン間リソース共有)">CORS</abbr>についてより詳しい情報は、<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS documentation</a> を参照して下さい。
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.middleware.cors import CORSMiddleware` も使用できます。
は実行されません。
-/// info | "情報"
+/// info | 情報
より詳しい情報は、<a href="https://docs.python.org/3/library/__main__.html" class="external-link" target="_blank">公式Pythonドキュメント</a>を参照してください。
...そして **FastAPI** は何をすべきか知っています。
-/// tip | "豆知識"
+/// tip | 豆知識
役に立つというよりも、混乱するようであれば無視してください。それをする*必要*はありません。
これらの依存関係は、通常の依存関係と同様に実行・解決されます。しかし、それらの値（何かを返す場合）は*path operation関数*には渡されません。
-/// tip | "豆知識"
+/// tip | 豆知識
エディタによっては、未使用の関数パラメータをチェックしてエラーとして表示するものもあります。
これを行うには、`return`の代わりに`yield`を使い、その後に追加のステップを書きます。
-/// tip | "豆知識"
+/// tip | 豆知識
`yield`は必ず一度だけ使用するようにしてください。
///
-/// info | "情報"
+/// info | 情報
これを動作させるには、**Python 3.7** 以上を使用するか、**Python 3.6** では"backports"をインストールする必要があります:
///
-/// note | "技術詳細"
+/// note | 技術詳細
以下と一緒に使用できる関数なら何でも有効です:
{!../../docs_src/dependencies/tutorial007.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`async`や通常の関数を使用することができます。
**FastAPI** は、全てが正しい順序で実行されていることを確認します。
-/// note | "技術詳細"
+/// note | 技術詳細
これはPythonの<a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">Context Managers</a>のおかげで動作します。
レスポンスを返したり、レスポンスを変更したり、`HTTPException`を発生させたりする*前に*処理したいカスタム例外がある場合は、[カスタム例外ハンドラ](../handling-errors.md#_4){.internal-link target=_blank}を作成してください。
-/// tip | "豆知識"
+/// tip | 豆知識
`HTTPException`を含む例外は、`yield`の*前*でも発生させることができます。ただし、後ではできません。
end
```
-/// info | "情報"
+/// info | 情報
**１つのレスポンス** だけがクライアントに送信されます。それはエラーレスポンスの一つかもしれませんし、*path operation*からのレスポンスかもしれません。
///
-/// tip | "豆知識"
+/// tip | 豆知識
この図は`HTTPException`を示していますが、[カスタム例外ハンドラ](../handling-errors.md#_4){.internal-link target=_blank}を作成することで、他の例外を発生させることもできます。そして、その例外は依存関係の終了コードではなく、そのカスタム例外ハンドラによって処理されます。
### `yield`を持つ依存関係でのコンテキストマネージャの使用
-/// warning | "注意"
+/// warning | 注意
これは多かれ少なかれ、「高度な」発想です。
{!../../docs_src/dependencies/tutorial010.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
コンテキストマネージャを作成するもう一つの方法はwithです:
そして、その関数は、*path operation関数*が行うのと同じ方法でパラメータを取ります。
-/// tip | "豆知識"
+/// tip | 豆知識
次の章では、関数以外の「もの」が依存関係として使用できるものを見ていきます。
この方法では、共有されるコードを一度書き、**FastAPI** が*path operations*のための呼び出しを行います。
-/// check | "確認"
+/// check | 確認
特別なクラスを作成してどこかで **FastAPI** に渡して「登録」する必要はないことに注意してください。
それは重要ではありません。**FastAPI** は何をすべきかを知っています。
-/// note | "備考"
+/// note | 備考
わからない場合は、ドキュメントの[Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank}の中の`async`と`await`についてのセクションを確認してください。
{!../../docs_src/dependencies/tutorial005.py!}
```
-/// info | "情報"
+/// info | 情報
*path operation関数*の中で宣言している依存関係は`query_or_cookie_extractor`の１つだけであることに注意してください。
しかし、それでも非常に強力で、任意の深くネストされた依存関係「グラフ」（ツリー）を宣言することができます。
-/// tip | "豆知識"
+/// tip | 豆知識
これらの単純な例では、全てが役に立つとは言えないかもしれません。
これはJSON形式のデータを含む大きな`str`を（文字列として）返しません。JSONと互換性のある値とサブの値を持つPython標準のデータ構造（例：`dict`）を返します。
-/// note | "備考"
+/// note | 備考
`jsonable_encoder`は実際には **FastAPI** が内部的にデータを変換するために使用します。しかしこれは他の多くのシナリオで有用です。
* **出力モデル**はパスワードをもつべきではありません。
* **データベースモデル**はおそらくハッシュ化されたパスワードが必要になるでしょう。
-/// danger | "危険"
+/// danger | 危険
ユーザーの平文のパスワードは絶対に保存しないでください。常に認証に利用可能な「安全なハッシュ」を保存してください。
)
```
-/// warning | "注意"
+/// warning | 注意
サポートしている追加機能は、データの可能な流れをデモするだけであり、もちろん本当のセキュリティを提供しているわけではありません。
</div>
-/// note | "備考"
+/// note | 備考
`uvicorn main:app`は以下を示します:
`FastAPI`は、APIのすべての機能を提供するPythonクラスです。
-/// note | "技術詳細"
+/// note | 技術詳細
`FastAPI`は`Starlette`を直接継承するクラスです。
/items/foo
```
-/// info | "情報"
+/// info | 情報
「パス」は一般に「エンドポイント」または「ルート」とも呼ばれます。
* パス `/`
* <abbr title="an HTTP GET method"><code>get</code> オペレーション</abbr>
-/// info | "`@decorator` について"
+/// info | `@decorator` について
Pythonにおける`@something`シンタックスはデコレータと呼ばれます。
* `@app.patch()`
* `@app.trace()`
-/// tip | "豆知識"
+/// tip | 豆知識
各オペレーション (HTTPメソッド)は自由に使用できます。
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "備考"
+/// note | 備考
違いが分からない場合は、[Async: *"急いでいますか？"*](../async.md#_1){.internal-link target=_blank}を確認してください。
}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`HTTPException`を発生させる際には、`str`だけでなく、JSONに変換できる任意の値を`detail`パラメータとして渡すことができます。
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "技術詳細"
+/// note | 技術詳細
また、`from starlette.requests import Request`と`from starlette.responses import JSONResponse`を使用することもできます。
#### `RequestValidationError`と`ValidationError`
-/// warning | "注意"
+/// warning | 注意
これらは今のあなたにとって重要でない場合は省略しても良い技術的な詳細です。
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
また、`from starlette.responses import PlainTextResponse`を使用することもできます。
{!../../docs_src/header_params/tutorial001.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
`Header`は`Path`や`Query`、`Cookie`の「姉妹」クラスです。また、同じ共通の`Param`クラスを継承しています。
///
-/// info | "情報"
+/// info | 情報
ヘッダーを宣言するには、`Header`を使う必要があります。なぜなら、そうしないと、パラメータがクエリのパラメータとして解釈されてしまうからです。
{!../../docs_src/header_params/tutorial002.py!}
```
-/// warning | "注意"
+/// warning | 注意
`convert_underscores`を`False`に設定する前に、HTTPプロキシやサーバの中にはアンダースコアを含むヘッダーの使用を許可していないものがあることに注意してください。
...これには、コードを実行するサーバーとして使用できる `uvicorn`も含まれます。
-/// note | "備考"
+/// note | 備考
パーツ毎にインストールすることも可能です。
説明文 (description) の中で Markdown を使用できることに注意してください。たとえば、「login」は太字 (**login**) で表示され、「fancy」は斜体 (_fancy_) で表示されます。
-/// tip | "豆知識"
+/// tip | 豆知識
使用するすべてのタグにメタデータを追加する必要はありません。
{!../../docs_src/metadata/tutorial004.py!}
```
-/// info | "情報"
+/// info | 情報
タグのより詳しい説明を知りたい場合は [Path Operation Configuration](path-operation-configuration.md#tags){.internal-link target=_blank} を参照して下さい。
* その**レスポンス**に対して何かを実行したり、必要なコードを実行したりできます。
* そして、**レスポンス**を返します。
-/// note | "技術詳細"
+/// note | 技術詳細
`yield` を使った依存関係をもつ場合は、終了コードはミドルウェアの *後に* 実行されます。
{!../../docs_src/middleware/tutorial001.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">'X-'プレフィックスを使用</a>してカスタムの独自ヘッダーを追加できます。
///
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.requests import Request` を使用することもできます。
*path operationデコレータ*を設定するためのパラメータがいくつかあります。
-/// warning | "注意"
+/// warning | 注意
これらのパラメータは*path operation関数*ではなく、*path operationデコレータ*に直接渡されることに注意してください。
そのステータスコードはレスポンスで使用され、OpenAPIスキーマに追加されます。
-/// note | "技術詳細"
+/// note | 技術詳細
また、`from starlette import status`を使用することもできます。
{!../../docs_src/path_operation_configuration/tutorial005.py!}
```
-/// info | "情報"
+/// info | 情報
`respnse_description`は具体的にレスポンスを参照し、`description`は*path operation*全般を参照していることに注意してください。
///
-/// check | "確認"
+/// check | 確認
OpenAPIは*path operation*ごとにレスポンスの説明を必要としています。
{!../../docs_src/path_params_numeric_validations/tutorial001.py!}
```
-/// note | "備考"
+/// note | 備考
パスの一部でなければならないので、パスパラメータは常に必須です。
* `lt`: より小さい（`l`ess `t`han）
* `le`: 以下（`l`ess than or `e`qual）
-/// info | "情報"
+/// info | 情報
`Query`、`Path`などは後に共通の`Param`クラスのサブクラスを見ることになります。（使う必要はありません）
///
-/// note | "技術詳細"
+/// note | 技術詳細
`fastapi`から\b`Query`、`Path`などをインポートすると、これらは実際には関数です。
ここでは、 `item_id` は `int` として宣言されています。
-/// check | "確認"
+/// check | 確認
これにより、関数内でのエディターサポート (エラーチェックや補完など) が提供されます。
{"item_id":3}
```
-/// check | "確認"
+/// check | 確認
関数が受け取った（および返した）値は、文字列の `"3"` ではなく、Pythonの `int` としての `3` であることに注意してください。
<a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a> で見られるように、intのかわりに `float` が与えられた場合にも同様なエラーが表示されます。
-/// check | "確認"
+/// check | 確認
したがって、Pythonの型宣言を使用することで、**FastAPI**はデータのバリデーションを行います。
<img src="/img/tutorial/path-params/image01.png">
-/// check | "確認"
+/// check | 確認
繰り返しになりますが、Python型宣言を使用するだけで、**FastAPI**は対話的なAPIドキュメントを自動的に生成します（Swagger UIを統合）。
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "情報"
+/// info | 情報
<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">Enumerations (もしくは、enums)はPython 3.4以降で利用できます</a>。
///
-/// tip | "豆知識"
+/// tip | 豆知識
"AlexNet"、"ResNet"そして"LeNet"は機械学習<abbr title="Technically, Deep Learning model architectures">モデル</abbr>の名前です。
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`ModelName.lenet.value` でも `"lenet"` 値にアクセスできます。
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
最初のスラッシュ (`/`)が付いている `/home/johndoe/myfile.txt` をパラメータが含んでいる必要があります。
クエリパラメータ `q` は `Optional[str]` 型で、`None` を許容する `str` 型を意味しており、デフォルトは `None` です。そのため、FastAPIはそれが必須ではないと理解します。
-/// note | "備考"
+/// note | 備考
FastAPIは、 `q` はデフォルト値が `=None` であるため、必須ではないと理解します。
しかし、これはクエリパラメータとして明示的に宣言しています。
-/// info | "情報"
+/// info | 情報
FastAPIは以下の部分を気にすることを覚えておいてください:
{!../../docs_src/query_params_str_validations/tutorial005.py!}
```
-/// note | "備考"
+/// note | 備考
デフォルト値を指定すると、パラメータは任意になります。
{!../../docs_src/query_params_str_validations/tutorial006.py!}
```
-/// info | "情報"
+/// info | 情報
これまで`...`を見たことがない方へ: これは特殊な単一値です。<a href="https://docs.python.org/3/library/constants.html#Ellipsis" class="external-link" target="_blank">Pythonの一部であり、"Ellipsis"と呼ばれています</a>。
}
```
-/// tip | "豆知識"
+/// tip | 豆知識
上述の例のように、`list`型のクエリパラメータを宣言するには明示的に`Query`を使用する必要があります。そうしない場合、リクエストボディと解釈されます。
{!../../docs_src/query_params_str_validations/tutorial013.py!}
```
-/// note | "備考"
+/// note | 備考
この場合、FastAPIはリストの内容をチェックしないことを覚えておいてください。
その情報は、生成されたOpenAPIに含まれ、ドキュメントのユーザーインターフェースや外部のツールで使用されます。
-/// note | "備考"
+/// note | 備考
ツールによってOpenAPIのサポートのレベルが異なる可能性があることを覚えておいてください。
この場合、関数パラメータ `q` はオプショナルとなり、デフォルトでは `None` になります。
-/// check | "確認"
+/// check | 確認
パスパラメータ `item_id` はパスパラメータであり、`q` はそれとは違ってクエリパラメータであると判別できるほど**FastAPI** が賢いということにも注意してください。
* `skip`、デフォルト値を `0` とする `int` 。
* `limit`、オプショナルな `int` 。
-/// tip | "豆知識"
+/// tip | 豆知識
[パスパラメータ](path-params.md#_8){.internal-link target=_blank}と同様に `Enum` を使用できます。
`File`と`Form`を同時に使うことでファイルとフォームフィールドを定義することができます。
-/// info | "情報"
+/// info | 情報
アップロードされたファイルやフォームデータを受信するには、まず<a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>をインストールします。
また、いくつかのファイルを`bytes`として、いくつかのファイルを`UploadFile`として宣言することができます。
-/// warning | "注意"
+/// warning | 注意
*path operation*で複数の`File`と`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストのボディは`application/json`の代わりに`multipart/form-data`を使ってエンコードされているからです。
JSONの代わりにフィールドを受け取る場合は、`Form`を使用します。
-/// info | "情報"
+/// info | 情報
フォームを使うためには、まず<a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>をインストールします。
`Form`では`Body`（および`Query`や`Path`、`Cookie`）と同じメタデータとバリデーションを宣言することができます。
-/// info | "情報"
+/// info | 情報
`Form`は`Body`を直接継承するクラスです。
///
-/// tip | "豆知識"
+/// tip | 豆知識
フォームのボディを宣言するには、明示的に`Form`を使用する必要があります。なぜなら、これを使わないと、パラメータはクエリパラメータやボディ（JSON）パラメータとして解釈されるからです。
**FastAPI** は、JSONの代わりにそのデータを適切な場所から読み込むようにします。
-/// note | "技術詳細"
+/// note | 技術詳細
フォームからのデータは通常、`application/x-www-form-urlencoded`の「media type」を使用してエンコードされます。
///
-/// warning | "注意"
+/// warning | 注意
*path operation*で複数の`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストは`application/json`の代わりに`application/x-www-form-urlencoded`を使ってボディをエンコードするからです。
{!../../docs_src/response_model/tutorial001.py!}
```
-/// note | "備考"
+/// note | 備考
`response_model`は「デコレータ」メソッド（`get`、`post`など）のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数* のパラメータではありません。
* 出力データをモデルのデータに限定します。これがどのように重要なのか以下で見ていきましょう。
-/// note | "技術詳細"
+/// note | 技術詳細
レスポンスモデルは、関数の戻り値のアノテーションではなく、このパラメータで宣言されています。なぜなら、パス関数は実際にはそのレスポンスモデルを返すのではなく、`dict`やデータベースオブジェクト、あるいは他のモデルを返し、`response_model`を使用してフィールドの制限やシリアライズを行うからです。
しかし、同じモデルを別の*path operation*に使用すると、すべてのクライアントにユーザーのパスワードを送信してしまうことになります。
-/// danger | "危険"
+/// danger | 危険
ユーザーの平文のパスワードを保存したり、レスポンスで送信したりすることは絶対にしないでください。
}
```
-/// info | "情報"
+/// info | 情報
FastAPIはこれをするために、Pydanticモデルの`.dict()`を<a href="https://docs.pydantic.dev/latest/concepts/serialization/#modeldict" class="external-link" target="_blank">その`exclude_unset`パラメータ</a>で使用しています。
///
-/// info | "情報"
+/// info | 情報
以下も使用することができます:
そのため、それらはJSONレスポンスに含まれることになります。
-/// tip | "豆知識"
+/// tip | 豆知識
デフォルト値は`None`だけでなく、なんでも良いことに注意してください。
例えば、リスト（`[]`）や`10.5`の`float`などです。
これは、Pydanticモデルが１つしかなく、出力からいくつかのデータを削除したい場合のクイックショートカットとして使用することができます。
-/// tip | "豆知識"
+/// tip | 豆知識
それでも、これらのパラメータではなく、複数のクラスを使用して、上記のようなアイデアを使うことをおすすめします。
{!../../docs_src/response_model/tutorial005.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
`{"name", "description"}`の構文はこれら２つの値をもつ`set`を作成します。
{!../../docs_src/response_status_code/tutorial001.py!}
```
-/// note | "備考"
+/// note | 備考
`status_code`は「デコレータ」メソッド（`get`、`post`など）のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数*のものではありません。
`status_code`パラメータはHTTPステータスコードを含む数値を受け取ります。
-/// info | "情報"
+/// info | 情報
`status_code`は代わりに、Pythonの<a href="https://docs.python.org/3/library/http.html#http.HTTPStatus" class="external-link" target="_blank">`http.HTTPStatus`</a>のように、`IntEnum`を受け取ることもできます。
<img src="https://fastapi.tiangolo.com/img/tutorial/response-status-code/image01.png">
-/// note | "備考"
+/// note | 備考
いくつかのレスポンスコード（次のセクションを参照）は、レスポンスにボディがないことを示しています。
## HTTPステータスコードについて
-/// note | "備考"
+/// note | 備考
すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。
* クライアントからの一般的なエラーについては、`400`を使用することができます。
* `500`以上はサーバーエラーのためのものです。これらを直接使うことはほとんどありません。アプリケーションコードやサーバーのどこかで何か問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。
-/// tip | "豆知識"
+/// tip | 豆知識
それぞれのステータスコードとどのコードが何のためのコードなのかについて詳細は<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> HTTP レスポンスステータスコードについてのドキュメント</a>を参照してください。
<img src="https://fastapi.tiangolo.com/img/tutorial/response-status-code/image02.png">
-/// note | "技術詳細"
+/// note | 技術詳細
また、`from starlette import status`を使うこともできます。
{!../../docs_src/schema_extra_example/tutorial002.py!}
```
-/// warning | "注意"
+/// warning | 注意
これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。
## 実行
-/// info | "情報"
+/// info | 情報
まず<a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>をインストールします。
<img src="/img/tutorial/security/image01.png">
-/// check | "Authorizeボタン!"
+/// check | Authorizeボタン!
すでにピカピカの新しい「Authorize」ボタンがあります。
<img src="/img/tutorial/security/image02.png">
-/// note | "備考"
+/// note | 備考
フォームに何を入力しても、まだうまくいきません。ですが、これから動くようになります。
この例では、**Bearer**トークンを使用して**OAuth2**を**パスワード**フローで使用します。これには`OAuth2PasswordBearer`クラスを使用します。
-/// info | "情報"
+/// info | 情報
「bearer」トークンが、唯一の選択肢ではありません。
{!../../docs_src/security/tutorial001.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
ここで、`tokenUrl="token"`は、まだ作成していない相対URL`token`を指します。相対URLなので、`./token`と同じです。
実際のpath operationもすぐに作ります。
-/// info | "情報"
+/// info | 情報
非常に厳格な「Pythonista」であれば、パラメーター名のスタイルが`token_url`ではなく`tokenUrl`であることを気に入らないかもしれません。
**FastAPI**は、この依存関係を使用してOpenAPIスキーマ (および自動APIドキュメント) で「セキュリティスキーム」を定義できることを知っています。
-/// info | "技術詳細"
+/// info | 技術詳細
**FastAPI**は、`OAuth2PasswordBearer` クラス (依存関係で宣言されている) を使用してOpenAPIのセキュリティスキームを定義できることを知っています。これは`fastapi.security.oauth2.OAuth2`、`fastapi.security.base.SecurityBase`を継承しているからです。
その関数の中ですべての入力補完や型チェックを行う際に役に立ちます。
-/// tip | "豆知識"
+/// tip | 豆知識
リクエストボディはPydanticモデルでも宣言できることを覚えているかもしれません。
///
-/// check | "確認"
+/// check | 確認
依存関係システムがこのように設計されているおかげで、 `User` モデルを返却する別の依存関係（別の"dependables"）を持つことができます。
OAuth2は、通信を暗号化する方法を指定せず、アプリケーションがHTTPSで提供されることを想定しています。
-/// tip | "豆知識"
+/// tip | 豆知識
**デプロイ**のセクションでは、TraefikとLet's Encryptを使用して、無料でHTTPSを設定する方法が紹介されています。
* この自動検出メカニズムは、OpenID Connectの仕様で定義されているものです。
-/// tip | "豆知識"
+/// tip | 豆知識
Google、Facebook、Twitter、GitHubなど、他の認証/認可プロバイダを統合することも可能で、比較的簡単です。
ここでは、推奨されているものを使用します：<a href="https://cryptography.io/" class="external-link" target="_blank">pyca/cryptography</a>。
-/// tip | "豆知識"
+/// tip | 豆知識
このチュートリアルでは以前、<a href="https://pyjwt.readthedocs.io/" class="external-link" target="_blank">PyJWT</a>を使用していました。
</div>
-/// tip | "豆知識"
+/// tip | 豆知識
`passlib`を使用すると、**Django**や**Flask**のセキュリティプラグインなどで作成されたパスワードを読み取れるように設定できます。
PassLib の「context」を作成します。これは、パスワードのハッシュ化と検証に使用されるものです。
-/// tip | "豆知識"
+/// tip | 豆知識
PassLibのcontextには、検証だけが許された非推奨の古いハッシュアルゴリズムを含む、様々なハッシュアルゴリズムを使用した検証機能もあります。
{!../../docs_src/security/tutorial004.py!}
```
-/// note | "備考"
+/// note | 備考
新しい（偽の）データベース`fake_users_db`を確認すると、ハッシュ化されたパスワードが次のようになっていることがわかります：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`
Username: `johndoe`
Password: `secret`
-/// check | "確認"
+/// check | 確認
コードのどこにも平文のパスワード"`secret`"はなく、ハッシュ化されたものしかないことを確認してください。
<img src="/img/tutorial/security/image10.png">
-/// note | "備考"
+/// note | 備考
ヘッダーの`Authorization`には、`Bearer`で始まる値があります。
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.staticfiles import StaticFiles` も使用できます。
{!../../docs_src/app_testing/tutorial001.py!}
```
-/// tip | "豆知識"
+/// tip | 豆知識
テスト関数は `async def` ではなく、通常の `def` であることに注意してください。
///
-/// note | "技術詳細"
+/// note | 技術詳細
`from starlette.testclient import TestClient` も使用できます。
///
-/// tip | "豆知識"
+/// tip | 豆知識
FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。
(`httpx` または `TestClient` を使用して) バックエンドにデータを渡す方法の詳細は、<a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPXのドキュメント</a>を確認してください。
-/// info | "情報"
+/// info | 情報
`TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。
이 함수들은 `async def` 또는 평범하게 `def`으로 선언할 수 있습니다.
-/// warning | "경고"
+/// warning | 경고
이벤트 핸들러는 주 응용 프로그램에서만 작동합니다. [하위 응용 프로그램 - 마운트](./sub-applications.md){.internal-link target=_blank}에서는 작동하지 않습니다.
이 예제에서 `shutdown` 이벤트 핸들러 함수는 `"Application shutdown"`이라는 텍스트가 적힌 `log.txt` 파일을 추가할 것입니다.
-/// info | "정보"
+/// info | 정보
`open()` 함수에서 `mode="a"`는 "추가"를 의미합니다. 따라서 이미 존재하는 파일의 내용을 덮어쓰지 않고 새로운 줄을 추가합니다.
///
-/// tip | "팁"
+/// tip | 팁
이 예제에서는 파일과 상호작용 하기 위해 파이썬 표준 함수인 `open()`을 사용하고 있습니다.
///
-/// info | "정보"
+/// info | 정보
이벤트 핸들러에 관한 내용은 <a href="https://www.starlette.io/events/" class="external-link" target="_blank">Starlette 이벤트 문서</a>에서 추가로 확인할 수 있습니다.
이어지는 장에서는 여러분이 다른 옵션, 구성 및 추가 기능을 보실 수 있습니다.
-/// tip | "팁"
+/// tip | 팁
다음 장들이 **반드시 "심화"**인 것은 아닙니다.
### 추가 정보
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette.responses import Response` 또는 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
{!../../docs_src/response_directly/tutorial001.py!}
```
-/// note | "기술적 세부 사항"
+/// note | 기술적 세부 사항
`from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
{!../../docs_src/response_headers/tutorial001.py!}
```
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette.responses import Response`나 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
return results
```
-/// note | "참고"
+/// note | 참고
`async def`로 생성된 함수 내부에서만 `await`를 사용할 수 있습니다.
## 매우 세부적인 기술적 사항
-/// warning | "경고"
+/// warning | 경고
이 부분은 넘어가도 됩니다.
리눅스 컨테이너를 사용하는 데에는 **보안**, **반복 가능성**, **단순함** 등의 장점이 있습니다.
-/// tip | "팁"
+/// tip | 팁
시간에 쫓기고 있고 이미 이런것들을 알고 있다면 [`Dockerfile`👇](#build-a-docker-image-for-fastapi)로 점프할 수 있습니다.
</div>
-/// info | "정보"
+/// info | 정보
패키지 종속성을 정의하고 설치하기 위한 방법과 도구는 다양합니다.
프로그램이 `/code`에서 시작하고 그 속에 `./app` 디렉터리가 여러분의 코드와 함께 들어있기 때문에, **Uvicorn**은 이를 보고 `app`을 `app.main`으로부터 **불러 올** 것입니다.
-/// tip | "팁"
+/// tip | 팁
각 코드 라인을 코드의 숫자 버블을 클릭하여 리뷰할 수 있습니다. 👆
</div>
-/// tip | "팁"
+/// tip | 팁
맨 끝에 있는 `.` 에 주목합시다. 이는 `./`와 동등하며, 도커에게 컨테이너 이미지를 빌드하기 위한 디렉터리를 알려줍니다.
**HTTPS**와 **인증서**의 **자동** 취득을 다루는 것은 다른 컨테이너가 될 수 있는데, 예를 들어 <a href="https://traefik.io/" class="external-link" target="_blank">Traefik</a>을 사용하는 것입니다.
-/// tip | "팁"
+/// tip | 팁
Traefik은 도커, 쿠버네티스, 그리고 다른 도구와 통합되어 있어 여러분의 컨테이너를 포함하는 HTTPS를 셋업하고 설정하는 것이 매우 쉽습니다.
이 요소가 요청들의 **로드**를 읽어들이고 각 워커에게 (바라건대) **균형적으로** 분배한다면, 이 요소는 일반적으로 **로드 밸런서**라고 불립니다.
-/// tip | "팁"
+/// tip | 팁
HTTPS를 위해 사용된 **TLS 종료 프록시** 요소 또한 **로드 밸런서**가 될 수 있습니다.
만약 여러분이 **여러개의 컨테이너**를 가지고 있다면, 아마도 각각의 컨테이너는 **하나의 프로세스**를 가지고 있을 것입니다(예를 들어, **쿠버네티스** 클러스터에서). 그러면 여러분은 복제된 워커 컨테이너를 실행하기 **이전에**, 하나의 컨테이너에 있는 **이전의 단계들을** 수행하는 단일 프로세스를 가지는 **별도의 컨테이너들**을 가지고 싶을 것입니다.
-/// info | "정보"
+/// info | 정보
만약 여러분이 쿠버네티스를 사용하고 있다면, 아마도 이는 <a href="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" class="external-link" target="_blank">Init Container</a>일 것입니다.
* <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
-/// warning | "경고"
+/// warning | 경고
여러분이 이 베이스 이미지 또는 다른 유사한 이미지를 필요로 하지 **않을** 높은 가능성이 있으며, [위에서 설명된 것처럼: FastAPI를 위한 도커 이미지 빌드하기](#build-a-docker-image-for-fastapi) 처음부터 이미지를 빌드하는 것이 더 나을 수 있습니다.
또한 스크립트를 통해 <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker#pre_start_path" class="external-link" target="_blank">**시작하기 전 사전 단계**</a>를 실행하는 것을 지원합니다.
-/// tip | "팁"
+/// tip | 팁
모든 설정과 옵션을 보려면, 도커 이미지 페이지로 이동합니다: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
11. `uvicorn` 커맨드를 실행하여, `app.main`에서 불러온 `app` 객체를 사용하도록 합니다.
-/// tip | "팁"
+/// tip | 팁
버블 숫자를 클릭해 각 줄이 하는 일을 알아볼 수 있습니다.
지금부터 <a href="https://gunicorn.org/" class="external-link" target="_blank">**구니콘**</a>을 **유비콘 워커 프로세스**와 함께 사용하는 방법을 알려드리겠습니다.
-/// info | "정보"
+/// info | 정보
만약 도커와 쿠버네티스 같은 컨테이너를 사용하고 있다면 다음 챕터 [FastAPI와 컨테이너 - 도커](docker.md){.internal-link target=_blank}에서 더 많은 정보를 얻을 수 있습니다.
FastAPI는 오류를 수정하고, 일반적인 변경사항을 위해 "패치"버전의 관습을 따릅니다.
-/// tip | "팁"
+/// tip | 팁
여기서 말하는 "패치"란 버전의 마지막 숫자로, 예를 들어 `0.2.3` 버전에서 "패치"는 `3`을 의미합니다.
수정된 사항과 새로운 요소들이 "마이너" 버전에 추가되었습니다.
-/// tip | "팁"
+/// tip | 팁
"마이너"란 버전 넘버의 가운데 숫자로, 예를 들어서 `0.2.3`의 "마이너" 버전은 `2`입니다.
# 환경 변수
-/// tip | "팁"
+/// tip | 팁
만약 "환경 변수"가 무엇이고, 어떻게 사용하는지 알고 계시다면, 이 챕터를 스킵하셔도 좋습니다.
print(f"Hello {name} from Python")
```
-/// tip | "팁"
+/// tip | 팁
<a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> 의 두 번째 인자는 반환할 기본값입니다.
</div>
-/// tip | "팁"
+/// tip | 팁
<a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a> 에서 좀 더 자세히 알아볼 수 있습니다.
my_second_user: User = User(**second_user_data)
```
-/// info | "정보"
+/// info | 정보
`**second_user_data`가 뜻하는 것:
비록 **FastAPI**를 쓰지 않는다고 하더라도, 조금이라도 알아두면 도움이 될 것입니다.
-/// note | "참고"
+/// note | 참고
파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요.
{!../../docs_src/python_types/tutorial006.py!}
```
-/// tip | "팁"
+/// tip | 팁
대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다.
{!../../docs_src/python_types/tutorial011.py!}
```
-/// info | "정보"
+/// info | 정보
Pydantic<에 대해 더 배우고 싶다면 <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">공식 문서</a>를 참고하세요.</a>
가장 중요한 건, 표준 파이썬 타입을 한 곳에서(클래스를 더하거나, 데코레이터 사용하는 대신) 사용함으로써 **FastAPI**가 당신을 위해 많은 일을 해준다는 사실이죠.
-/// info | "정보"
+/// info | 정보
만약 모든 자습서를 다 보았음에도 타입에 대해서 더 보고자 방문한 경우에는 <a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">`mypy`에서 제공하는 "cheat sheet"</a>이 좋은 자료가 될 겁니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
////
-/// warning | "경고"
+/// warning | 경고
`Field`는 다른 것들처럼 (`Query`, `Path`, `Body` 등) `fastapi`에서가 아닌 `pydantic`에서 바로 임포트 되는 점에 주의하세요.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
`Field`는 `Query`, `Path`와 `Body`와 같은 방식으로 동작하며, 모두 같은 매개변수들 등을 가집니다.
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
실제로 `Query`, `Path`등, 여러분이 앞으로 볼 다른 것들은 공통 클래스인 `Param` 클래스의 서브클래스 객체를 만드는데, 그 자체로 Pydantic의 `FieldInfo` 클래스의 서브클래스입니다.
///
-/// tip | "팁"
+/// tip | 팁
주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 작동 함수*의 매개변수와 같은 구조를 가진다는 점 입니다.
여러분이 예제를 선언할 때 나중에 이 공식 문서에서 별도 정보를 추가하는 방법을 배울 것입니다.
-/// warning | "경고"
+/// warning | 경고
별도 키가 전달된 `Field` 또한 여러분의 어플리케이션의 OpenAPI 스키마에 나타날 것입니다.
이런 키가 OpenAPI 명세서, [the OpenAPI validator](https://validator.swagger.io/)같은 몇몇 OpenAPI 도구들에 포함되지 못할 수 있으며, 여러분이 생성한 스키마와 호환되지 않을 수 있습니다.
{!../../docs_src/body_multiple_params/tutorial001.py!}
```
-/// note | "참고"
+/// note | 참고
이 경우에는 본문으로 부터 가져온 ` item`은 기본값이 `None`이기 때문에, 선택사항이라는 점을 유의해야 합니다.
}
```
-/// note | "참고"
+/// note | 참고
이전과 같이 `item`이 선언 되었더라도, 본문 내의 `item` 키가 있을 것이라고 예측합니다.
q: Optional[str] = None
```
-/// info | "정보"
+/// info | 정보
`Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들처럼 동일한 추가 검증과 메타데이터 매개변수를 갖고 있습니다.
}
```
-/// info | "정보"
+/// info | 정보
`images` 키가 어떻게 이미지 객체 리스트를 갖는지 주목하세요.
{!../../docs_src/body_nested_models/tutorial007.py!}
```
-/// info | "정보"
+/// info | 정보
`Offer`가 선택사항 `Image` 리스트를 차례로 갖는 `Item` 리스트를 어떻게 가지고 있는지 주목하세요
{!../../docs_src/body_nested_models/tutorial009.py!}
```
-/// tip | "팁"
+/// tip | 팁
JSON은 오직 `str`형 키만 지원한다는 것을 염두에 두세요.
**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> 모델을 사용합니다.
-/// info | "정보"
+/// info | 정보
데이터를 보내기 위해, (좀 더 보편적인) `POST`, `PUT`, `DELETE` 혹은 `PATCH` 중에 하나를 사용하는 것이 좋습니다.
<img src="/img/tutorial/body/image05.png">
-/// tip | "팁"
+/// tip | 팁
만약 <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>를 편집기로 사용한다면, <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>을 사용할 수 있습니다.
* 만약 매개변수가 (`int`, `float`, `str`, `bool` 등과 같은) **유일한 타입**으로 되어있으면, **쿼리** 매개변수로 해석될 것입니다.
* 만약 매개변수가 **Pydantic 모델** 타입으로 선언되어 있으면, 요청 **본문**으로 해석될 것입니다.
-/// note | "참고"
+/// note | 참고
FastAPI는 `q`의 값이 필요없음을 알게 될 것입니다. 기본 값이 `= None`이기 때문입니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
////
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
`Cookie`는 `Path` 및 `Query`의 "자매"클래스입니다. 이 역시 동일한 공통 `Param` 클래스를 상속합니다.
///
-/// info | "정보"
+/// info | 정보
쿠키를 선언하기 위해서는 `Cookie`를 사용해야 합니다. 그렇지 않으면 해당 매개변수를 쿼리 매개변수로 해석하기 때문입니다.
<abbr title="교차-출처 리소스 공유">CORS</abbr>에 대한 더 많은 정보를 알고싶다면, <a href="https://developer.mozilla.org/ko/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS 문서</a>를 참고하기 바랍니다.
-/// note | "기술적 세부 사항"
+/// note | 기술적 세부 사항
`from starlette.middleware.cors import CORSMiddleware` 역시 사용할 수 있습니다.
은 실행되지 않습니다.
-/// info | "정보"
+/// info | 정보
자세한 내용은 <a href="https://docs.python.org/3/library/__main__.html" class="external-link" target="_blank">공식 Python 문서</a>를 확인하세요
...이렇게 코드를 단축하여도 **FastAPI**는 무엇을 해야하는지 알고 있습니다.
-/// tip | "팁"
+/// tip | 팁
만약 이것이 도움이 되기보다 더 헷갈리게 만든다면, 잊어버리십시오. 이것이 반드시 필요한 것은 아닙니다.
//// tab | Python 3.8 Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
이러한 의존성들은 기존 의존성들과 같은 방식으로 실행/해결됩니다. 그러나 값은 (무엇이든 반환한다면) *경로 작동 함수*에 제공되지 않습니다.
-/// tip | "팁"
+/// tip | 팁
일부 편집기에서는 사용되지 않는 함수 매개변수를 검사하고 오류로 표시합니다.
///
-/// info | "정보"
+/// info | 정보
이 예시에서 `X-Key`와 `X-Token`이라는 커스텀 헤더를 만들어 사용했습니다.
//// tab | Python 3.8 Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8 Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8 Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8 Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
그 후 위의 값을 포함한 `dict` 자료형으로 반환할 뿐입니다.
-/// info | "정보"
+/// info | 정보
FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 사용하기 권장합니다) 추가했습니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.10+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
//// tab | Python 3.8+ Annotated가 없는 경우
-/// tip | "팁"
+/// tip | 팁
가능하다면 `Annotated`가 달린 버전을 권장합니다.
그리고 그 함수는 *경로 작동 함수*가 작동하는 것과 같은 방식으로 매개변수를 받습니다.
-/// tip | "팁"
+/// tip | 팁
여러분은 다음 장에서 함수를 제외하고서, "다른 것들"이 어떻게 의존성으로 사용되는지 알게 될 것입니다.
이렇게 하면 공용 코드를 한번만 적어도 되며, **FastAPI**는 *경로 작동*을 위해 이에 대한 호출을 처리합니다.
-/// check | "확인"
+/// check | 확인
특별한 클래스를 만들지 않아도 되며, 이러한 것 혹은 비슷한 종류를 **FastAPI**에 "등록"하기 위해 어떤 곳에 넘겨주지 않아도 됩니다.
////
-/// tip | "팁"
+/// tip | 팁
이는 그저 표준 파이썬이고 "type alias"라고 부르며 사실 **FastAPI**에 국한되는 것은 아닙니다.
아무 문제 없습니다. **FastAPI**는 무엇을 할지 알고 있습니다.
-/// note | "참고"
+/// note | 참고
잘 모르시겠다면, [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} 문서에서 `async`와 `await`에 대해 확인할 수 있습니다.
길이가 긴 문자열 형태의 JSON 형식(문자열)의 데이터가 들어있는 상황에서는 `str`로 반환하지 않습니다. JSON과 모두 호환되는 값과 하위 값이 있는 Python 표준 데이터 구조 (예: `dict`)를 반환합니다.
-/// note | "참고"
+/// note | 참고
실제로 `jsonable_encoder`는 **FastAPI** 에서 내부적으로 데이터를 변환하는 데 사용하지만, 다른 많은 곳에서도 이는 유용합니다.
</div>
-/// note | "참고"
+/// note | 참고
`uvicorn main:app` 명령은 다음을 의미합니다:
`FastAPI`는 당신의 API를 위한 모든 기능을 제공하는 파이썬 클래스입니다.
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
`FastAPI`는 `Starlette`를 직접 상속하는 클래스입니다.
/items/foo
```
-/// info | "정보"
+/// info | 정보
"경로"는 일반적으로 "엔드포인트" 또는 "라우트"라고도 불립니다.
* 경로 `/`
* <abbr title="HTTP GET 메소드"><code>get</code> 작동</abbr> 사용
-/// info | "`@decorator` 정보"
+/// info | `@decorator` 정보
이 `@something` 문법은 파이썬에서 "데코레이터"라 부릅니다.
* `@app.patch()`
* `@app.trace()`
-/// tip | "팁"
+/// tip | 팁
각 작동(HTTP 메소드)을 원하는 대로 사용해도 됩니다.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "참고"
+/// note | 참고
차이점을 모르겠다면 [Async: *"바쁘신 경우"*](../async.md#_1){.internal-link target=_blank}을 확인하세요.
{!../../docs_src/header_params/tutorial001.py!}
```
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
`Header`는 `Path`, `Query` 및 `Cookie`의 "자매"클래스입니다. 이 역시 동일한 공통 `Param` 클래스를 상속합니다.
///
-/// info | "정보"
+/// info | 정보
헤더를 선언하기 위해서 `Header`를 사용해야 합니다. 그렇지 않으면 해당 매개변수를 쿼리 매개변수로 해석하기 때문입니다.
{!../../docs_src/header_params/tutorial002.py!}
```
-/// warning | "경고"
+/// warning | 경고
`convert_underscore`를 `False`로 설정하기 전에, 어떤 HTTP 프록시들과 서버들은 언더스코어가 포함된 헤더 사용을 허락하지 않는다는 것을 명심하십시오.
...이는 코드를 실행하는 서버로 사용할 수 있는 `uvicorn` 또한 포함하고 있습니다.
-/// note | "참고"
+/// note | 참고
부분적으로 설치할 수도 있습니다.
* **응답** 또는 다른 필요한 코드를 실행시키는 동작을 할 수 있습니다.
* **응답**를 반환합니다.
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
만약 `yield`를 사용한 의존성을 가지고 있다면, 미들웨어가 실행되고 난 후에 exit이 실행됩니다.
{!../../docs_src/middleware/tutorial001.py!}
```
-/// tip | "팁"
+/// tip | 팁
사용자 정의 헤더는 <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">'X-' 접두사를 사용</a>하여 추가할 수 있습니다.
///
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette.requests import request`를 사용할 수도 있습니다.
*경로 작동 데코레이터*를 설정하기 위해서 전달할수 있는 몇 가지 매개변수가 있습니다.
-/// warning | "경고"
+/// warning | 경고
아래 매개변수들은 *경로 작동 함수*가 아닌 *경로 작동 데코레이터*에 직접 전달된다는 사실을 기억하십시오.
각 상태 코드들은 응답에 사용되며, OpenAPI 스키마에 추가됩니다.
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
다음과 같이 임포트하셔도 좋습니다. `from starlette import status`.
{!../../docs_src/path_operation_configuration/tutorial005.py!}
```
-/// info | "정보"
+/// info | 정보
`response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 작동*을 지칭합니다.
///
-/// check | "확인"
+/// check | 확인
OpenAPI는 각 *경로 작동*이 응답에 관한 설명을 요구할 것을 명시합니다.
{!../../docs_src/path_params_numeric_validations/tutorial001.py!}
```
-/// note | "참고"
+/// note | 참고
경로 매개변수는 경로의 일부여야 하므로 언제나 필수적입니다.
* `lt`: 작거나(`l`ess `t`han)
* `le`: 작거나 같은(`l`ess than or `e`qual)
-/// info | "정보"
+/// info | 정보
`Query`, `Path`, 그리고 나중에게 보게될 것들은 (여러분이 사용할 필요가 없는) 공통 `Param` 클래스의 서브 클래스입니다.
///
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
`fastapi`에서 `Query`, `Path` 등을 임포트 할 때, 이것들은 실제로 함수입니다.
위의 예시에서, `item_id`는 `int`로 선언되었습니다.
-/// check | "확인"
+/// check | 확인
이 기능은 함수 내에서 오류 검사, 자동완성 등의 편집기 기능을 활용할 수 있게 해줍니다.
{"item_id":3}
```
-/// check | "확인"
+/// check | 확인
함수가 받은(반환도 하는) 값은 문자열 `"3"`이 아니라 파이썬 `int` 형인 `3`입니다.
`int`가 아닌 `float`을 전달하는 경우에도 동일한 오류가 나타납니다: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
-/// check | "확인"
+/// check | 확인
즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다.
<img src="/img/tutorial/path-params/image01.png">
-/// check | "확인"
+/// check | 확인
그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화형 API 문서(Swagger UI)를 제공합니다.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "정보"
+/// info | 정보
<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">열거형(또는 enums)</a>은 파이썬 버전 3.4 이후로 사용 가능합니다.
///
-/// tip | "팁"
+/// tip | 팁
혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 <abbr title="기술적으로 정확히는 딥 러닝 모델 구조">모델</abbr>들의 이름입니다.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "팁"
+/// tip | 팁
`ModelName.lenet.value`로도 값 `"lenet"`에 접근할 수 있습니다.
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "팁"
+/// tip | 팁
매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다.
쿼리 매개변수 `q`는 `Optional[str]` 자료형입니다. 즉, `str` 자료형이지만 `None` 역시 될 수 있음을 뜻하고, 실제로 기본값은 `None`이기 때문에 FastAPI는 이 매개변수가 필수가 아니라는 것을 압니다.
-/// note | "참고"
+/// note | 참고
FastAPI는 `q`의 기본값이 `= None`이기 때문에 필수가 아님을 압니다.
하지만 명시적으로 쿼리 매개변수를 선언합니다.
-/// info | "정보"
+/// info | 정보
FastAPI는 다음 부분에 관심이 있습니다:
{!../../docs_src/query_params_str_validations/tutorial005.py!}
```
-/// note | "참고"
+/// note | 참고
기본값을 갖는 것만으로 매개변수는 선택적이 됩니다.
{!../../docs_src/query_params_str_validations/tutorial006.py!}
```
-/// info | "정보"
+/// info | 정보
이전에 `...`를 본적이 없다면: 특별한 단일값으로, <a href="https://docs.python.org/3/library/constants.html#Ellipsis" class="external-link" target="_blank">파이썬의 일부이며 "Ellipsis"라 부릅니다</a>.
}
```
-/// tip | "팁"
+/// tip | 팁
위의 예와 같이 `list` 자료형으로 쿼리 매개변수를 선언하려면 `Query`를 명시적으로 사용해야 합니다. 그렇지 않으면 요청 본문으로 해석됩니다.
{!../../docs_src/query_params_str_validations/tutorial013.py!}
```
-/// note | "참고"
+/// note | 참고
이 경우 FastAPI는 리스트의 내용을 검사하지 않음을 명심하기 바랍니다.
해당 정보는 생성된 OpenAPI에 포함되고 문서 사용자 인터페이스 및 외부 도구에서 사용됩니다.
-/// note | "참고"
+/// note | 참고
도구에 따라 OpenAPI 지원 수준이 다를 수 있음을 명심하기 바랍니다.
이 경우 함수 매개변수 `q`는 선택적이며 기본값으로 `None` 값이 됩니다.
-/// check | "확인"
+/// check | 확인
**FastAPI**는 `item_id`가 경로 매개변수이고 `q`는 경로 매개변수가 아닌 쿼리 매개변수라는 것을 알 정도로 충분히 똑똑합니다.
///
-/// note | "참고"
+/// note | 참고
FastAPI는 `q`가 `= None`이므로 선택적이라는 것을 인지합니다.
* `skip`, 기본값이 `0`인 `int`.
* `limit`, 선택적인 `int`.
-/// tip | "팁"
+/// tip | 팁
[경로 매개변수](path-params.md#_8){.internal-link target=_blank}와 마찬가지로 `Enum`을 사용할 수 있습니다.
`File`을 사용하여 클라이언트가 업로드할 파일들을 정의할 수 있습니다.
-/// info | "정보"
+/// info | 정보
업로드된 파일을 전달받기 위해 먼저 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>를 설치해야합니다.
{!../../docs_src/request_files/tutorial001.py!}
```
-/// info | "정보"
+/// info | 정보
`File` 은 `Form` 으로부터 직접 상속된 클래스입니다.
///
-/// tip | "팁"
+/// tip | 팁
File의 본문을 선언할 때, 매개변수가 쿼리 매개변수 또는 본문(JSON) 매개변수로 해석되는 것을 방지하기 위해 `File` 을 사용해야합니다.
///
-/// note | "Starlette 기술적 세부사항"
+/// note | Starlette 기술적 세부사항
**FastAPI**의 `UploadFile` 은 **Starlette**의 `UploadFile` 을 직접적으로 상속받지만, **Pydantic** 및 FastAPI의 다른 부분들과의 호환성을 위해 필요한 부분들이 추가되었습니다.
**FastAPI**는 JSON 대신 올바른 위치에서 데이터를 읽을 수 있도록 합니다.
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
폼의 데이터는 파일이 포함되지 않은 경우 일반적으로 "미디어 유형" `application/x-www-form-urlencoded` 을 사용해 인코딩 됩니다.
///
-/// warning | "경고"
+/// warning | 경고
다수의 `File` 과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
선언한대로, `bytes` 의 `list` 또는 `UploadFile` 들을 전송받을 것입니다.
-/// note | "참고"
+/// note | 참고
2019년 4월 14일부터 Swagger UI가 하나의 폼 필드로 다수의 파일을 업로드하는 것을 지원하지 않습니다. 더 많은 정보를 원하면, <a href="https://github.com/swagger-api/swagger-ui/issues/4276" class="external-link" target="_blank">#4276</a>과 <a href="https://github.com/swagger-api/swagger-ui/issues/3641" class="external-link" target="_blank">#3641</a>을 참고하세요.
///
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette.responses import HTMLResponse` 역시 사용할 수 있습니다.
`File` 과 `Form` 을 사용하여 파일과 폼을 함께 정의할 수 있습니다.
-/// info | "정보"
+/// info | 정보
파일과 폼 데이터를 함께, 또는 각각 업로드하기 위해 먼저 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>를 설치해야합니다.
어떤 파일들은 `bytes`로, 또 어떤 파일들은 `UploadFile`로 선언할 수 있습니다.
-/// warning | "경고"
+/// warning | 경고
다수의 `File`과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json`가 아닌 `multipart/form-data`로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
{!../../docs_src/response_model/tutorial001.py!}
```
-/// note | "참고"
+/// note | 참고
`response_model`은 "데코레이터" 메소드(`get`, `post`, 등)의 매개변수입니다. 모든 매개변수들과 본문(body)처럼 *경로 작동 함수*가 아닙니다.
* 해당 모델의 출력 데이터 제한. 이것이 얼마나 중요한지 아래에서 볼 것입니다.
-/// note | "기술 세부사항"
+/// note | 기술 세부사항
응답 모델은 함수의 타입 어노테이션 대신 이 매개변수로 선언하는데, 경로 함수가 실제 응답 모델을 반환하지 않고 `dict`, 데이터베이스 객체나 기타 다른 모델을 `response_model`을 사용하여 필드 제한과 직렬화를 수행하고 반환할 수 있기 때문입니다
그러나 동일한 모델을 다른 *경로 작동*에서 사용할 경우, 모든 클라이언트에게 사용자의 비밀번호를 발신할 수 있습니다.
-/// danger | "위험"
+/// danger | 위험
절대로 사용자의 평문 비밀번호를 저장하거나 응답으로 발신하지 마십시오.
}
```
-/// info | "정보"
+/// info | 정보
FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 <a href="https://docs.pydantic.dev/latest/concepts/serialization/#modeldict" class="external-link" target="_blank"> `exclude_unset` 매개변수</a>를 사용합니다.
///
-/// info | "정보"
+/// info | 정보
아래 또한 사용할 수 있습니다:
따라서 JSON 스키마에 포함됩니다.
-/// tip | "팁"
+/// tip | 팁
`None` 뿐만 아니라 다른 어떤 것도 기본값이 될 수 있습니다.
Pydantic 모델이 하나만 있고 출력에서 일부 데이터를 제거하려는 경우 빠른 지름길로 사용할 수 있습니다.
-/// tip | "팁"
+/// tip | 팁
하지만 이러한 매개변수 대신 여러 클래스를 사용하여 위 아이디어를 사용하는 것을 추천합니다.
{!../../docs_src/response_model/tutorial005.py!}
```
-/// tip | "팁"
+/// tip | 팁
문법 `{"name", "description"}`은 두 값을 갖는 `set`을 만듭니다.
{!../../docs_src/response_status_code/tutorial001.py!}
```
-/// note | "참고"
+/// note | 참고
`status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다.
`status_code` 매개변수는 HTTP 상태 코드를 숫자로 입력받습니다.
-/// info | "정보"
+/// info | 정보
`status_code` 는 파이썬의 `http.HTTPStatus` 와 같은 `IntEnum` 을 입력받을 수도 있습니다.
<img src="https://fastapi.tiangolo.com/img/tutorial/response-status-code/image01.png">
-/// note | "참고"
+/// note | 참고
어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고).
## HTTP 상태 코드에 대하여
-/// note | "참고"
+/// note | 참고
만약 HTTP 상태 코드에 대하여 이미 알고있다면, 다음 항목으로 넘어가십시오.
* 일반적인 클라이언트 오류의 경우 `400` 을 사용할 수 있습니다.
* `5xx` 상태 코드는 서버 오류에 사용됩니다. 이것들을 직접 사용할 일은 거의 없습니다. 응용 프로그램 코드나 서버의 일부에서 문제가 발생하면 자동으로 이들 상태 코드 중 하나를 반환합니다.
-/// tip | "팁"
+/// tip | 팁
각각의 상태 코드와 이들이 의미하는 내용에 대해 더 알고싶다면 <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> HTTP 상태 코드에 관한 문서</a> 를 확인하십시오.
<img src="https://fastapi.tiangolo.com/img/tutorial/response-status-code/image02.png">
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette import status` 역시 사용할 수 있습니다.
////
-/// tip | "팁"
+/// tip | 팁
JSON 스키마를 확장하고 여러분의 별도의 자체 데이터를 추가하기 위해 같은 기술을 사용할 수 있습니다.
///
-/// info | "정보"
+/// info | 정보
(FastAPI 0.99.0부터 쓰이기 시작한) OpenAPI 3.1.0은 **JSON 스키마** 표준의 일부인 `examples`에 대한 지원을 추가했습니다.
## 기술적 세부 사항
-/// tip | "팁"
+/// tip | 팁
이미 **FastAPI**의 **0.99.0 혹은 그 이상** 버전을 사용하고 있다면, 이 세부 사항을 **스킵**해도 상관 없을 것입니다.
///
-/// warning | "경고"
+/// warning | 경고
표준 **JSON 스키마**와 **OpenAPI**에 대한 아주 기술적인 세부사항입니다.
* `File()`
* `Form()`
-/// info | "정보"
+/// info | 정보
이 예전 OpenAPI-특화 `examples` 매개변수는 이제 FastAPI `0.103.0`부터 `openapi_examples`입니다.
JSON 스키마의 새로운 `examples` 필드는 예제 속 **단순한 `list`**이며, (위에서 상술한 것처럼) OpenAPI의 다른 곳에 존재하는 dict으로 된 추가적인 메타데이터가 아닙니다.
-/// info | "정보"
+/// info | 정보
더 쉽고 새로운 JSON 스키마와의 통합과 함께 OpenAPI 3.1.0가 배포되었지만, 잠시동안 자동 문서 생성을 제공하는 도구인 Swagger UI는 OpenAPI 3.1.0을 지원하지 않았습니다 (5.0.0 버전부터 지원합니다 🎉).
이것은 모든 완료 및 타입 검사를 통해 함수 내부에서 우리를 도울 것입니다.
-/// tip | "팁"
+/// tip | 팁
요청 본문도 Pydantic 모델로 선언된다는 것을 기억할 것입니다.
///
-/// check | "확인"
+/// check | 확인
이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 다양한 의존성(다른 "의존적인")을 가질 수 있도록 합니다.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "기술적 세부사항"
+/// note | 기술적 세부사항
`from starlette.staticfiles import StaticFiles` 를 사용할 수도 있습니다.
Dołącz do 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">serwera czatu na Discordzie</a> 👥 i spędzaj czas z innymi w społeczności FastAPI.
-/// tip | "Wskazówka"
+/// tip | Wskazówka
Jeśli masz pytania, zadaj je w <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">Dyskusjach na GitHubie</a>, jest dużo większa szansa, że otrzymasz pomoc od [Ekspertów FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}.
`FastAPI` jest klasą, która zapewnia wszystkie funkcjonalności Twojego API.
-/// note | "Szczegóły techniczne"
+/// note | Szczegóły techniczne
`FastAPI` jest klasą, która dziedziczy bezpośrednio z `Starlette`.
* ścieżki `/`
* używając <abbr title="metoda HTTP GET">operacji <code>get</code></abbr>
-/// info | "`@decorator` Info"
+/// info | `@decorator` Info
Składnia `@something` jest w Pythonie nazywana "dekoratorem".
# Retornos Adicionais no OpenAPI
-/// warning | "Aviso"
+/// warning | Aviso
Este é um tema bem avançado.
{!../../docs_src/additional_responses/tutorial001.py!}
```
-/// note | "Nota"
+/// note | Nota
Lembre-se que você deve retornar o `JSONResponse` diretamente.
///
-/// info | "Informação"
+/// info | Informação
A chave `model` não é parte do OpenAPI.
{!../../docs_src/additional_responses/tutorial002.py!}
```
-/// note | "Nota"
+/// note | Nota
Note que você deve retornar a imagem utilizando um `FileResponse` diretamente.
///
-/// info | "Informação"
+/// info | Informação
A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`).
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Faça uso da versão `Annotated` quando possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Faça uso da versão `Annotated` quando possível.
////
-/// warning | "Aviso"
+/// warning | Aviso
Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente.
///
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode utilizar `from starlette.responses import JSONResponse`.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
////
-/// tip | "Dica"
+/// tip | Dica
Tudo isso parece não ser natural. E pode não estar muito claro ou aparentar ser útil ainda.
{!../../docs_src/async_tests/test_main.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Note que a função de teste é `async def` agora, no lugar de apenas `def` como quando estávamos utilizando o `TestClient` anteriormente.
...que nós utilizamos para fazer as nossas requisições utilizando o `TestClient`.
-/// tip | "Dica"
+/// tip | Dica
Note que nós estamos utilizando async/await com o novo `AsyncClient` - a requisição é assíncrona.
///
-/// warning | "Aviso"
+/// warning | Aviso
Se a sua aplicação depende dos eventos de vida útil (*lifespan*), o `AsyncClient` não acionará estes eventos. Para garantir que eles são acionados, utilize o `LifespanManager` do <a href="https://github.com/florimondmanca/asgi-lifespan#usage" class="external-link" target="_blank">florimondmanca/asgi-lifespan</a>.
Como a função de teste agora é assíncrona, você pode chamar (e `esperar`) outras funções `async` além de enviar requisições para a sua aplicação FastAPI em seus testes, exatamente como você as chamaria em qualquer outro lugar do seu código.
-/// tip | "Dica"
+/// tip | Dica
Se você se deparar com um `RuntimeError: Task attached to a different loop` ao integrar funções assíncronas em seus testes (e.g. ao utilizar o <a href="https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop" class="external-link" target="_blank">MotorClient do MongoDB</a>) Lembre-se de instanciar objetos que precisam de um loop de eventos (*event loop*) apenas em funções assíncronas, e.g. um *"callback"* `'@app.on_event("startup")`.
proxy --> server
```
-/// tip | "Dica"
+/// tip | Dica
O IP `0.0.0.0` é comumente usado para significar que o programa escuta em todos os IPs disponíveis naquela máquina/servidor.
Se você usar Hypercorn, ele também tem a opção `--root-path`.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
A especificação ASGI define um `root_path` para esse caso de uso.
Isso diz ao Traefik para escutar na porta 9999 e usar outro arquivo `routes.toml`.
-/// tip | "Dica"
+/// tip | Dica
Estamos usando a porta 9999 em vez da porta padrão HTTP 80 para que você não precise executá-lo com privilégios de administrador (`sudo`).
}
```
-/// tip | "Dica"
+/// tip | Dica
Perceba que, mesmo acessando em `http://127.0.0.1:8000/app`, ele mostra o `root_path` de `/api/v1`, retirado da opção `--root-path`.
## Servidores adicionais
-/// warning | "Aviso"
+/// warning | Aviso
Este é um caso de uso mais avançado. Sinta-se à vontade para pular.
}
```
-/// tip | "Dica"
+/// tip | Dica
Perceba o servidor gerado automaticamente com um valor `url` de `/api/v1`, retirado do `root_path`.
<img src="/img/tutorial/behind-a-proxy/image03.png">
-/// tip | "Dica"
+/// tip | Dica
A interface de documentação interagirá com o servidor que você selecionar.
E então, logo após o `yield`, descarregaremos o modelo. Esse código será executado **após** a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou GPU.
-/// tip | "Dica"
+/// tip | Dica
O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação.
## Eventos alternativos (deprecados)
-/// warning | "Aviso"
+/// warning | Aviso
A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima.
Aqui, a função de manipulação de evento `shutdown` irá escrever uma linha de texto `"Application shutdown"` no arquivo `log.txt`.
-/// info | "Informação"
+/// info | Informação
Na função `open()`, o `mode="a"` significa "acrescentar", então, a linha irá ser adicionada depois de qualquer coisa que esteja naquele arquivo, sem sobrescrever o conteúdo anterior.
///
-/// tip | "Dica"
+/// tip | Dica
Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo.
Por baixo, na especificação técnica ASGI, essa é a parte do <a href="https://asgi.readthedocs.io/en/latest/specs/lifespan.html" class="external-link" target="_blank">Protocolo Lifespan</a>, e define eventos chamados `startup` e `shutdown`.
-/// info | "Informação"
+/// info | Informação
Você pode ler mais sobre o manipulador `lifespan` do Starlette na <a href="https://www.starlette.io/lifespan/" class="external-link" target="_blank">Documentação do Lifespan Starlette</a>.
Na próxima seção você verá outras opções, configurações, e recursos adicionais.
-/// tip | "Dica"
+/// tip | Dica
As próximas seções **não são necessáriamente "avançadas"**
Isto pode facilitar bastante para os seus usuários **implementarem as APIs deles** para receber as requisições dos seus **webhooks**, eles podem inclusive ser capazes de gerar parte do código da API deles.
-/// info | "Informação"
+/// info | Informação
Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do FastAPI a partir da versão `0.99.0`.
Os webhooks que você define aparecerão no esquema do **OpenAPI** e na **página de documentação** gerada automaticamente.
-/// info | "Informação"
+/// info | Informação
O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que você utilizaria ao estruturar a sua aplicação com diversos arquivos.
### Mais informações
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você também poderia usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`.
{!../../docs_src/response_headers/tutorial001.py!}
```
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
Existem algumas funcionalidades adicionais para lidar com segurança além das cobertas em [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}.
-/// tip | "Dica"
+/// tip | Dica
As próximas seções **não são necessariamente "avançadas"**.
Nesta seção, você verá como gerenciar a autenticação e autorização com os mesmos escopos do OAuth2 em sua aplicação **FastAPI**.
-/// warning | "Aviso"
+/// warning | Aviso
Isso é uma seção mais ou menos avançada. Se você está apenas começando, você pode pular.
Neste caso, ele requer o escopo `me` (poderia requerer mais de um escopo).
-/// note | "Nota"
+/// note | Nota
Você não necessariamente precisa adicionar diferentes escopos em diferentes lugares.
O mais seguro é o fluxo de código, mas ele é mais complexo para implementar, pois ele necessita mais passos. Como ele é mais complexo, muitos provedores terminam sugerindo o fluxo implícito.
-/// note | "Nota"
+/// note | Nota
É comum que cada provedor de autenticação nomeie os seus fluxos de forma diferente, para torná-lo parte de sua marca.
///
-/// tip | "Dica"
+/// tip | Dica
Ao declarar `response_class=HTMLResponse`, a documentação entenderá que a resposta será HTML.
///
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você também poderia usar `from starlette.templating import Jinja2Templates`.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
////
-/// tip | "Dica"
+/// tip | Dica
Você pode definir uma sobreposição de dependência para uma dependência que é utilizada em qualquer lugar da sua aplicação **FastAPI**.
app.dependency_overrides = {}
```
-/// tip | "Dica"
+/// tip | Dica
Se você quer sobrepor uma dependência apenas para alguns testes, você pode definir a sobreposição no início do testes (dentro da função de teste) e reiniciá-la ao final (no final da função de teste).
{!../../docs_src/app_testing/tutorial002.py!}
```
-/// note | "Nota"
+/// note | Nota
Para mais detalhes, confira a documentação do Starlette para <a href="https://www.starlette.io/testclient/#testing-websocket-sessions" class="external-link" target="_blank">testar WebSockets</a>.
Ao declarar o parâmetro com o tipo sendo um `Request` em sua *função de operação de rota*, o **FastAPI** saberá como passar o `Request` neste parâmetro.
-/// tip | "Dica"
+/// tip | Dica
Note que neste caso, nós estamos declarando o parâmetro da rota ao lado do parâmetro da requisição.
Você pode ler mais sobre os detalhes do objeto <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request` no site da documentação oficial do Starlette.</a>.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você também pode utilizar `from starlette.requests import Request`.
Ele foi um dos primeiros exemplos de **documentação automática de API**, e essa foi especificamente uma das primeiras idéias que inspirou "a busca por" **FastAPI**.
-/// note | "Nota"
+/// note | Nota
Django REST Framework foi criado por Tom Christie. O mesmo criador de Starlette e Uvicorn, nos quais **FastAPI** é baseado.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Ter uma documentação automática da API em interface web.
Dada a simplicidade do Flask, parecia uma ótima opção para construção de APIs. A próxima coisa a procurar era um "Django REST Framework" para Flask.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Ser um microframework. Fazer ele fácil para misturar e combinar com ferramentas e partes necessárias.
Veja as similaridades em `requests.get(...)` e `@app.get(...)`.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
* Ter uma API simples e intuitiva.
* Utilizar nomes de métodos HTTP (operações) diretamente, de um jeito direto e intuitivo.
Isso acontece porquê quando alguém fala sobre a versão 2.0 é comum dizer "Swagger", e para a versão 3+, "OpenAPI".
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Adotar e usar um padrão aberto para especificações API, ao invés de algum esquema customizado.
Mas ele foi criado antes da existência do _type hints_ do Python. Então, para definir todo o <abbr title="definição de como os dados devem ser formados">_schema_</abbr> você precisa utilizar específicas ferramentas e classes fornecidas pelo Marshmallow.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Usar código para definir "schemas" que forneçam, automaticamente, tipos de dados e validação.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Ter validação automática de dados vindos de requisições.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Dar suporte a padrões abertos para APIs, OpenAPI.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Gerar _schema_ OpenAPI automaticamente, a partir do mesmo código que define serialização e validação.
Ele também não controla modelos aninhados muito bem. Então, se o corpo JSON na requisição for um objeto JSON que contém campos internos que contém objetos JSON aninhados, ele não consegue ser validado e documentado apropriadamente.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Usar tipos Python para ter um ótimo suporte do editor.
Ele foi um dos primeiros frameworks Python extremamente rápido baseado em `asyncio`. Ele foi feito para ser muito similar ao Flask.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Ele utiliza <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> ao invés do '_loop_' `asyncio` padrão do Python. É isso que deixa ele tão rápido.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Achar um jeito de ter uma performance insana.
Então, validação de dados, serialização e documentação tem que ser feitos no código, não automaticamente. Ou eles terão que ser implementados como um framework acima do Falcon, como o Hug. Essa mesma distinção acontece em outros frameworks que são inspirados pelo design do Falcon, tendo um objeto de requisição e um objeto de resposta como parâmetros.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Achar jeitos de conseguir melhor performance.
Rotas são declaradas em um único lugar, usando funções declaradas em outros lugares (ao invés de usar decoradores que possam ser colocados diretamente acima da função que controla o _endpoint_). Isso é mais perto de como o Django faz isso do que como Flask (e Starlette) faz. Ele separa no código coisas que são relativamente amarradas.
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Definir validações extras para tipos de dados usando valores "padrão" de atributos dos modelos. Isso melhora o suporte do editor, e não estava disponível no Pydantic antes.
///
-/// check | "Idéias inspiradas para o **FastAPI**"
+/// check | Idéias inspiradas para o **FastAPI**
Hug inspirou partes do APIStar, e foi uma das ferramentas que eu achei mais promissora, ao lado do APIStar.
///
-/// check | "**FastAPI** inspirado para"
+/// check | **FastAPI** inspirado para
Existir.
Ele é comparável ao Marshmallow. Embora ele seja mais rápido que Marshmallow em testes de performance. E ele é baseado nos mesmos Python _type hints_, o suporte ao editor é ótimo.
-/// check | "**FastAPI** usa isso para"
+/// check | **FastAPI** usa isso para
Controlar toda a validação de dados, serialização de dados e modelo de documentação automática (baseado no JSON Schema).
Essa é uma das principais coisas que **FastAPI** adiciona no topo, tudo baseado em Python _type hints_ (usando Pydantic). Isso, mais o sistema de injeção de dependência, utilidades de segurança, geração de _schema_ OpenAPI, etc.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
ASGI é um novo "padrão" sendo desenvolvido pelos membros do time central do Django. Ele ainda não está como "Padrão Python" (PEP), embora eles estejam em processo de fazer isso.
///
-/// check | "**FastAPI** usa isso para"
+/// check | **FastAPI** usa isso para
Controlar todas as partes web centrais. Adiciona recursos no topo.
Ele é o servidor recomendado para Starlette e **FastAPI**.
-/// check | "**FastAPI** recomenda isso para"
+/// check | **FastAPI** recomenda isso para
O principal servidor web para rodar aplicações **FastAPI**.
Mas nos casos com erros realmente graves que travam o **processo** em execução, você vai querer um componente externo que seja responsável por **reiniciar** o processo, pelo menos algumas vezes...
-/// tip | "Dica"
+/// tip | Dica
...Embora se o aplicativo inteiro estiver **travando imediatamente**, provavelmente não faça sentido reiniciá-lo para sempre. Mas nesses casos, você provavelmente notará isso durante o desenvolvimento, ou pelo menos logo após a implantação.
* **Serviços de nuvem** que cuidam disso para você
* O serviço de nuvem provavelmente **cuidará da replicação para você**. Ele possivelmente deixaria você definir **um processo para executar**, ou uma **imagem de contêiner** para usar, em qualquer caso, provavelmente seria **um único processo Uvicorn**, e o serviço de nuvem seria responsável por replicá-lo.
-/// tip | "Dica"
+/// tip | Dica
Não se preocupe se alguns desses itens sobre **contêineres**, Docker ou Kubernetes ainda não fizerem muito sentido.
Claro, há alguns casos em que não há problema em executar as etapas anteriores várias vezes; nesse caso, é muito mais fácil de lidar.
-/// tip | "Dica"
+/// tip | Dica
Além disso, tenha em mente que, dependendo da sua configuração, em alguns casos você **pode nem precisar de nenhuma etapa anterior** antes de iniciar sua aplicação.
* Um script bash que roda os passos anteriores e então inicia seu aplicativo
* Você ainda precisaria de uma maneira de iniciar/reiniciar *aquele* script bash, detectar erros, etc.
-/// tip | "Dica"
+/// tip | Dica
Darei exemplos mais concretos de como fazer isso com contêineres em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}.
Usando contêineres Linux você tem diversas vantagens incluindo **segurança**, **replicabilidade**, **simplicidade**, entre outras.
-/// tip | "Dica"
+/// tip | Dica
Está com pressa e já sabe dessas coisas? Pode ir direto para [`Dockerfile` abaixo 👇](#construindo-uma-imagem-docker-para-fastapi).
Mas é bem mais complexo do que isso.
-/// tip | "Dica"
+/// tip | Dica
Se você está com pressa ou não se importa, continue com as seções seguintes para instruções passo a passo para configurar tudo com diferentes técnicas.
Um processo semelhante se aplicaria a qualquer outro programa de servidor ASGI.
-/// tip | "Dica"
+/// tip | Dica
Adicionando o `standard`, o Uvicorn instalará e usará algumas dependências extras recomendadas.
</div>
-/// note | "Nota"
+/// note | Nota
O comando `uvicorn main:app` refere-se a:
Cada programa de servidor ASGI alternativo teria um comando semelhante, você pode ler mais na documentação respectiva.
-/// warning | "Aviso"
+/// warning | Aviso
Uvicorn e outros servidores suportam a opção `--reload` que é útil durante o desenvolvimento.
Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o comando `fastapi` ou o comando `uvicorn` diretamente.
-/// info | "Informação"
+/// info | Informação
Se você estiver usando contêineres, por exemplo com Docker ou Kubernetes, falarei mais sobre isso no próximo capítulo: [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}.
FastAPI também segue a convenção de que qualquer alteração de versão "PATCH" é para correção de bugs e alterações não significativas.
-/// tip | "Dica"
+/// tip | Dica
O "PATCH" é o último número, por exemplo, em `0.2.3`, a versão PATCH é `3`.
Mudanças significativas e novos recursos são adicionados em versões "MINOR".
-/// tip | "Dica"
+/// tip | Dica
O "MINOR" é o número que está no meio, por exemplo, em `0.2.3`, a versão MINOR é `2`.
# Variáveis de Ambiente
-/// tip | "Dica"
+/// tip | Dica
Se você já sabe o que são "variáveis de ambiente" e como usá-las, pode pular esta seção.
print(f"Hello {name} from Python")
```
-/// tip | "Dica"
+/// tip | Dica
O segundo argumento para <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> é o valor padrão a ser retornado.
</div>
-/// tip | "Dica"
+/// tip | Dica
Você pode ler mais sobre isso em <a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a>.
Entre no 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">server de conversa do Discord</a> 👥 e conheça novas pessoas da comunidade
do FastAPI.
-/// tip | "Dica"
+/// tip | Dica
Para perguntas, pergunte nas <a href="https://github.com/fastapi/fastapi/issues/new/choose" class="external-link" target="_blank">questões do GitHub</a>, lá tem um chance maior de você ser ajudado sobre o FastAPI [FastAPI Experts](fastapi-people.md#especialistas){.internal-link target=_blank}.
Você pode combinar *operações de rota* normais do FastAPI com GraphQL na mesma aplicação.
-/// tip | "Dica"
+/// tip | Dica
**GraphQL** resolve alguns casos de uso muito específicos.
Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, você pode facilmente **migrar** para <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>, que cobre o mesmo caso de uso e tem uma **interface quase idêntica**.
-/// tip | "Dica"
+/// tip | Dica
Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a>, pois ele é baseado em type annotations em vez de classes e tipos personalizados.
**FastAPI** oferece uma ferramenta conveniente para estruturar sua aplicação, mantendo toda a flexibilidade.
-/// info | "Informação"
+/// info | Informação
Se você vem do Flask, isso seria o equivalente aos Blueprints do Flask.
│ └── admin.py
```
-/// tip | "Dica"
+/// tip | Dica
Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório.
Todos os mesmos `parameters`, `responses`, `dependencies`, `tags`, etc.
-/// tip | "Dica"
+/// tip | Dica
Neste exemplo, a variável é chamada de `router`, mas você pode nomeá-la como quiser.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira usar a versão `Annotated` se possível.
////
-/// tip | "Dica"
+/// tip | Dica
Estamos usando um cabeçalho inventado para simplificar este exemplo.
E podemos adicionar uma lista de `dependencies` que serão adicionadas a todas as *operações de rota* no roteador e serão executadas/resolvidas para cada solicitação feita a elas.
-/// tip | "Dica"
+/// tip | Dica
Observe que, assim como [dependências em *decoradores de operação de rota*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, nenhum valor será passado para sua *função de operação de rota*.
* As dependências do roteador são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} e, em seguida, as dependências de parâmetros normais.
* Você também pode adicionar [dependências de `Segurança` com `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
-/// tip | "Dica"
+/// tip | Dica
Ter `dependências` no `APIRouter` pode ser usado, por exemplo, para exigir autenticação para um grupo inteiro de *operações de rota*. Mesmo que as dependências não sejam adicionadas individualmente a cada uma delas.
#### Como funcionam as importações relativas
-/// tip | "Dica"
+/// tip | Dica
Se você sabe perfeitamente como funcionam as importações, continue para a próxima seção abaixo.
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Esta última operação de caminho terá a combinação de tags: `["items", "custom"]`.
from app.routers import items, users
```
-/// info | "Informação"
+/// info | Informação
A primeira versão é uma "importação relativa":
{!../../docs_src/bigger_applications/app/main.py!}
```
-/// info | "Informação"
+/// info | Informação
`users.router` contém o `APIRouter` dentro do arquivo `app/routers/users.py`.
Ele incluirá todas as rotas daquele roteador como parte dele.
-/// note | "Detalhe Técnico"
+/// note | Detalhe Técnico
Na verdade, ele criará internamente uma *operação de rota* para cada *operação de rota* que foi declarada no `APIRouter`.
e funcionará corretamente, junto com todas as outras *operações de rota* adicionadas com `app.include_router()`.
-/// info | "Detalhes Técnicos"
+/// info | Detalhes Técnicos
**Observação**: este é um detalhe muito técnico que você provavelmente pode **simplesmente pular**.
{!../../docs_src/body_fields/tutorial001.py!}
```
-/// warning | "Aviso"
+/// warning | Aviso
Note que `Field` é importado diretamente do `pydantic`, não do `fastapi` como todo o resto (`Query`, `Path`, `Body`, etc).
`Field` funciona da mesma forma que `Query`, `Path` e `Body`, ele possui todos os mesmos parâmetros, etc.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Na realidade, `Query`, `Path` e outros que você verá em seguida, criam objetos de subclasses de uma classe `Param` comum, que é ela mesma uma subclasse da classe `FieldInfo` do Pydantic.
///
-/// tip | "Dica"
+/// tip | Dica
Note como cada atributo do modelo com um tipo, valor padrão e `Field` possuem a mesma estrutura que parâmetros de *funções de operações de rota*, com `Field` ao invés de `Path`, `Query` e `Body`.
////
-/// note | "Nota"
+/// note | Nota
Repare que, neste caso, o `item` que seria capturado a partir do corpo é opcional. Visto que ele possui `None` como valor padrão.
}
```
-/// note | "Nota"
+/// note | Nota
Repare que mesmo que o `item` esteja declarado da mesma maneira que antes, agora é esperado que ele esteja dentro do corpo com uma chave `item`.
////
-/// info | "Informação"
+/// info | Informação
`Body` também possui todas as validações adicionais e metadados de parâmetros como em `Query`,`Path` e outras que você verá depois.
}
```
-/// info | "informação"
+/// info | informação
Note como o campo `images` agora tem uma lista de objetos de image.
{!../../docs_src/body_nested_models/tutorial007.py!}
```
-/// info | "informação"
+/// info | informação
Note como `Offer` tem uma lista de `Item`s, que por sua vez possui opcionalmente uma lista `Image`s
{!../../docs_src/body_nested_models/tutorial009.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Leve em condideração que o JSON só suporta `str` como chaves.
Para declarar um corpo da **requisição**, você utiliza os modelos do <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> com todos os seus poderes e benefícios.
-/// info | "Informação"
+/// info | Informação
Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`.
<img src="/img/tutorial/body/image05.png">
-/// tip | "Dica"
+/// tip | Dica
Se você utiliza o <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> como editor, você pode utilizar o <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Plugin do Pydantic para o PyCharm </a>.
* Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**.
* Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição.
-/// note | "Observação"
+/// note | Observação
O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
Para mais informações <abbr title="Cross-Origin Resource Sharing">CORS</abbr>, acesse <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS documentation</a>.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette.middleware.cors import CORSMiddleware`.
não será executada.
-/// info | "Informação"
+/// info | Informação
Para mais informações, consulte <a href="https://docs.python.org/3/library/__main__.html" class="external-link" target="_blank">a documentação oficial do Python</a>.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
...e o **FastAPI** saberá o que fazer.
-/// tip | "Dica"
+/// tip | Dica
Se isso parece mais confuso do que útil, não utilize, você não *precisa* disso.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível
Essas dependências serão executadas/resolvidas da mesma forma que dependências comuns. Mas o valor delas (se existir algum) não será passado para a sua *função de operação de rota*.
-/// tip | "Dica"
+/// tip | Dica
Alguns editores de texto checam parâmetros de funções não utilizados, e os mostram como erros.
///
-/// info | "Informação"
+/// info | Informação
Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Keys` e `X-Token`.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Para fazer isso, utilize `yield` em vez de `return`, e escreva os passos extras (código) depois.
-/// tip | "Dica"
+/// tip | Dica
Garanta que `yield` é utilizado apenas uma vez.
///
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Qualquer função que possa ser utilizada com:
{!../../docs_src/dependencies/tutorial007.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Você pode usar funções assíncronas (`async`) ou funções comuns.
//// tab | python 3.8+ non-annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | python 3.8+ non-annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
O **FastAPI** se encarrega de executá-las na ordem certa.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Tudo isso funciona graças aos <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">gerenciadores de contexto</a> do Python.
Da mesma forma, você pode lançar uma `httpexception` ou algo parecido no código de saída, após o `yield`
-/// tip | "Dica"
+/// tip | Dica
Essa é uma técnica relativamente avançada, e na maioria dos casos você não precisa dela totalmente, já que você pode lançar exceções (incluindo `httpexception`) dentro do resto do código da sua aplicação, por exemplo, em uma *função de operação de rota*.
//// tab | python 3.8+ non-annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-annotated
-/// tip | "dica"
+/// tip | dica
utilize a versão com `Annotated` se possível.
//// tab | python 3.8+ non-annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
end
```
-/// info | "Informação"
+/// info | Informação
Apenas **uma resposta** será enviada para o cliente. Ela pode ser uma das respostas de erro, ou então a resposta da *operação de rota*.
///
-/// tip | "Dica"
+/// tip | Dica
Esse diagrama mostra `HttpException`, mas você pode levantar qualquer outra exceção que você capture em uma dependência com `yield` ou um [Manipulador de exceções personalizado](../handling-errors.md#instalando-manipuladores-de-excecoes-customizados){.internal-link target=_blank}.
## Dependências com `yield`, `HTTPException`, `except` e Tarefas de Background
-/// warning | "Aviso"
+/// warning | Aviso
Você provavelmente não precisa desses detalhes técnicos, você pode pular essa seção e continuar na próxima seção abaixo.
Ainda assim, como isso exigiria esperar que a resposta navegasse pela rede enquanto mantia ativo um recurso desnecessário na dependência com yield (por exemplo, uma conexão com banco de dados), isso mudou na versão 0.106.0 do FastAPI.
-/// tip | "Dica"
+/// tip | Dica
Adicionalmente, uma tarefa de background é, normalmente, um conjunto de lógicas independentes que devem ser manipuladas separadamente, com seus próprios recursos (e.g. sua própria conexão com banco de dados).
### Utilizando gerenciadores de contexto em dependências com `yield`
-/// warning | "Aviso"
+/// warning | Aviso
Isso é uma ideia mais ou menos "avançada".
{!../../docs_src/dependencies/tutorial010.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Outra forma de criar um gerenciador de contexto é utilizando:
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
E então retorna um `dict` contendo esses valores.
-/// info | "Informação"
+/// info | Informação
FastAPI passou a suportar a notação `Annotated` (e começou a recomendá-la) na versão 0.95.0.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
E essa função vai receber os parâmetros da mesma forma que uma *função de operação de rota*.
-/// tip | "Dica"
+/// tip | Dica
Você verá quais outras "coisas", além de funções, podem ser usadas como dependências no próximo capítulo.
Assim, você escreve um código compartilhado apenas uma vez e o **FastAPI** se encarrega de chamá-lo em suas *operações de rota*.
-/// check | "Checando"
+/// check | Checando
Perceba que você não precisa criar uma classe especial e enviar a dependência para algum outro lugar em que o **FastAPI** a "registre" ou realize qualquer operação similar.
////
-/// tip | "Dica"
+/// tip | Dica
Isso é apenas Python padrão, essa funcionalidade é chamada de "type alias", e na verdade não é específica ao **FastAPI**.
Não faz diferença. O **FastAPI** sabe o que fazer.
-/// note | "Nota"
+/// note | Nota
Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#com-pressa){.internal-link target=_blank} a sessão acerca de `async` e `await` na documentação.
//// tab | Python 3.10 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.10 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
//// tab | Python 3.8 non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
////
-/// info | "Informação"
+/// info | Informação
Perceba que nós estamos declarando apenas uma dependência na *função de operação de rota*, em `query_or_cookie_extractor`.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Utilize a versão com `Annotated` se possível.
Mas ainda assim, é bastante poderoso, e permite que você declare grafos (árvores) de dependências com uma profundidade arbitrária.
-/// tip | "Dica"
+/// tip | Dica
Tudo isso pode não parecer muito útil com esses exemplos.
A função não retorna um grande `str` contendo os dados no formato JSON (como uma string). Mas sim, retorna uma estrutura de dados padrão do Python (por exemplo, um `dict`) com valores e subvalores compatíveis com JSON.
-/// note | "Nota"
+/// note | Nota
`jsonable_encoder` é realmente usado pelo **FastAPI** internamente para converter dados. Mas também é útil em muitos outros cenários.
</div>
-/// note | "Nota"
+/// note | Nota
O comando `uvicorn main:app` se refere a:
`FastAPI` é uma classe Python que fornece todas as funcionalidades para sua API.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
`FastAPI` é uma classe que herda diretamente de `Starlette`.
/items/foo
```
-/// info | "Informação"
+/// info | Informação
Uma "rota" também é comumente chamada de "endpoint".
* a rota `/`
* usando o <abbr title="o método HTTP GET">operador <code>get</code></abbr>
-/// info | "`@decorador`"
+/// info | `@decorador`
Essa sintaxe `@alguma_coisa` em Python é chamada de "decorador".
* `@app.patch()`
* `@app.trace()`
-/// tip | "Dica"
+/// tip | Dica
Você está livre para usar cada operação (método HTTP) como desejar.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "Nota"
+/// note | Nota
Se você não sabe a diferença, verifique o [Async: *"Com pressa?"*](../async.md#com-pressa){.internal-link target=_blank}.
}
```
-/// tip | "Dica"
+/// tip | Dica
Quando você lançar um `HTTPException`, você pode passar qualquer valor convertível em JSON como parâmetro de `detail`, e não apenas `str`.
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você também pode usar `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
### `RequestValidationError` vs `ValidationError`
-/// warning | "Aviso"
+/// warning | Aviso
Você pode pular estes detalhes técnicos caso eles não sejam importantes para você neste momento.
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você pode usar `from starlette.responses import PlainTextResponse`.
////
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
`Header` é uma classe "irmã" de `Path`, `Query` e `Cookie`. Ela também herda da mesma classe em comum `Param`.
////
-/// warning | "Aviso"
+/// warning | Aviso
Antes de definir `convert_underscores` como `False`, lembre-se de que alguns proxies e servidores HTTP não permitem o uso de cabeçalhos com sublinhados.
...isso também inclui o `uvicorn`, que você pode usar como o servidor que rodará seu código.
-/// note | "Nota"
+/// note | Nota
Você também pode instalar parte por parte.
* Ele pode fazer algo com essa **resposta** ou executar qualquer código necessário.
* Então ele retorna a **resposta**.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Se você tiver dependências com `yield`, o código de saída será executado *depois* do middleware.
{!../../docs_src/middleware/tutorial001.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Tenha em mente que cabeçalhos proprietários personalizados podem ser adicionados <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">usando o prefixo 'X-'</a>.
///
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette.requests import Request`.
Existem vários parâmetros que você pode passar para o seu *decorador de operação de rota* para configurá-lo.
-/// warning | "Aviso"
+/// warning | Aviso
Observe que esses parâmetros são passados diretamente para o *decorador de operação de rota*, não para a sua *função de operação de rota*.
Esse código de status será usado na resposta e será adicionado ao esquema OpenAPI.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você também poderia usar `from starlette import status`.
////
-/// info | "Informação"
+/// info | Informação
Note que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral.
////
-/// note | "Nota"
+/// note | Nota
Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota.
* `lt`: menor que (`l`ess `t`han)
* `le`: menor que ou igual (`l`ess than or `e`qual)
-/// info | "Informação"
+/// info | Informação
`Query`, `Path` e outras classes que você verá a frente são subclasses de uma classe comum `Param`.
///
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Quando você importa `Query`, `Path` e outras de `fastapi`, elas são na verdade funções.
Nesse caso, `item_id` está sendo declarado como um `int`.
-/// check | "Verifique"
+/// check | Verifique
{"item_id":3}
```
-/// check | "Verifique"
+/// check | Verifique
O mesmo erro apareceria se você tivesse fornecido um `float` ao invés de um `int`, como em: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
-/// check | "Verifique"
+/// check | Verifique
<img src="/img/tutorial/path-params/image01.png">
-/// check | "Verifique"
+/// check | Verifique
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "informação"
+/// info | informação
<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">Enumerations (ou enums) estão disponíveis no Python</a> desde a versão 3.4.
///
-/// tip | "Dica"
+/// tip | Dica
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "Dica"
+/// tip | Dica
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "Dica"
+/// tip | Dica
O parâmetro de consulta `q` é do tipo `Union[str, None]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório.
-/// note | "Observação"
+/// note | Observação
O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
Mas o declara explicitamente como um parâmetro de consulta.
-/// info | "Informação"
+/// info | Informação
Tenha em mente que o FastAPI se preocupa com a parte:
{!../../docs_src/query_params_str_validations/tutorial005.py!}
```
-/// note | "Observação"
+/// note | Observação
O parâmetro torna-se opcional quando possui um valor padrão.
{!../../docs_src/query_params_str_validations/tutorial006.py!}
```
-/// info | "Informação"
+/// info | Informação
Se você nunca viu os `...` antes: é um valor único especial, faz <a href="https://docs.python.org/3/library/constants.html#Ellipsis" class="external-link" target="_blank">parte do Python e é chamado "Ellipsis"</a>.
}
```
-/// tip | "Dica"
+/// tip | Dica
Para declarar um parâmetro de consulta com o tipo `list`, como no exemplo acima, você precisa usar explicitamente o `Query`, caso contrário será interpretado como um corpo da requisição.
{!../../docs_src/query_params_str_validations/tutorial013.py!}
```
-/// note | "Observação"
+/// note | Observação
Tenha em mente que neste caso, o FastAPI não irá validar os conteúdos da lista.
Essa informações serão inclusas no esquema do OpenAPI e utilizado pela documentação interativa e ferramentas externas.
-/// note | "Observação"
+/// note | Observação
Tenha em mente que cada ferramenta oferece diferentes níveis de suporte ao OpenAPI.
Nesse caso, o parâmetro da função `q` será opcional, e `None` será o padrão.
-/// check | "Verificar"
+/// check | Verificar
Você também pode notar que o **FastAPI** é esperto o suficiente para perceber que o parâmetro da rota `item_id` é um parâmetro da rota, e `q` não é, portanto, `q` é o parâmetro de consulta.
* `skip`, um `int` com o valor padrão `0`.
* `limit`, um `int` opcional.
-/// tip | "Dica"
+/// tip | Dica
Você também poderia usar `Enum` da mesma forma que com [Path Parameters](path-params.md#valores-predefinidos){.internal-link target=_blank}.
///
-/// note | "Detalhes Técnicos do Starlette"
+/// note | Detalhes Técnicos do Starlette
O `UploadFile` do ***FastAPI** herda diretamente do `UploadFile` do **Starlette** , mas adiciona algumas partes necessárias para torná-lo compatível com o **Pydantic** e as outras partes do FastAPI.
**FastAPI** se certificará de ler esses dados do lugar certo, ao invés de JSON.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Dados de formulários normalmente são codificados usando o "media type" (tipo de mídia) `application/x-www-form-urlencoded` quando não incluem arquivos.
Você receberá, tal como declarado, uma `list` de `bytes` ou `UploadFile`.
-/// note | "Detalhes Técnicos"
+/// note | Detalhes Técnicos
Você pode também pode usar `from starlette.responses import HTMLResponse`.
Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários** no FastAPI.
-/// info | "Informação"
+/// info | Informação
Para utilizar formulários, instale primeiramente o <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
///
-/// note | "Nota"
+/// note | Nota
Isto é suportado desde a versão `0.113.0` do FastAPI. 🤓
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira utilizar a versão `Annotated` se possível.
Em alguns casos de uso especiais (provavelmente não muito comum), você pode desejar **restringir** os campos do formulário para aceitar apenas os declarados no modelo Pydantic. E **proibir** qualquer campo **extra**.
-/// note | "Nota"
+/// note | Nota
Isso é suportado deste a versão `0.114.0` do FastAPI. 🤓
Você pode definir arquivos e campos de formulário ao mesmo tempo usando `File` e `Form`.
-/// info | "Informação"
+/// info | Informação
Para receber arquivos carregados e/ou dados de formulário, primeiro instale <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
E você pode declarar alguns dos arquivos como `bytes` e alguns como `UploadFile`.
-/// warning | "Aviso"
+/// warning | Aviso
Você pode declarar vários parâmetros `File` e `Form` em uma *operação de caminho*, mas não é possível declarar campos `Body` para receber como JSON, pois a requisição terá o corpo codificado usando `multipart/form-data` ao invés de `application/json`.
Quando você precisar receber campos de formulário ao invés de JSON, você pode usar `Form`.
-/// info | "Informação"
+/// info | Informação
Para usar formulários, primeiro instale <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
Com `Form` você pode declarar os mesmos metadados e validação que com `Body` (e `Query`, `Path`, `Cookie`).
-/// info | "Informação"
+/// info | Informação
`Form` é uma classe que herda diretamente de `Body`.
///
-/// tip | "Dica"
+/// tip | Dica
Para declarar corpos de formulário, você precisa usar `Form` explicitamente, porque sem ele os parâmetros seriam interpretados como parâmetros de consulta ou parâmetros de corpo (JSON).
O **FastAPI** fará a leitura desses dados no lugar certo em vez de JSON.
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Os dados dos formulários são normalmente codificados usando o "tipo de mídia" `application/x-www-form-urlencoded`.
///
-/// warning | "Aviso"
+/// warning | Aviso
Você pode declarar vários parâmetros `Form` em uma *operação de caminho*, mas não pode declarar campos `Body` que espera receber como JSON, pois a solicitação terá o corpo codificado usando `application/x-www- form-urlencoded` em vez de `application/json`.
{!../../docs_src/response_status_code/tutorial001.py!}
```
-/// note | "Nota"
+/// note | Nota
Observe que `status_code` é um parâmetro do método "decorador" (get, post, etc). Não da sua função de *operação de caminho*, como todos os parâmetros e corpo.
O parâmetro `status_code` recebe um número com o código de status HTTP.
-/// info | "Informação"
+/// info | Informação
`status_code` também pode receber um `IntEnum`, como o do Python <a href="https://docs.python.org/3/library/http.html#http.HTTPStatus" class="external-link" target="_blank">`http.HTTPStatus`</a>.
<img src="/img/tutorial/response-status-code/image01.png">
-/// note | "Nota"
+/// note | Nota
Alguns códigos de resposta (consulte a próxima seção) indicam que a resposta não possui um corpo.
## Sobre os códigos de status HTTP
-/// note | "Nota"
+/// note | Nota
Se você já sabe o que são códigos de status HTTP, pule para a próxima seção.
* Para erros genéricos do cliente, você pode usar apenas `400`.
* `500` e acima são para erros do servidor. Você quase nunca os usa diretamente. Quando algo der errado em alguma parte do código do seu aplicativo ou servidor, ele retornará automaticamente um desses códigos de status.
-/// tip | "Dica"
+/// tip | Dica
Para saber mais sobre cada código de status e qual código serve para quê, verifique o <a href="https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> documentação sobre códigos de status HTTP</a>.
<img src="/img/tutorial/response-status-code/image02.png">
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette import status`.
Essas informações extras serão adicionadas como se encontram no **JSON Schema** de resposta desse modelo e serão usadas na documentação da API.
-/// tip | "Dica"
+/// tip | Dica
Você pode usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras de forma personalizada.
{!../../docs_src/schema_extra_example/tutorial002.py!}
```
-/// warning | "Atenção"
+/// warning | Atenção
Lembre-se de que esses argumentos extras passados não adicionarão nenhuma validação, apenas informações extras, para fins de documentação.
## Detalhes técnicos
-/// warning | "Atenção"
+/// warning | Atenção
Esses são detalhes muito técnicos sobre os padrões **JSON Schema** e **OpenAPI**.
## Execute-o
-/// info | "informação"
+/// info | informação
<img src="/img/tutorial/security/image01.png">
-/// check | "Botão de Autorizar!"
+/// check | Botão de Autorizar!
<img src="/img/tutorial/security/image02.png">
-/// note | "Nota"
+/// note | Nota
Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`.
-/// info | "informação"
+/// info | informação
{!../../docs_src/security/tutorial001.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Em breve também criaremos o atual path operation.
-/// info | "informação"
+/// info | informação
A **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema da OpenAPI (e na documentação da API automática).
-/// info | "Detalhes técnicos"
+/// info | Detalhes técnicos
OAuth2 não especifica como criptografar a comunicação, ele espera que você tenha sua aplicação em um servidor HTTPS.
-/// tip | "Dica"
+/// tip | Dica
Na seção sobre **deployment** você irá ver como configurar HTTPS de modo gratuito, usando Traefik e Let’s Encrypt.
* Essa descoberta automática é o que é definido na especificação OpenID Connect.
-/// tip | "Dica"
+/// tip | Dica
Integração com outros provedores de autenticação/autorização como Google, Facebook, Twitter, GitHub, etc. é bem possível e relativamente fácil.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette.staticfiles import StaticFiles`.
## Usando `TestClient`
-/// info | "Informação"
+/// info | Informação
Para usar o `TestClient`, primeiro instale o <a href="https://www.python-httpx.org" class="external-link" target="_blank">`httpx`</a>.
{!../../docs_src/app_testing/tutorial001.py!}
```
-/// tip | "Dica"
+/// tip | Dica
Observe que as funções de teste são `def` normais, não `async def`.
///
-/// note | "Detalhes técnicos"
+/// note | Detalhes técnicos
Você também pode usar `from starlette.testclient import TestClient`.
///
-/// tip | "Dica"
+/// tip | Dica
Se você quiser chamar funções `async` em seus testes além de enviar solicitações ao seu aplicativo FastAPI (por exemplo, funções de banco de dados assíncronas), dê uma olhada em [Testes assíncronos](../advanced/async-tests.md){.internal-link target=_blank} no tutorial avançado.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira usar a versão `Annotated` se possível.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Dica"
+/// tip | Dica
Prefira usar a versão `Annotated` se possível.
Para mais informações sobre como passar dados para o backend (usando `httpx` ou `TestClient`), consulte a <a href="https://www.python-httpx.org" class="external-link" target="_blank">documentação do HTTPX</a>.
-/// info | "Informação"
+/// info | Informação
Observe que o `TestClient` recebe dados que podem ser convertidos para JSON, não para modelos Pydantic.
Ao trabalhar em projetos Python, você provavelmente deve usar um **ambiente virtual** (ou um mecanismo similar) para isolar os pacotes que você instala para cada projeto.
-/// info | "Informação"
+/// info | Informação
Se você já sabe sobre ambientes virtuais, como criá-los e usá-los, talvez seja melhor pular esta seção. 🤓
///
-/// tip | "Dica"
+/// tip | Dica
Um **ambiente virtual** é diferente de uma **variável de ambiente**.
///
-/// info | "Informação"
+/// info | Informação
Esta página lhe ensinará como usar **ambientes virtuais** e como eles funcionam.
Ao começar a trabalhar em um projeto Python **pela primeira vez**, crie um ambiente virtual **<abbr title="existem outras opções, esta é uma diretriz simples">dentro do seu projeto</abbr>**.
-/// tip | "Dica"
+/// tip | Dica
Você só precisa fazer isso **uma vez por projeto**, não toda vez que trabalhar.
</div>
-/// tip | "Dica"
+/// tip | Dica
Por padrão, `uv` criará um ambiente virtual em um diretório chamado `.venv`.
Ative o novo ambiente virtual para que qualquer comando Python que você executar ou pacote que você instalar o utilize.
-/// tip | "Dica"
+/// tip | Dica
Faça isso **toda vez** que iniciar uma **nova sessão de terminal** para trabalhar no projeto.
////
-/// tip | "Dica"
+/// tip | Dica
Toda vez que você instalar um **novo pacote** naquele ambiente, **ative** o ambiente novamente.
Verifique se o ambiente virtual está ativo (o comando anterior funcionou).
-/// tip | "Dica"
+/// tip | Dica
Isso é **opcional**, mas é uma boa maneira de **verificar** se tudo está funcionando conforme o esperado e se você está usando o ambiente virtual pretendido.
## Atualizar `pip`
-/// tip | "Dica"
+/// tip | Dica
Se você usar <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a>, você o usará para instalar coisas em vez do `pip`, então não precisará atualizar o `pip`. 😎
Muitos erros exóticos durante a instalação de um pacote são resolvidos apenas atualizando o `pip` primeiro.
-/// tip | "Dica"
+/// tip | Dica
Normalmente, você faria isso **uma vez**, logo após criar o ambiente virtual.
Se você estiver usando **Git** (você deveria), adicione um arquivo `.gitignore` para excluir tudo em seu `.venv` do Git.
-/// tip | "Dica"
+/// tip | Dica
Se você usou <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a> para criar o ambiente virtual, ele já fez isso para você, você pode pular esta etapa. 😎
///
-/// tip | "Dica"
+/// tip | Dica
Faça isso **uma vez**, logo após criar o ambiente virtual.
Após ativar o ambiente, você pode instalar pacotes nele.
-/// tip | "Dica"
+/// tip | Dica
Faça isso **uma vez** ao instalar ou atualizar os pacotes que seu projeto precisa.
Se estiver com pressa e não quiser usar um arquivo para declarar os requisitos de pacote do seu projeto, você pode instalá-los diretamente.
-/// tip | "Dica"
+/// tip | Dica
É uma (muito) boa ideia colocar os pacotes e versões que seu programa precisa em um arquivo (por exemplo `requirements.txt` ou `pyproject.toml`).
* <a href="https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment" class="external-link" target="_blank">VS Code</a>
* <a href="https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html" class="external-link" target="_blank">PyCharm</a>
-/// tip | "Dica"
+/// tip | Dica
Normalmente, você só precisa fazer isso **uma vez**, ao criar o ambiente virtual.
-/// tip | "Dica"
+/// tip | Dica
Você quer entender o que é tudo isso acima?
end
```
-/// tip | "Dica"
+/// tip | Dica
É muito comum em pacotes Python tentar ao máximo **evitar alterações drásticas** em **novas versões**, mas é melhor prevenir do que remediar e instalar versões mais recentes intencionalmente e, quando possível, executar os testes para verificar se tudo está funcionando corretamente.
Uma dessas variáveis é a variável `PATH`.
-/// tip | "Dica"
+/// tip | Dica
Você pode aprender mais sobre a variável de ambiente `PATH` na seção [Variáveis de ambiente](environment-variables.md#path-environment-variable){.internal-link target=_blank}.
Assim, você pode confirmar se está no ambiente virtual correto.
-/// tip | "Dica"
+/// tip | Dica
É fácil ativar um ambiente virtual, obter um Python e então **ir para outro projeto**.
Это был один из первых примеров **автоматического документирования API** и это была одна из первых идей, вдохновивших на создание **FastAPI**.
-/// note | "Заметка"
+/// note | Заметка
Django REST Framework был создан Tom Christie.
Он же создал Starlette и Uvicorn, на которых основан **FastAPI**.
///
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом.
Простота Flask, показалась мне подходящей для создания API.
Но ещё нужно было найти "Django REST Framework" для Flask.
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части.
Глядите, как похоже `requests.get(...)` и `@app.get(...)`.
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
* Должен быть простой и понятный API.
* Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего.
Вот почему, когда говорят о версии 2.0, обычно говорят "Swagger", а для версии 3+ "OpenAPI".
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
Использовать открытые стандарты для спецификаций API вместо самодельных схем.
Итак, чтобы определить каждую <abbr title="Формат данных">схему</abbr>,
Вам нужно использовать определенные утилиты и классы, предоставляемые Marshmallow.
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку.
Это превосходный инструмент и я тоже часто пользовался им до **FastAPI**.
-/// info | "Информация"
+/// info | Информация
Webargs бы создан разработчиками Marshmallow.
///
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Должна быть автоматическая проверка входных данных.
Редактор кода не особо может помочь в такой парадигме.
А изменив какие-то параметры или схемы для Marshmallow можно забыть отредактировать докстринг с YAML и сгенерированная схема становится недействительной.
-/// info | "Информация"
+/// info | Информация
APISpec тоже был создан авторами Marshmallow.
///
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Необходима поддержка открытого стандарта для API - OpenAPI.
Эти генераторы проектов также стали основой для [Генераторов проектов с **FastAPI**](project-generation.md){.internal-link target=_blank}.
-/// info | "Информация"
+/// info | Информация
Как ни странно, но Flask-apispec тоже создан авторами Marshmallow.
///
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных.
Кроме того, он не очень хорошо справляется с вложенными моделями.
Если в запросе имеется объект JSON, внутренние поля которого, в свою очередь, являются вложенными объектами JSON, это не может быть должным образом задокументировано и проверено.
-/// check | "Идеи для **FastAPI** "
+/// check | Идеи для **FastAPI**
Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода.
Sanic был одним из первых чрезвычайно быстрых Python-фреймворков основанных на `asyncio`.
Он был сделан очень похожим на Flask.
-/// note | "Технические детали"
+/// note | Технические детали
В нём использован <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым.
///
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
Должна быть сумасшедшая производительность.
Либо эти функции должны быть встроены во фреймворк, сконструированный поверх Falcon, как в Hug.
Такая же особенность присутствует и в других фреймворках, вдохновлённых идеей Falcon, использовать только один объект запроса и один объект ответа.
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Найдите способы добиться отличной производительности.
Это больше похоже на Django, чем на Flask и Starlette.
Он разделяет в коде вещи, которые довольно тесно связаны.
-/// check | "Идея для **FastAPI**"
+/// check | Идея для **FastAPI**
Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию".
Это улучшает помощь редактора и раньше это не было доступно в Pydantic.
Поскольку он основан на WSGI, старом стандарте для синхронных веб-фреймворков, он не может работать с веб-сокетами и другими модными штуками, но всё равно обладает высокой производительностью.
-/// info | "Информация"
+/// info | Информация
Hug создан Timothy Crosley, автором <a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>, отличного инструмента для автоматической сортировки импортов в Python-файлах.
///
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar.
Ныне APIStar - это набор инструментов для проверки спецификаций OpenAPI.
-/// info | "Информация"
+/// info | Информация
APIStar был создан Tom Christie. Тот самый парень, который создал:
///
-/// check | "Идеи для **FastAPI**"
+/// check | Идеи для **FastAPI**
Воплощение.
Его можно сравнить с Marshmallow, хотя в бенчмарках Pydantic быстрее, чем Marshmallow.
И он основан на тех же подсказках типов, которые отлично поддерживаются редакторами кода.
-/// check | "**FastAPI** использует Pydantic"
+/// check | **FastAPI** использует Pydantic
Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema).
**FastAPI** добавляет эти функции используя подсказки типов Python и Pydantic.
Ещё **FastAPI** добавляет систему внедрения зависимостей, утилиты безопасности, генерацию схемы OpenAPI и т.д.
-/// note | "Технические детали"
+/// note | Технические детали
ASGI - это новый "стандарт" разработанный участниками команды Django.
Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен.
///
-/// check | "**FastAPI** использует Starlette"
+/// check | **FastAPI** использует Starlette
В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху.
Он рекомендуется в качестве сервера для Starlette и **FastAPI**.
-/// check | "**FastAPI** рекомендует его"
+/// check | **FastAPI** рекомендует его
Как основной сервер для запуска приложения **FastAPI**.
</div>
-/// tip | "Подсказка"
+/// tip | Подсказка
Каждый раз, перед установкой новой библиотеки в виртуальное окружение при помощи `pip`, не забудьте активировать это виртуальное окружение.
Также существуют дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Нет необходимости заглядывать в `./scripts/docs.py`, просто используйте это в командной строке.
* Проверьте <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">существующие пул-реквесты</a> для Вашего языка. Добавьте отзывы с просьбой внести изменения, если они необходимы, или одобрите их.
-/// tip | "Подсказка"
+/// tip | Подсказка
Вы можете <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">добавлять комментарии с предложениями по изменению</a> в существующие пул-реквесты.
Кодом испанского языка является `es`. А значит директория для переводов на испанский язык: `docs/es/`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Главный ("официальный") язык - английский, директория для него `docs/en/`.
docs/es/docs/features.md
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Заметьте, что в пути файла мы изменили только код языка с `en` на `es`.
После чего Вы можете проверить в своем редакторе кода, что появился новый каталог `docs/ht/`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Создайте первый пул-реквест, который будет содержать только пустую директорию для нового языка, прежде чем добавлять переводы.
Для случаев, когда ошибки приводят к сбою в запущенном **процессе**, Вам понадобится добавить компонент, который **перезапустит** процесс хотя бы пару раз...
-/// tip | "Заметка"
+/// tip | Заметка
... Если приложение падает сразу же после запуска, вероятно бесполезно его бесконечно перезапускать. Но полагаю, вы заметите такое поведение во время разработки или, по крайней мере, сразу после развёртывания.
* **Облачные сервисы**, которые позаботятся обо всём за Вас
* Возможно, что облачный сервис умеет **управлять запуском дополнительных экземпляров приложения**. Вероятно, он потребует, чтоб вы указали - какой **процесс** или **образ** следует клонировать. Скорее всего, вы укажете **один процесс Uvicorn** и облачный сервис будет запускать его копии при необходимости.
-/// tip | "Заметка"
+/// tip | Заметка
Если вы не знаете, что такое **контейнеры**, Docker или Kubernetes, не переживайте.
Безусловно, возможны случаи, когда нет проблем при выполнении предварительной подготовки параллельно или несколько раз. Тогда Вам повезло, работать с ними намного проще.
-/// tip | "Заметка"
+/// tip | Заметка
Имейте в виду, что в некоторых случаях запуск вашего приложения **может не требовать каких-либо предварительных шагов вовсе**.
* Bash-скрипт, выполняющий предварительные шаги, а затем запускающий приложение.
* При этом Вам всё ещё нужно найти способ - как запускать/перезапускать *такой* bash-скрипт, обнаруживать ошибки и т.п.
-/// tip | "Заметка"
+/// tip | Заметка
Я приведу Вам больше конкретных примеров работы с контейнерами в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}.
Использование контейнеров на основе Linux имеет ряд преимуществ, включая **безопасность**, **воспроизводимость**, **простоту** и прочие.
-/// tip | "Подсказка"
+/// tip | Подсказка
Торопитесь или уже знакомы с этой технологией? Перепрыгните на раздел [Создать Docker-образ для FastAPI 👇](#docker-fastapi)
</div>
-/// info | "Информация"
+/// info | Информация
Существуют и другие инструменты управления зависимостями.
Так как команда выполняется внутри директории `/code`, в которую мы поместили папку `./app` с приложением, то **Uvicorn** сможет найти и **импортировать** объект `app` из файла `app.main`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Если ткнёте на кружок с плюсом, то увидите пояснения. 👆
</div>
-/// tip | "Подсказка"
+/// tip | Подсказка
Обратите внимание, что в конце написана точка - `.`, это то же самое что и `./`, тем самым мы указываем Docker директорию, из которой нужно выполнять сборку образа контейнера.
Это может быть другой контейнер, в котором есть, например, <a href="https://traefik.io/" class="external-link" target="_blank">Traefik</a>, работающий с **HTTPS** и **самостоятельно** обновляющий **сертификаты**.
-/// tip | "Подсказка"
+/// tip | Подсказка
Traefik совместим с Docker, Kubernetes и им подобными инструментами. Он очень прост в установке и настройке использования HTTPS для Ваших контейнеров.
Поскольку этот компонент **принимает запросы** и равномерно **распределяет** их между компонентами, его также называют **балансировщиком нагрузки**.
-/// tip | "Подсказка"
+/// tip | Подсказка
**Прокси-сервер завершения работы TLS** одновременно может быть **балансировщиком нагрузки**.
Когда вы запускаете **множество контейнеров**, в каждом из которых работает **только один процесс** (например, в кластере **Kubernetes**), может возникнуть необходимость иметь **отдельный контейнер**, который осуществит **предварительные шаги перед запуском** остальных контейнеров (например, применяет миграции к базе данных).
-/// info | "Информация"
+/// info | Информация
При использовании Kubernetes, это может быть <a href="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" class="external-link" target="_blank">Инициализирующий контейнер</a>.
* <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
-/// warning | "Предупреждение"
+/// warning | Предупреждение
Скорее всего у вас **нет необходимости** в использовании этого образа или подобного ему и лучше создать свой образ с нуля как описано тут: [Создать Docker-образ для FastAPI](#docker-fastapi).
Он также поддерживает прохождение <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker#pre_start_path" class="external-link" target="_blank">**Подготовительных шагов при запуске контейнеров**</a> при помощи скрипта.
-/// tip | "Подсказка"
+/// tip | Подсказка
Для просмотра всех возможных настроек перейдите на страницу этого Docker-образа: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
11. Запустите `uvicorn`, указав ему использовать объект `app`, расположенный в `app.main`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Если ткнёте на кружок с плюсом, то увидите объяснения, что происходит в этой строке.
Но всё несколько сложнее.
-/// tip | "Заметка"
+/// tip | Заметка
Если вы торопитесь или вам не интересно, можете перейти на следующую страницу этого пошагового руководства по размещению приложений на серверах с использованием различных технологий.
Обычно эту запись достаточно указать один раз, при первоначальной настройке всего сервера.
-/// tip | "Заметка"
+/// tip | Заметка
Уровни протоколов, работающих с именами доменов, намного ниже HTTPS, но об этом следует упомянуть здесь, так как всё зависит от доменов и IP-адресов.
Таким образом, **HTTPS** это тот же **HTTP**, но внутри **безопасного TLS-соединения** вместо чистого (незашифрованного) TCP-соединения.
-/// tip | "Заметка"
+/// tip | Заметка
Обратите внимание, что шифрование происходит на **уровне TCP**, а не на более высоком уровне HTTP.
</div>
-/// tip | "Подсказка"
+/// tip | Подсказка
С опцией `standard`, Uvicorn будет устанавливаться и использоваться с некоторыми дополнительными рекомендованными зависимостями.
////
-/// warning | "Предупреждение"
+/// warning | Предупреждение
Не забудьте удалить опцию `--reload`, если ранее пользовались ею.
FastAPI следует соглашению в том, что любые изменения "ПАТЧ"-версии предназначены для исправления багов и внесения обратно совместимых изменений.
-/// tip | "Подсказка"
+/// tip | Подсказка
"ПАТЧ" - это последнее число. Например, в `0.2.3`, ПАТЧ-версия - это `3`.
Обратно несовместимые изменения и новые функции добавляются в "МИНОРНЫЕ" версии.
-/// tip | "Подсказка"
+/// tip | Подсказка
"МИНОРНАЯ" версия - это число в середине. Например, в `0.2.3` МИНОРНАЯ версия - это `2`.
my_second_user: User = User(**second_user_data)
```
-/// info | "Информация"
+/// info | Информация
`**second_user_data` означает:
* Затем, используя **комментарий**, сообщите, что Вы сделали проверку, тогда я буду знать, что Вы действительно проверили код.
-/// info | "Информация"
+/// info | Информация
К сожалению, я не могу так просто доверять пул-реквестам, у которых уже есть несколько одобрений.
Подключайтесь к 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank"> чату в Discord</a> 👥 и общайтесь с другими участниками сообщества FastAPI.
-/// tip | "Подсказка"
+/// tip | Подсказка
Вопросы по проблемам с фреймворком лучше задавать в <a href="https://github.com/fastapi/fastapi/issues/new/choose" class="external-link" target="_blank">GitHub issues</a>, так больше шансов, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#_3){.internal-link target=_blank}.
////
-/// warning | "Внимание"
+/// warning | Внимание
Обратите внимание, что функция `Field` импортируется непосредственно из `pydantic`, а не из `fastapi`, как все остальные функции (`Query`, `Path`, `Body` и т.д.).
Функция `Field` работает так же, как `Query`, `Path` и `Body`, у неё такие же параметры и т.д.
-/// note | "Технические детали"
+/// note | Технические детали
На самом деле, `Query`, `Path` и другие функции, которые вы увидите в дальнейшем, создают объекты подклассов общего класса `Param`, который сам по себе является подклассом `FieldInfo` из Pydantic.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
Обратите внимание, что каждый атрибут модели с типом, значением по умолчанию и `Field` имеет ту же структуру, что и параметр *функции обработки пути* с `Field` вместо `Path`, `Query` и `Body`.
Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать, как задавать примеры принимаемых данных.
-/// warning | "Внимание"
+/// warning | Внимание
Дополнительные ключи, переданные в функцию `Field`, также будут присутствовать в сгенерированной OpenAPI схеме вашего приложения.
Поскольку эти ключи не являются обязательной частью спецификации OpenAPI, некоторые инструменты OpenAPI, например, [валидатор OpenAPI](https://validator.swagger.io/), могут не работать с вашей сгенерированной схемой.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать версию с `Annotated`, если это возможно.
////
-/// note | "Заметка"
+/// note | Заметка
Заметьте, что в данном случае параметр `item`, который будет взят из тела запроса, необязателен. Так как было установлено значение `None` по умолчанию.
}
```
-/// note | "Внимание"
+/// note | Внимание
Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предпологается, что он находится внутри тела с ключом `item`.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
////
-/// info | "Информация"
+/// info | Информация
`Body` также имеет все те же дополнительные параметры валидации и метаданных, как у `Query`,`Path` и других, которые вы увидите позже.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Заметка"
+/// tip | Заметка
Рекомендуется использовать `Annotated` версию, если это возможно.
}
```
-/// info | "Информация"
+/// info | Информация
Заметьте, что теперь у ключа `images` есть список объектов изображений.
////
-/// info | "Информация"
+/// info | Информация
Заметьте, что у объекта `Offer` есть список объектов `Item`, которые, в свою очередь, могут содержать необязательный список объектов `Image`
////
-/// tip | "Совет"
+/// tip | Совет
Имейте в виду, что JSON поддерживает только ключи типа `str`.
Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми.
-/// note | "Технические детали"
+/// note | Технические детали
`PATCH` менее распространен и известен, чем `PUT`.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
Эту же технику можно использовать и для операции HTTP `PUT`.
///
-/// note | "Технические детали"
+/// note | Технические детали
Обратите внимание, что входная модель по-прежнему валидируется.
Чтобы объявить тело **запроса**, необходимо использовать модели <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a>, со всей их мощью и преимуществами.
-/// info | "Информация"
+/// info | Информация
Чтобы отправить данные, необходимо использовать один из методов: `POST` (обычно), `PUT`, `DELETE` или `PATCH`.
<img src="/img/tutorial/body/image05.png">
-/// tip | "Подсказка"
+/// tip | Подсказка
Если вы используете <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> в качестве редактора, то вам стоит попробовать плагин <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>.
* Если аннотация типа параметра содержит **примитивный тип** (`int`, `float`, `str`, `bool` и т.п.), он будет интерпретирован как параметр **запроса**.
* Если аннотация типа параметра представляет собой **модель Pydantic**, он будет интерпретирован как параметр **тела запроса**.
-/// note | "Заметка"
+/// note | Заметка
FastAPI понимает, что значение параметра `q` не является обязательным, потому что имеет значение по умолчанию `= None`.
////
-/// note | "Технические детали"
+/// note | Технические детали
`Cookie` - это класс, родственный `Path` и `Query`. Он также наследуется от общего класса `Param`.
///
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Для объявления cookies, вам нужно использовать `Cookie`, иначе параметры будут интерпретированы как параметры запроса.
Для получения более подробной информации о <abbr title="Cross-Origin Resource Sharing">CORS</abbr>, обратитесь к <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Документации CORS от Mozilla</a>.
-/// note | "Технические детали"
+/// note | Технические детали
Вы также можете использовать `from starlette.middleware.cors import CORSMiddleware`.
не будет выполнена.
-/// info | "Информация"
+/// info | Информация
Для получения дополнительной информации, ознакомьтесь с <a href="https://docs.python.org/3/library/__main__.html" class="external-link" target="_blank">официальной документацией Python</a>.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
...и **FastAPI** будет знать, что делать.
-/// tip | "Подсказка"
+/// tip | Подсказка
Если это покажется вам более запутанным, чем полезным, не обращайте внимания, это вам не *нужно*.
Для этого используйте `yield` вместо `return`, а дополнительный код напишите после него.
-/// tip | "Подсказка"
+/// tip | Подсказка
Обязательно используйте `yield` один-единственный раз.
///
-/// note | "Технические детали"
+/// note | Технические детали
Любая функция, с которой может работать:
{!../../docs_src/dependencies/tutorial007.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Можно использовать как `async` так и обычные функции.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
**FastAPI** проследит за тем, чтобы все выполнялось в правильном порядке.
-/// note | "Технические детали"
+/// note | Технические детали
Это работает благодаря <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">Контекстным менеджерам</a> в Python.
Если у вас есть пользовательские исключения, которые вы хотите обрабатывать *до* возврата ответа и, возможно, модифицировать ответ, даже вызывая `HTTPException`, создайте [Cобственный обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
-/// tip | "Подсказка"
+/// tip | Подсказка
Вы все еще можете вызывать исключения, включая `HTTPException`, *до* `yield`. Но не после.
end
```
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Клиенту будет отправлен только **один ответ**. Это может быть один из ответов об ошибке или это будет ответ от *операции пути*.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
На этой диаграмме показано "HttpException", но вы также можете вызвать любое другое исключение, для которого вы создаете [Пользовательский обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
## Зависимости с `yield`, `HTTPException` и фоновыми задачами
-/// warning | "Внимание"
+/// warning | Внимание
Скорее всего, вам не нужны эти технические подробности, вы можете пропустить этот раздел и продолжить ниже.
Тем не менее, поскольку это означало бы ожидание ответа в сети, а также ненужное удержание ресурса в зависимости от доходности (например, соединение с базой данных), это было изменено в FastAPI 0.106.0.
-/// tip | "Подсказка"
+/// tip | Подсказка
Кроме того, фоновая задача обычно представляет собой независимый набор логики, который должен обрабатываться отдельно, со своими собственными ресурсами (например, собственным подключением к базе данных).
Таким образом, вы, вероятно, получите более чистый код.
### Использование менеджеров контекста в зависимостях с помощью `yield`
-/// warning | "Внимание"
+/// warning | Внимание
Это более или менее "продвинутая" идея.
{!../../docs_src/dependencies/tutorial010.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Другой способ создания контекстного менеджера - с помощью:
//// tab | Python 3.8 non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать 'Annotated' версию, если это возможно.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
И в конце она возвращает `dict`, содержащий эти значения.
-/// info | "Информация"
+/// info | Информация
**FastAPI** добавил поддержку для `Annotated` (и начал её рекомендовать) в версии 0.95.0.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
//// tab | Python 3.10+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
//// tab | Python 3.8+ non-Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно.
И потом функция берёт параметры так же, как *функция обработки пути*.
-/// tip | "Подсказка"
+/// tip | Подсказка
В следующей главе вы увидите, какие другие вещи, помимо функций, можно использовать в качестве зависимостей.
Таким образом, вы пишете общий код один раз, и **FastAPI** позаботится о его вызове для ваших *операций с путями*.
-/// check | "Проверка"
+/// check | Проверка
Обратите внимание, что вы не создаёте специальный класс и не передаёте его куда-то в **FastAPI** для регистрации, или что-то в этом роде.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
Это стандартный синтаксис python и называется "type alias", это не особенность **FastAPI**.
Это всё не важно. **FastAPI** знает, что нужно сделать. 😎
-/// note | "Информация"
+/// note | Информация
Если вам эта тема не знакома, прочтите [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} раздел о `async` и `await` в документации.
//// tab | Python 3.10 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.10 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.10 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
////
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Обратите внимание, что мы объявляем только одну зависимость в *функции операции пути* - `query_or_cookie_extractor`.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
Но, тем не менее, эта система очень мощная и позволяет вам объявлять вложенные графы (деревья) зависимостей сколь угодно глубоко.
-/// tip | "Подсказка"
+/// tip | Подсказка
Все это может показаться не столь полезным на этих простых примерах.
Функция не возвращает большой `str`, содержащий данные в формате JSON (в виде строки). Она возвращает стандартную структуру данных Python (например, `dict`) со значениями и подзначениями, которые совместимы с JSON.
-/// note | "Технические детали"
+/// note | Технические детали
`jsonable_encoder` фактически используется **FastAPI** внутри системы для преобразования данных. Однако он полезен и во многих других сценариях.
* **Модель для вывода** не должна содержать пароль.
* **Модель для базы данных**, возможно, должна содержать хэшированный пароль.
-/// danger | "Внимание"
+/// danger | Внимание
Никогда не храните пароли пользователей в чистом виде. Всегда храните "безопасный хэш", который вы затем сможете проверить.
)
```
-/// warning | "Предупреждение"
+/// warning | Предупреждение
Цель использованных в примере вспомогательных функций - не более чем демонстрация возможных операций с данными, но, конечно, они не обеспечивают настоящую безопасность.
Для этого используйте стандартные аннотации типов в Python <a href="https://docs.python.org/3/library/typing.html#typing.Union" class="external-link" target="_blank">`typing.Union`</a>:
-/// note | "Примечание"
+/// note | Примечание
При объявлении <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" class="external-link" target="_blank">`Union`</a>, сначала указывайте наиболее детальные типы, затем менее детальные. В примере ниже более детальный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`.
</div>
-/// note | "Технические детали"
+/// note | Технические детали
Команда `uvicorn main:app` обращается к:
`FastAPI` это класс в Python, который предоставляет всю функциональность для API.
-/// note | "Технические детали"
+/// note | Технические детали
`FastAPI` это класс, который наследуется непосредственно от `Starlette`.
/items/foo
```
-/// info | "Дополнительная иформация"
+/// info | Дополнительная иформация
Термин "path" также часто называется "endpoint" или "route".
* путь `/`
* использующих <abbr title="HTTP GET метод"><code>get</code> операцию</abbr>
-/// info | "`@decorator` Дополнительная информация"
+/// info | `@decorator` Дополнительная информация
Синтаксис `@something` в Python называется "декоратор".
* `@app.patch()`
* `@app.trace()`
-/// tip | "Подсказка"
+/// tip | Подсказка
Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "Технические детали"
+/// note | Технические детали
Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#_1){.internal-link target=_blank}.
}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
При вызове `HTTPException` в качестве параметра `detail` можно передавать любое значение, которое может быть преобразовано в JSON, а не только `str`.
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-/// note | "Технические детали"
+/// note | Технические детали
Также можно использовать `from starlette.requests import Request` и `from starlette.responses import JSONResponse`.
#### `RequestValidationError` или `ValidationError`
-/// warning | "Внимание"
+/// warning | Внимание
Это технические детали, которые можно пропустить, если они не важны для вас сейчас.
{!../../docs_src/handling_errors/tutorial004.py!}
```
-/// note | "Технические детали"
+/// note | Технические детали
Можно также использовать `from starlette.responses import PlainTextResponse`.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
////
-/// note | "Технические детали"
+/// note | Технические детали
`Header` - это "родственный" класс `Path`, `Query` и `Cookie`. Он также наследуется от того же общего класса `Param`.
///
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Чтобы объявить заголовки, важно использовать `Header`, иначе параметры интерпретируются как query-параметры.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
////
-/// warning | "Внимание"
+/// warning | Внимание
Прежде чем установить для `convert_underscores` значение `False`, имейте в виду, что некоторые HTTP-прокси и серверы запрещают использование заголовков с подчеркиванием.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.9+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
...это также включает `uvicorn`, который вы можете использовать в качестве сервера, который запускает ваш код.
-/// note | "Технические детали"
+/// note | Технические детали
Вы также можете установить его по частям.
{!../../docs_src/metadata/tutorial001.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Вы можете использовать Markdown в поле `description`, и оно будет отображено в выводе.
Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_).
-/// tip | "Подсказка"
+/// tip | Подсказка
Вам необязательно добавлять метаданные для всех используемых тегов
{!../../docs_src/metadata/tutorial004.py!}
```
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#_3){.internal-link target=_blank}.
Существует несколько параметров, которые вы можете передать вашему *декоратору операций пути* для его настройки.
-/// warning | "Внимание"
+/// warning | Внимание
Помните, что эти параметры передаются непосредственно *декоратору операций пути*, а не вашей *функции-обработчику операций пути*.
Этот код состояния будет использован в ответе и будет добавлен в схему OpenAPI.
-/// note | "Технические детали"
+/// note | Технические детали
Вы также можете использовать `from starlette import status`.
////
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Помните, что `response_description` относится конкретно к ответу, а `description` относится к *операции пути* в целом.
///
-/// check | "Технические детали"
+/// check | Технические детали
OpenAPI указывает, что каждой *операции пути* необходимо описание ответа.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// info | "Информация"
+/// info | Информация
Поддержка `Annotated` была добавлена в FastAPI начиная с версии 0.95.0 (и с этой версии рекомендуется использовать этот подход).
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// note | "Примечание"
+/// note | Примечание
Path-параметр всегда является обязательным, поскольку он составляет часть пути.
## Задайте нужный вам порядок параметров
-/// tip | "Подсказка"
+/// tip | Подсказка
Это не имеет большого значения, если вы используете `Annotated`.
//// tab | Python 3.8 без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
## Задайте нужный вам порядок параметров, полезные приёмы
-/// tip | "Подсказка"
+/// tip | Подсказка
Это не имеет большого значения, если вы используете `Annotated`.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
* `lt`: меньше (`l`ess `t`han)
* `le`: меньше или равно (`l`ess than or `e`qual)
-/// info | "Информация"
+/// info | Информация
`Query`, `Path` и другие классы, которые мы разберём позже, являются наследниками общего класса `Param`.
///
-/// note | "Технические детали"
+/// note | Технические детали
`Query`, `Path` и другие "классы", которые вы импортируете из `fastapi`, на самом деле являются функциями, которые при вызове возвращают экземпляры одноимённых классов.
Здесь, `item_id` объявлен типом `int`.
-/// check | "Заметка"
+/// check | Заметка
Это обеспечит поддержку редактора внутри функции (проверка ошибок, автодополнение и т.п.).
{"item_id":3}
```
-/// check | "Заметка"
+/// check | Заметка
Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`.
Та же ошибка возникнет, если вместо `int` передать `float` , например: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
-/// check | "Заметка"
+/// check | Заметка
**FastAPI** обеспечивает проверку типов, используя всё те же определения типов.
<img src="/img/tutorial/path-params/image01.png">
-/// check | "Заметка"
+/// check | Заметка
Ещё раз, просто используя определения типов, **FastAPI** обеспечивает автоматическую интерактивную документацию (с интеграцией Swagger UI).
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">Перечисления (enum) доступны в Python</a> начиная с версии 3.4.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия <abbr title="Технически, это архитектуры моделей глубокого обучения">моделей</abbr> машинного обучения.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Значение `"lenet"` также можно получить с помощью `ModelName.lenet.value`.
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Возможно, вам понадобится, чтобы параметр содержал `/home/johndoe/myfile.txt` с ведущим слэшем (`/`).
Query-параметр `q` имеет тип `Union[str, None]` (или `str | None` в Python 3.10). Это означает, что входной параметр будет типа `str`, но может быть и `None`. Ещё параметр имеет значение по умолчанию `None`, из-за чего FastAPI определит параметр как необязательный.
-/// note | "Технические детали"
+/// note | Технические детали
FastAPI определит параметр `q` как необязательный, потому что его значение по умолчанию `= None`.
В предыдущих версиях FastAPI (ниже <abbr title="ранее 2023-03">0.95.0</abbr>) необходимо было использовать `Query` как значение по умолчанию для query-параметра. Так было вместо размещения его в `Annotated`, так что велика вероятность, что вам встретится такой код. Сейчас объясню.
-/// tip | "Подсказка"
+/// tip | Подсказка
При написании нового кода и везде где это возможно, используйте `Annotated`, как было описано ранее. У этого способа есть несколько преимуществ (о них дальше) и никаких недостатков. 🍰
Но он явно объявляет его как query-параметр.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Запомните, важной частью объявления параметра как необязательного является:
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// note | "Технические детали"
+/// note | Технические детали
Наличие значения по умолчанию делает параметр необязательным.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
{!> ../../docs_src/query_params_str_validations/tutorial006.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Обратите внимание, что даже когда `Query()` используется как значение по умолчанию для параметра функции, мы не передаём `default=None` в `Query()`.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Если вы ранее не сталкивались с `...`: это специальное значение, <a href="https://docs.python.org/3/library/constants.html#Ellipsis" class="external-link" target="_blank">часть языка Python и называется "Ellipsis"</a>.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
Pydantic, мощь которого используется в FastAPI для валидации и сериализации, имеет специальное поведение для `Optional` или `Union[Something, None]` без значения по умолчанию. Вы можете узнать об этом больше в документации Pydantic, раздел <a href="https://docs.pydantic.dev/latest/concepts/models/#required-optional-fields" class="external-link" target="_blank">Обязательные Опциональные поля</a>.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
Запомните, когда вам необходимо объявить query-параметр обязательным, вы можете просто не указывать параметр `default`. Таким образом, вам редко придётся использовать `...` или `Required`.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.9+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Чтобы объявить query-параметр типом `list`, как в примере выше, вам нужно явно использовать `Query`, иначе он будет интерпретирован как тело запроса.
//// tab | Python 3.9+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
////
-/// note | "Технические детали"
+/// note | Технические детали
Запомните, что в таком случае, FastAPI не будет проверять содержимое списка.
Указанная информация будет включена в генерируемую OpenAPI документацию и использована в пользовательском интерфейсе и внешних инструментах.
-/// note | "Технические детали"
+/// note | Технические детали
Имейте в виду, что разные инструменты могут иметь разные уровни поддержки OpenAPI.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать версию с `Annotated` если возможно.
В этом случае, параметр `q` будет не обязательным и будет иметь значение `None` по умолчанию.
-/// check | "Важно"
+/// check | Важно
Также обратите внимание, что **FastAPI** достаточно умён чтобы заметить, что параметр `item_id` является path-параметром, а `q` нет, поэтому, это параметр запроса.
* `skip`, типа `int` и со значением по умолчанию `0`.
* `limit`, необязательный `int`.
-/// tip | "Подсказка"
+/// tip | Подсказка
Вы можете использовать класс `Enum` также, как ранее применяли его с [Path-параметрами](path-params.md#_7){.internal-link target=_blank}.
Используя класс `File`, мы можем позволить клиентам загружать файлы.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Чтобы получать загруженные файлы, сначала установите <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
////
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
`File` - это класс, который наследуется непосредственно от `Form`.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
Для объявления тела файла необходимо использовать `File`, поскольку в противном случае параметры будут интерпретироваться как параметры запроса или параметры тела (JSON).
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
contents = myfile.file.read()
```
-/// note | "Технические детали `async`"
+/// note | Технические детали `async`
При использовании методов `async` **FastAPI** запускает файловые методы в пуле потоков и ожидает их.
///
-/// note | "Технические детали Starlette"
+/// note | Технические детали Starlette
**FastAPI** наследует `UploadFile` непосредственно из **Starlette**, но добавляет некоторые детали для совместимости с **Pydantic** и другими частями FastAPI.
**FastAPI** позаботится о том, чтобы считать эти данные из нужного места, а не из JSON.
-/// note | "Технические детали"
+/// note | Технические детали
Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы.
///
-/// warning | "Внимание"
+/// warning | Внимание
В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.9+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`.
-/// note | "Technical Details"
+/// note | Technical Details
Можно также использовать `from starlette.responses import HTMLResponse`.
//// tab | Python 3.9+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
Вы можете определять файлы и поля формы одновременно, используя `File` и `Form`.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Чтобы получать загруженные файлы и/или данные форм, сначала установите <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
//// tab | Python 3.6+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
Вы можете объявить некоторые файлы как `bytes`, а некоторые - как `UploadFile`.
-/// warning | "Внимание"
+/// warning | Внимание
Вы можете объявить несколько параметров `File` и `Form` в операции *path*, но вы не можете также объявить поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с помощью `multipart/form-data` вместо `application/json`.
Когда вам нужно получить поля формы вместо JSON, вы можете использовать `Form`.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Чтобы использовать формы, сначала установите <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать 'Annotated' версию, если это возможно.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Рекомендуется использовать 'Annotated' версию, если это возможно.
Вы можете настроить `Form` точно так же, как настраиваете и `Body` ( `Query`, `Path`, `Cookie`), включая валидации, примеры, псевдонимы (например, `user-name` вместо `username`) и т.д.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
`Form` - это класс, который наследуется непосредственно от `Body`.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
Вам необходимо явно указывать параметр `Form` при объявлении каждого поля, иначе поля будут интерпретироваться как параметры запроса или параметры тела (JSON).
**FastAPI** гарантирует правильное чтение этих данных из соответствующего места, а не из JSON.
-/// note | "Технические детали"
+/// note | Технические детали
Данные из форм обычно кодируются с использованием "типа медиа" `application/x-www-form-urlencoded`.
///
-/// warning | "Предупреждение"
+/// warning | Предупреждение
Вы можете объявлять несколько параметров `Form` в *операции пути*, но вы не можете одновременно с этим объявлять поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с использованием `application/x-www-form-urlencoded`, а не `application/json`.
////
-/// note | "Технические детали"
+/// note | Технические детали
Помните, что параметр `response_model` является параметром именно декоратора http-методов (`get`, `post`, и т.п.). Не следует его указывать для *функций операций пути*, как вы бы поступили с другими параметрами или с телом запроса.
FastAPI будет использовать значение `response_model` для того, чтобы автоматически генерировать документацию, производить валидацию и т.п. А также для **конвертации и фильтрации выходных данных** в объявленный тип.
-/// tip | "Подсказка"
+/// tip | Подсказка
Если вы используете анализаторы типов со строгой проверкой (например, mypy), можно указать `Any` в качестве типа возвращаемого значения функции.
////
-/// info | "Информация"
+/// info | Информация
Чтобы использовать `EmailStr`, прежде необходимо установить <a href="https://github.com/JoshData/python-email-validator" class="external-link" target="_blank">`email-validator`</a>.
Используйте `pip install email-validator`
Но что если мы захотим использовать эту модель для какой-либо другой *операции пути*? Мы можем, сами того не желая, отправить пароль любому другому пользователю.
-/// danger | "Осторожно"
+/// danger | Осторожно
Никогда не храните пароли пользователей в открытом виде, а также никогда не возвращайте их в ответе, как в примере выше. В противном случае - убедитесь, что вы хорошо продумали и учли все возможные риски такого подхода и вам известно, что вы делаете.
}
```
-/// info | "Информация"
+/// info | Информация
"Под капотом" FastAPI использует метод `.dict()` у объектов моделей Pydantic <a href="https://docs.pydantic.dev/latest/concepts/serialization/#modeldict" class="external-link" target="_blank">с параметром `exclude_unset`</a>, чтобы достичь такого эффекта.
///
-/// info | "Информация"
+/// info | Информация
Вы также можете использовать:
И поэтому, они также будут включены в JSON ответа.
-/// tip | "Подсказка"
+/// tip | Подсказка
Значением по умолчанию может быть что угодно, не только `None`.
Это можно использовать как быстрый способ исключить данные из ответа, не создавая отдельную модель Pydantic.
-/// tip | "Подсказка"
+/// tip | Подсказка
Но по-прежнему рекомендуется следовать изложенным выше советам и использовать несколько моделей вместо данных параметров.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
При помощи кода `{"name","description"}` создается объект множества (`set`) с двумя строковыми значениями.
{!../../docs_src/response_status_code/tutorial001.py!}
```
-/// note | "Примечание"
+/// note | Примечание
Обратите внимание, что `status_code` является атрибутом метода-декоратора (`get`, `post` и т.д.), а не *функции-обработчика пути* в отличие от всех остальных параметров и тела запроса.
Параметр `status_code` принимает число, обозначающее HTTP код статуса ответа.
-/// info | "Информация"
+/// info | Информация
В качестве значения параметра `status_code` также может использоваться `IntEnum`, например, из библиотеки <a href="https://docs.python.org/3/library/http.html#http.HTTPStatus" class="external-link" target="_blank">`http.HTTPStatus`</a> в Python.
<img src="/img/tutorial/response-status-code/image01.png">
-/// note | "Примечание"
+/// note | Примечание
Некоторые коды статуса ответа (см. следующий раздел) указывают на то, что ответ не имеет тела.
## Об HTTP кодах статуса ответа
-/// note | "Примечание"
+/// note | Примечание
Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу.
* Для общих ошибок со стороны клиента можно просто использовать код `400`.
* `5XX` – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из 5XX кодов.
-/// tip | "Подсказка"
+/// tip | Подсказка
Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank">документацией <abbr title="Mozilla Developer Network">MDN</abbr> об HTTP кодах статуса ответа</a>.
<img src="/img/tutorial/response-status-code/image02.png">
-/// note | "Технические детали"
+/// note | Технические детали
Вы также можете использовать `from starlette import status` вместо `from fastapi import status`.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
## Запуск
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Вначале, установите библиотеку <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
<img src="/img/tutorial/security/image01.png">
-/// check | "Кнопка авторизации!"
+/// check | Кнопка авторизации!
У вас уже появилась новая кнопка "Authorize".
<img src="/img/tutorial/security/image02.png">
-/// note | "Технические детали"
+/// note | Технические детали
Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем.
В данном примере мы будем использовать **OAuth2**, с аутентификацией по паролю, используя токен **Bearer**. Для этого мы используем класс `OAuth2PasswordBearer`.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
////
-/// tip | "Подсказка"
+/// tip | Подсказка
Здесь `tokenUrl="token"` ссылается на относительный URL `token`, который мы еще не создали. Поскольку это относительный URL, он эквивалентен `./token`.
Вскоре мы создадим и саму операцию пути.
-/// info | "Дополнительная информация"
+/// info | Дополнительная информация
Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра `tokenUrl` вместо `token_url`.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
Предпочтительнее использовать версию с аннотацией, если это возможно.
**FastAPI** будет знать, что он может использовать эту зависимость для определения "схемы безопасности" в схеме OpenAPI (и автоматической документации по API).
-/// info | "Технические детали"
+/// info | Технические детали
**FastAPI** будет знать, что он может использовать класс `OAuth2PasswordBearer` (объявленный в зависимости) для определения схемы безопасности в OpenAPI, поскольку он наследуется от `fastapi.security.oauth2.OAuth2`, который, в свою очередь, наследуется от `fastapi.security.base.SecurityBase`.
OAuth2 не указывает, как шифровать сообщение, он ожидает, что ваше приложение будет обслуживаться по протоколу HTTPS.
-/// tip | "Подсказка"
+/// tip | Подсказка
В разделе **Развертывание** вы увидите [как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.](https://fastapi.tiangolo.com/ru/deployment/https/)
* Это автоматическое обнаружение определено в спецификации OpenID Connect.
-/// tip | "Подсказка"
+/// tip | Подсказка
Интеграция сторонних сервисов для аутентификации/авторизации таких как Google, Facebook, Twitter, GitHub и т.д. осуществляется достаточно легко.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "Технические детали"
+/// note | Технические детали
Вы также можете использовать `from starlette.staticfiles import StaticFiles`.
## Использование класса `TestClient`
-/// info | "Информация"
+/// info | Информация
Для использования класса `TestClient` необходимо установить библиотеку <a href="https://www.python-httpx.org" class="external-link" target="_blank">`httpx`</a>.
{!../../docs_src/app_testing/tutorial001.py!}
```
-/// tip | "Подсказка"
+/// tip | Подсказка
Обратите внимание, что тестирующая функция является обычной `def`, а не асинхронной `async def`.
///
-/// note | "Технические детали"
+/// note | Технические детали
Также можно написать `from starlette.testclient import TestClient`.
///
-/// tip | "Подсказка"
+/// tip | Подсказка
Если для тестирования Вам, помимо запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, для подключения к базе данных с помощью асинхронного драйвера), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md){.internal-link target=_blank} в расширенном руководстве.
//// tab | Python 3.10+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
По возможности используйте версию с `Annotated`.
//// tab | Python 3.8+ без Annotated
-/// tip | "Подсказка"
+/// tip | Подсказка
По возможности используйте версию с `Annotated`.
Для получения дополнительной информации о передаче данных на бэкенд с помощью `httpx` или `TestClient` ознакомьтесь с <a href="https://www.python-httpx.org" class="external-link" target="_blank">документацией HTTPX</a>.
-/// info | "Информация"
+/// info | Информация
Обратите внимание, что `TestClient` принимает данные, которые можно конвертировать в JSON, но не модели Pydantic.
İlerleyen bölümlerde diğer seçenekler, konfigürasyonlar ve ek özellikleri göreceğiz.
-/// tip | "İpucu"
+/// tip | İpucu
Sonraki bölümler **mutlaka "gelişmiş" olmak zorunda değildir**.
[Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasında ele alınanların dışında güvenlikle ilgili bazı ek özellikler vardır.
-/// tip | "İpucu"
+/// tip | İpucu
Sonraki bölümler **mutlaka "gelişmiş" olmak zorunda değildir**.
{!../../docs_src/app_testing/tutorial002.py!}
```
-/// note | "Not"
+/// note | Not
Daha fazla detay için Starlette'in <a href="https://www.starlette.io/staticfiles/" class="external-link" target="_blank">Websockets'i Test Etmek</a> dokümantasyonunu inceleyin.
**Otomatik API dökümantasyonu**nun ilk örneklerinden biri olduğu için, **FastAPI** arayışına ilham veren ilk fikirlerden biri oldu.
-/// note | "Not"
+/// note | Not
Django REST Framework'ü, aynı zamanda **FastAPI**'ın dayandığı Starlette ve Uvicorn'un da yaratıcısı olan Tom Christie tarafından geliştirildi.
///
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
Kullanıcılar için otomatik API dökümantasyonu sunan bir web arayüzüne sahip olmalı.
Flask'ın basitliği göz önünde bulundurulduğu zaman, API geliştirmek için iyi bir seçim gibi görünüyordu. Sıradaki şey ise Flask için bir "Django REST Framework"!
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
Gereken araçları ve parçaları birleştirip eşleştirmeyi kolaylaştıracak bir mikro framework olmalı.
`requests.get(...)` ile `@app.get(...)` arasındaki benzerliklere bakın.
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
* Basit ve sezgisel bir API'ya sahip olmalı.
* HTTP metot isimlerini (işlemlerini) anlaşılır olacak bir şekilde, direkt kullanmalı.
İşte bu yüzden versiyon 2.0 hakkında konuşurken "Swagger", versiyon 3 ve üzeri için ise "OpenAPI" adını kullanmak daha yaygın.
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
API spesifikasyonları için özel bir şema yerine bir <abbr title="Open Standard: Açık Standart, Açık kaynak olarak yayınlanan standart">açık standart</abbr> benimseyip kullanmalı.
Ama... Python'un tip belirteçleri gelmeden önce oluşturulmuştu. Yani her <abbr title="Verilerin nasıl oluşturulması gerektiğinin tanımı">şemayı</abbr> tanımlamak için Marshmallow'un sunduğu spesifik araçları ve sınıfları kullanmanız gerekiyordu.
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
Kod kullanarak otomatik olarak veri tipini ve veri doğrulamayı belirten "şemalar" tanımlamalı.
Webargs da harika bir araç ve onu da geçmişte henüz **FastAPI** yokken çok kullandım.
-/// info | "Bilgi"
+/// info | Bilgi
Webargs aynı Marshmallow geliştirileri tarafından oluşturuldu.
///
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
Gelen istek verisi için otomatik veri doğrulamaya sahip olmalı.
Editör bu konuda pek yardımcı olamaz. Üstelik eğer parametreleri ya da Marshmallow şemalarını değiştirip YAML kodunu güncellemeyi unutursak artık döküman geçerliliğini yitiriyor.
-/// info | "Bilgi"
+/// info | Bilgi
APISpec de aynı Marshmallow geliştiricileri tarafından oluşturuldu.
///
-/// check | "**FastAPI**'a nasıl ilham verdi?"
+/// check | **FastAPI**'a nasıl ilham verdi?
API'lar için açık standart desteği olmalı (OpenAPI gibi).
Aynı full-stack üreticiler [**FastAPI** Proje Üreticileri](project-generation.md){.internal-link target=_blank}'nin de temelini oluşturdu.
-/// info | "Bilgi"
+/// info | Bilgi
Flask-apispec de aynı Marshmallow geliştiricileri tarafından üretildi.
///
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Veri dönüşümü ve veri doğrulamayı tanımlayan kodu kullanarak otomatik olarak OpenAPI şeması oluşturmalı.
İç içe geçen derin modelleri pek iyi işleyemiyor. Yani eğer istekteki JSON gövdesi derin bir JSON objesiyse düzgün bir şekilde dökümante edilip doğrulanamıyor.
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Güzel bir editör desteği için Python tiplerini kullanmalı.
Sanic, `asyncio`'ya dayanan son derece hızlı Python kütüphanelerinden biriydi. Flask'a epey benzeyecek şekilde geliştirilmişti.
-/// note | "Teknik detaylar"
+/// note | Teknik detaylar
İçerisinde standart Python `asyncio` döngüsü yerine <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> kullanıldı. Hızının asıl kaynağı buydu.
///
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Uçuk performans sağlayacak bir yol bulmalı.
Yani veri doğrulama, veri dönüştürme ve dökümantasyonun hepsi kodda yer almalı, otomatik halledemiyoruz. Ya da Falcon üzerine bir framework olarak uygulanmaları gerekiyor, aynı Hug'da olduğu gibi. Bu ayrım Falcon'un tasarımından esinlenen, istek ve cevap objelerini parametre olarak işleyen diğer kütüphanelerde de yer alıyor.
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Harika bir performans'a sahip olmanın yollarını bulmalı.
<abbr title="Route: HTTP isteğinin gittiği yol">Yol</abbr>'lar fonksiyonun üstünde endpoint'i işleyen dekoratörler yerine farklı yerlerde tanımlanan fonksiyonlarla belirlenir. Bu Flask (ve Starlette) yerine daha çok Django'nun yaklaşımına daha yakın bir metot. Bu, kodda nispeten birbiriyle sıkı ilişkili olan şeyleri ayırmaya sebep oluyor.
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Model özelliklerinin "standart" değerlerini kullanarak veri tipleri için ekstra veri doğrulama koşulları tanımlamalı. Bu editör desteğini geliştiriyor ve daha önceden Pydantic'te yoktu.
Senkron çalışan Python web framework'lerinin standardına (WSGI) dayandığından dolayı Websocket'leri ve diğer şeyleri işleyemiyor, ancak yine de yüksek performansa sahip.
-/// info | "Bilgi"
+/// info | Bilgi
Hug, Python dosyalarında bulunan dahil etme satırlarını otomatik olarak sıralayan harika bir araç olan <a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>'un geliştiricisi Timothy Crosley tarafından geliştirildi.
///
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Hug, APIStar'ın çeşitli kısımlarında esin kaynağı oldu ve APIStar'la birlikte en umut verici bulduğum araçlardan biriydi.
Artık APIStar, OpenAPI özelliklerini doğrulamak için bir dizi araç sunan bir proje haline geldi.
-/// info | "Bilgi"
+/// info | Bilgi
APIStar, aşağıdaki projeleri de üreten Tom Christie tarafından geliştirildi:
///
-/// check | "**FastAPI**'a nasıl ilham oldu?"
+/// check | **FastAPI**'a nasıl ilham oldu?
Var oldu.
Marshmallow ile karşılaştırılabilir. Ancak karşılaştırmalarda Marshmallowdan daha hızlı görünüyor. Aynı Python tip belirteçlerine dayanıyor ve editör desteği de harika.
-/// check | "**FastAPI** nerede kullanıyor?"
+/// check | **FastAPI** nerede kullanıyor?
Bütün veri doğrulama, veri dönüştürme ve JSON Şemasına bağlı otomatik model dökümantasyonunu halletmek için!
Bu, **FastAPI**'ın onun üzerine tamamen Python tip belirteçlerine bağlı olarak eklediği (Pydantic ile) ana şeylerden biri. **FastAPI** bunun yanında artı olarak bağımlılık enjeksiyonu sistemi, güvenlik araçları, OpenAPI şema üretimi ve benzeri özellikler de ekliyor.
-/// note | "Teknik Detaylar"
+/// note | Teknik Detaylar
ASGI, Django'nun ana ekibi tarafından geliştirilen yeni bir "standart". Bir "Python standardı" (PEP) olma sürecinde fakat henüz bir standart değil.
///
-/// check | "**FastAPI** nerede kullanıyor?"
+/// check | **FastAPI** nerede kullanıyor?
Tüm temel web kısımlarında üzerine özellikler eklenerek kullanılmakta.
Starlette ve **FastAPI** için tavsiye edilen sunucu Uvicorndur.
-/// check | "**FastAPI** neden tavsiye ediyor?"
+/// check | **FastAPI** neden tavsiye ediyor?
**FastAPI** uygulamalarını çalıştırmak için ana web sunucusu Uvicorn!
return results
```
-/// note | "Not"
+/// note | Not
Sadece `async def` ile tanımlanan fonksiyonlar içinde `await` kullanabilirsiniz.
Projeniz için ilginç ve yararlı görünen bir şey varsa devam edin ve inceleyin, aksi halde bunları atlayabilirsiniz.
-/// tip | "İpucu"
+/// tip | İpucu
**FastAPI**'ı düzgün (ve önerilen) şekilde öğrenmek istiyorsanız [Öğretici - Kullanıcı Rehberi](../tutorial/index.md){.internal-link target=_blank}'ni bölüm bölüm okuyun.
**FastAPI** kullanmayacak olsanız bile tür belirteçleri hakkında bilgi edinmenizde fayda var.
-/// note | "Not"
+/// note | Not
Python uzmanıysanız ve tip belirteçleri ilgili her şeyi zaten biliyorsanız, sonraki bölüme geçin.
{!../../docs_src/python_types/tutorial006.py!}
```
-/// tip | "Ipucu"
+/// tip | Ipucu
Köşeli parantez içindeki bu dahili tiplere "tip parametreleri" denir.
//// tab | Python 3.10+ non-Annotated
-/// tip | "İpucu"
+/// tip | İpucu
Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
//// tab | Python 3.8+ non-Annotated
-/// tip | "İpucu"
+/// tip | İpucu
Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
//// tab | Python 3.10+ non-Annotated
-/// tip | "İpucu"
+/// tip | İpucu
Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
//// tab | Python 3.8+ non-Annotated
-/// tip | "İpucu"
+/// tip | İpucu
Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
////
-/// note | "Teknik Detaylar"
+/// note | Teknik Detaylar
`Cookie` sınıfı `Path` ve `Query` sınıflarının kardeşidir. Diğerleri gibi `Param` sınıfını miras alan bir sınıftır.
///
-/// info | "Bilgi"
+/// info | Bilgi
Çerez tanımlamak için `Cookie` sınıfını kullanmanız gerekmektedir, aksi taktirde parametreler sorgu parametreleri olarak yorumlanır.
</div>
-/// note | "Not"
+/// note | Not
`uvicorn main:app` komutunu şu şekilde açıklayabiliriz:
`FastAPI`, API'niz için tüm işlevselliği sağlayan bir Python sınıfıdır.
-/// note | "Teknik Detaylar"
+/// note | Teknik Detaylar
`FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır.
/items/foo
```
-/// info | "Bilgi"
+/// info | Bilgi
"Yol" genellikle "<abbr title="Endpoint: Bitim Noktası">endpoint</abbr>" veya "<abbr title="Route: Yönlendirme/Yön">route</abbr>" olarak adlandırılır.
* <abbr title="Bir HTTP GET metodu"><code>get</code> operasyonu</abbr> ile
* `/` yoluna gelen istekler
-/// info | "`@decorator` Bilgisi"
+/// info | `@decorator` Bilgisi
Python'da `@something` sözdizimi "<abbr title="Decorator">dekoratör</abbr>" olarak adlandırılır.
* `@app.patch()`
* `@app.trace()`
-/// tip | "İpucu"
+/// tip | İpucu
Her işlemi (HTTP metod) istediğiniz gibi kullanmakta özgürsünüz.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "Not"
+/// note | Not
Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasını kontrol edebilirsiniz.
Bu durumda, `item_id` bir `int` olarak tanımlanacaktır.
-/// check | "Ek bilgi"
+/// check | Ek bilgi
Bu sayede, fonksiyon içerisinde hata denetimi, kod tamamlama gibi konularda editör desteğine kavuşacaksınız.
{"item_id":3}
```
-/// check | "Ek bilgi"
+/// check | Ek bilgi
Dikkatinizi çekerim ki, fonksiyonunuzun aldığı (ve döndürdüğü) değer olan `3` bir string `"3"` değil aksine bir Python `int`'idir.
Aynı hata <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a> sayfasında olduğu gibi `int` yerine `float` bir değer verseydik de ortaya çıkardı.
-/// check | "Ek bilgi"
+/// check | Ek bilgi
Böylece, aynı Python tip tanımlaması ile birlikte, **FastAPI** veri doğrulama özelliği sağlar.
<img src="/img/tutorial/path-params/image01.png">
-/// check | "Ek bilgi"
+/// check | Ek bilgi
Üstelik, sadece aynı Python tip tanımlaması ile, **FastAPI** size otomatik ve interaktif (Swagger UI ile entegre) bir dokümantasyon sağlar.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "Bilgi"
+/// info | Bilgi
3.4 sürümünden beri <a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">enumerationlar (ya da enumlar) Python'da mevcuttur</a>.
///
-/// tip | "İpucu"
+/// tip | İpucu
Merak ediyorsanız söyleyeyim, "AlexNet", "ResNet" ve "LeNet" isimleri Makine Öğrenmesi <abbr title="Teknik olarak, Derin Öğrenme model mimarileri">modellerini</abbr> temsil eder.
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "İpucu"
+/// tip | İpucu
`"lenet"` değerine `ModelName.lenet.value` tanımı ile de ulaşabilirsiniz.
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "İpucu"
+/// tip | İpucu
Parametrenin başında `/home/johndoe/myfile.txt` yolunda olduğu gibi (`/`) işareti ile birlikte kullanmanız gerektiği durumlar olabilir.
Bu durumda, `q` fonksiyon parametresi isteğe bağlı olacak ve varsayılan değer olarak `None` alacaktır.
-/// check | "Ek bilgi"
+/// check | Ek bilgi
Ayrıca, dikkatinizi çekerim ki; **FastAPI**, `item_id` parametresinin bir yol parametresi olduğunu ve `q` parametresinin yol değil bir sorgu parametresi olduğunu fark edecek kadar beceriklidir.
* `skip`, varsayılan değeri `0` olan bir `int`.
* `limit`, isteğe bağlı bir `int`.
-/// tip | "İpucu"
+/// tip | İpucu
Ayrıca, [Yol Parametrelerinde](path-params.md#on-tanml-degerler){.internal-link target=_blank} de kullanıldığı şekilde `Enum` sınıfından faydalanabilirsiniz.
İstek gövdesinde JSON verisi yerine form alanlarını karşılamanız gerketiğinde `Form` sınıfını kullanabilirsiniz.
-/// info | "Bilgi"
+/// info | Bilgi
Formları kullanmak için öncelikle <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a> paketini indirmeniz gerekmektedir.
`Form` sınıfıyla tanımlama yaparken `Body`, `Query`, `Path` ve `Cookie` sınıflarında kullandığınız aynı validasyon, örnekler, isimlendirme (örneğin `username` yerine `user-name` kullanımı) ve daha fazla konfigurasyonu kullanabilirsiniz.
-/// info | "Bilgi"
+/// info | Bilgi
`Form` doğrudan `Body` sınıfını miras alan bir sınıftır.
///
-/// tip | "İpucu"
+/// tip | İpucu
Form gövdelerini tanımlamak için `Form` sınıfını kullanmanız gerekir; çünkü bu olmadan parametreler sorgu parametreleri veya gövde (JSON) parametreleri olarak yorumlanır.
**FastAPI** bu verilerin JSON yerine doğru şekilde okunmasını sağlayacaktır.
-/// note | "Teknik Detaylar"
+/// note | Teknik Detaylar
Form verileri normalde `application/x-www-form-urlencoded` medya tipiyle kodlanır.
///
-/// warning | "Uyarı"
+/// warning | Uyarı
*Yol operasyonları* içerisinde birden fazla `Form` parametresi tanımlayabilirsiniz ancak bunlarla birlikte JSON verisi kabul eden `Body` alanları tanımlayamazsınız çünkü bu durumda istek gövdesi `application/json` yerine `application/x-www-form-urlencoded` ile kodlanmış olur.
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "Teknik Detaylar"
+/// note | Teknik Detaylar
Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kullanabilirsiniz.
Це був один із перших прикладів **автоматичної документації API**, і саме це була одна з перших ідей, яка надихнула на «пошук» **FastAPI**.
-/// note | "Примітка"
+/// note | Примітка
Django REST Framework створив Том Крісті. Той самий творець Starlette і Uvicorn, на яких базується **FastAPI**.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Мати автоматичний веб-інтерфейс документації API.
Враховуючи простоту Flask, він здавався хорошим підходом для створення API. Наступним, що знайшов, був «Django REST Framework» для Flask.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Бути мікрофреймоворком. Зробити легким комбінування та поєднання необхідних інструментів та частин.
Зверніть увагу на схожість у `requests.get(...)` і `@app.get(...)`.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
* Майте простий та інтуїтивно зрозумілий API.
* Використовуйте імена (операції) методів HTTP безпосередньо, простим та інтуїтивно зрозумілим способом.
Тому, коли говорять про версію 2.0, прийнято говорити «Swagger», а про версію 3+ «OpenAPI».
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Прийняти і використовувати відкритий стандарт для специфікацій API замість спеціальної схеми.
Але він був створений до того, як існували підказки типу Python. Отже, щоб визначити кожну <abbr title="визначення того, як дані повинні бути сформовані">схему</abbr>, вам потрібно використовувати спеціальні утиліти та класи, надані Marshmallow.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Використовувати код для автоматичного визначення "схем", які надають типи даних і перевірку.
Це чудовий інструмент, і я також часто використовував його, перш ніж створити **FastAPI**.
-/// info | "Інформація"
+/// info | Інформація
Webargs був створений тими ж розробниками Marshmallow.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Мати автоматичну перевірку даних вхідного запиту.
Редактор тут нічим не може допомогти. І якщо ми змінимо параметри чи схеми Marshmallow і забудемо також змінити цю строку документа YAML, згенерована схема буде застарілою.
-/// info | "Інформація"
+/// info | Інформація
APISpec був створений тими ж розробниками Marshmallow.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Підтримувати відкритий стандарт API, OpenAPI.
І ці самі генератори повного стеку були основою [**FastAPI** генераторів проектів](project-generation.md){.internal-link target=_blank}.
-/// info | "Інформація"
+/// info | Інформація
Flask-apispec був створений тими ж розробниками Marshmallow.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Створення схеми OpenAPI автоматично з того самого коду, який визначає серіалізацію та перевірку.
Він не дуже добре обробляє вкладені моделі. Отже, якщо тіло JSON у запиті є об’єктом JSON із внутрішніми полями, які, у свою чергу, є вкладеними об’єктами JSON, його неможливо належним чином задокументувати та перевірити.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Використовувати типи Python, щоб мати чудову підтримку редактора.
Це був один із перших надзвичайно швидких фреймворків Python на основі `asyncio`. Він був дуже схожий на Flask.
-/// note | "Технічні деталі"
+/// note | Технічні деталі
Він використовував <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> замість стандартного циклу Python `asyncio`. Ось що зробило його таким швидким.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Знайти спосіб отримати божевільну продуктивність.
Таким чином, перевірка даних, серіалізація та документація повинні виконуватися в коді, а не автоматично. Або вони повинні бути реалізовані як фреймворк поверх Falcon, як Hug. Така сама відмінність спостерігається в інших фреймворках, натхненних дизайном Falcon, що мають один об’єкт запиту та один об’єкт відповіді як параметри.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Знайти способи отримати чудову продуктивність.
Маршрути оголошуються в одному місці з використанням функцій, оголошених в інших місцях (замість використання декораторів, які можна розмістити безпосередньо поверх функції, яка обробляє кінцеву точку). Це ближче до того, як це робить Django, ніж до Flask (і Starlette). Він розділяє в коді речі, які відносно тісно пов’язані.
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Визначити додаткові перевірки для типів даних, використовуючи значення "за замовчуванням" атрибутів моделі. Це покращує підтримку редактора, а раніше вона була недоступна в Pydantic.
Оскільки він заснований на попередньому стандарті для синхронних веб-фреймворків Python (WSGI), він не може працювати з Websockets та іншими речами, хоча він також має високу продуктивність.
-/// info | "Інформація"
+/// info | Інформація
Hug створив Тімоті Крослі, той самий творець <a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>, чудовий інструмент для автоматичного сортування імпорту у файлах Python.
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Hug надихнув частину APIStar і був одним із найбільш перспективних інструментів, поряд із APIStar.
Тепер APIStar — це набір інструментів для перевірки специфікацій OpenAPI, а не веб-фреймворк.
-/// info | "Інформація"
+/// info | Інформація
APIStar створив Том Крісті. Той самий хлопець, який створив:
///
-/// check | "Надихнуло **FastAPI** на"
+/// check | Надихнуло **FastAPI** на
Існувати.
Його можна порівняти з Marshmallow. Хоча він швидший за Marshmallow у тестах. Оскільки він базується на тих самих підказках типу Python, підтримка редактора чудова.
-/// check | "**FastAPI** використовує його для"
+/// check | **FastAPI** використовує його для
Виконання перевірки всіх даних, серіалізації даних і автоматичної документацію моделі (на основі схеми JSON).
Це одна з головних речей, які **FastAPI** додає зверху, все на основі підказок типу Python (з використанням Pydantic). Це, а також система впровадження залежностей, утиліти безпеки, створення схеми OpenAPI тощо.
-/// note | "Технічні деталі"
+/// note | Технічні деталі
ASGI — це новий «стандарт», який розробляється членами основної команди Django. Це ще не «стандарт Python» (PEP), хоча вони в процесі цього.
///
-/// check | "**FastAPI** використовує його для"
+/// check | **FastAPI** використовує його для
Керування всіма основними веб-частинами. Додавання функцій зверху.
Це рекомендований сервер для Starlette і **FastAPI**.
-/// check | "**FastAPI** рекомендує це як"
+/// check | **FastAPI** рекомендує це як
Основний веб-сервер для запуску програм **FastAPI**.
`Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо.
-/// note | "Технічні деталі"
+/// note | Технічні деталі
Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic.
////
-/// note | "Технічні Деталі"
+/// note | Технічні Деталі
`Cookie` це "сестра" класів `Path` і `Query`. Вони наслідуються від одного батьківського класу `Param`.
Але пам'ятайте, що коли ви імпортуєте `Query`, `Path`, `Cookie` та інше з `fastapi`, це фактично функції, що повертають спеціальні класи.
Вона не повертає велику строку `str`, яка містить дані у форматі JSON (як строка). Вона повертає стандартну структуру даних Python (наприклад `dict`) із значеннями та підзначеннями, які є сумісними з JSON.
-/// note | "Примітка"
+/// note | Примітка
`jsonable_encoder` фактично використовується **FastAPI** внутрішньо для перетворення даних. Проте вона корисна в багатьох інших сценаріях.
`FastAPI` це клас у Python, який надає всю функціональність для API.
-/// note | "Технічні деталі"
+/// note | Технічні деталі
`FastAPI` це клас, який успадковується безпосередньо від `Starlette`.
/items/foo
```
-/// info | "Додаткова інформація"
+/// info | Додаткова інформація
"Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route).
* шлях `/`
* використовуючи <abbr title="an HTTP GET method"><code>get</code> операцію</abbr>
-/// info | "`@decorator` Додаткова інформація"
+/// info | `@decorator` Додаткова інформація
Синтаксис `@something` у Python називається "декоратором".
* `@app.patch()`
* `@app.trace()`
-/// tip | "Порада"
+/// tip | Порада
Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд.
{!../../docs_src/first_steps/tutorial003.py!}
```
-/// note | "Примітка"
+/// note | Примітка
Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
`FastAPI` là một Python class cung cấp tất cả chức năng cho API của bạn.
-/// note | "Chi tiết kĩ thuật"
+/// note | Chi tiết kĩ thuật
`FastAPI` là một class kế thừa trực tiếp `Starlette`.
{!../../docs_src/additional_status_codes/tutorial001.py!}
```
-/// warning | "警告"
+/// warning | 警告
当你直接返回一个像上面例子中的 `Response` 对象时，它会直接返回。
///
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用 `from starlette.responses import JSONResponse`。
{!../../docs_src/dependencies/tutorial011.py!}
```
-/// tip | "提示"
+/// tip | 提示
本章示例有些刻意，也看不出有什么用处。
proxy --> server
```
-/// tip | "提示"
+/// tip | 提示
IP `0.0.0.0` 常用于指程序监听本机或服务器上的所有有效 IP。
Hypercorn 也支持 `--root-path `选项。
-/// note | "技术细节"
+/// note | 技术细节
ASGI 规范定义的 `root_path` 就是为了这种用例。
这个文件把 Traefik 监听端口设置为 `9999`，并设置要使用另一个文件 `routes.toml`。
-/// tip | "提示"
+/// tip | 提示
使用端口 9999 代替标准的 HTTP 端口 80，这样就不必使用管理员权限运行（`sudo`）。
}
```
-/// tip | "提示"
+/// tip | 提示
注意，就算访问 `http://127.0.0.1:8000/app`，也显示从选项 `--root-path` 中提取的 `/api/v1`，这是 `root_path` 的值。
## 附加的服务器
-/// warning | "警告"
+/// warning | 警告
此用例较难，可以跳过。
}
```
-/// tip | "提示"
+/// tip | 提示
注意，自动生成服务器时，`url` 的值 `/api/v1` 提取自 `roog_path`。
<img src="/img/tutorial/behind-a-proxy/image03.png">
-/// tip | "提示"
+/// tip | 提示
API 文档与所选的服务器进行交互。
并且如果该 `Response` 有一个 JSON 媒体类型（`application/json`），比如使用 `JSONResponse` 或者 `UJSONResponse` 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换（和过滤）。
-/// note | "说明"
+/// note | 说明
如果你使用不带有任何媒体类型的响应类，FastAPI 认为你的响应没有任何内容，所以不会在生成的OpenAPI文档中记录响应格式。
{!../../docs_src/custom_response/tutorial001b.py!}
```
-/// info | "提示"
+/// info | 提示
参数 `response_class` 也会用来定义响应的「媒体类型」。
///
-/// tip | "小贴士"
+/// tip | 小贴士
`ORJSONResponse` 目前只在 FastAPI 中可用，而在 Starlette 中不可用。
{!../../docs_src/custom_response/tutorial002.py!}
```
-/// info | "提示"
+/// info | 提示
参数 `response_class` 也会用来定义响应的「媒体类型」。
{!../../docs_src/custom_response/tutorial003.py!}
```
-/// warning | "警告"
+/// warning | 警告
*路径操作函数* 直接返回的 `Response` 不会被 OpenAPI 的文档记录（比如，`Content-Type` 不会被文档记录），并且在自动化交互文档中也是不可见的。
///
-/// info | "提示"
+/// info | 提示
当然，实际的 `Content-Type` 头，状态码等等，将来自于你返回的 `Response` 对象。
要记得你可以使用 `Response` 来返回任何其他东西，甚至创建一个自定义的子类。
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用 `from starlette.responses import HTMLResponse`。
`UJSONResponse` 是一个使用 <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a> 的可选 JSON 响应。
-/// warning | "警告"
+/// warning | 警告
在处理某些边缘情况时，`ujson` 不如 Python 的内置实现那么谨慎。
{!../../docs_src/custom_response/tutorial001.py!}
```
-/// tip | "小贴士"
+/// tip | 小贴士
`ORJSONResponse` 可能是一个更快的选择。
{!../../docs_src/custom_response/tutorial008.py!}
```
-/// tip | "小贴士"
+/// tip | 小贴士
注意在这里，因为我们使用的是不支持 `async` 和 `await` 的标准 `open()`，我们使用普通的 `def` 声明了路径操作。
数据类的和运作方式与 Pydantic 模型相同。实际上，它的底层使用的也是 Pydantic。
-/// info | "说明"
+/// info | 说明
注意，数据类不支持 Pydantic 模型的所有功能。
事件函数既可以声明为异步函数（`async def`），也可以声明为普通函数（`def`）。
-/// warning | "警告"
+/// warning | 警告
**FastAPI** 只执行主应用中的事件处理器，不执行[子应用 - 挂载](sub-applications.md){.internal-link target=_blank}中的事件处理器。
此处，`shutdown` 事件处理器函数在 `log.txt` 中写入一行文本 `Application shutdown`。
-/// info | "说明"
+/// info | 说明
`open()` 函数中，`mode="a"` 指的是**追加**。因此这行文本会添加在文件已有内容之后，不会覆盖之前的内容。
///
-/// tip | "提示"
+/// tip | 提示
注意，本例使用 Python `open()` 标准函数与文件交互。
///
-/// info | "说明"
+/// info | 说明
有关事件处理器的详情，请参阅 <a href="https://www.starlette.io/events/" class="external-link" target="_blank">Starlette 官档 - 事件</a>。
**FastAPI** 为常见用例提供了一些中间件，下面介绍怎么使用这些中间件。
-/// note | "技术细节"
+/// note | 技术细节
以下几个示例中也可以使用 `from starlette.middleware.something import SomethingMiddleware`。
{!../../docs_src/openapi_callbacks/tutorial001.py!}
```
-/// tip | "提示"
+/// tip | 提示
`callback_url` 查询参数使用 Pydantic 的 <a href="https://pydantic-docs.helpmanual.io/usage/types/#urls" class="external-link" target="_blank">URL</a> 类型。
本例没有实现回调本身（只是一行代码），只有文档部分。
-/// tip | "提示"
+/// tip | 提示
实际的回调只是 HTTP 请求。
我们要使用与存档*外部 API* 相同的知识……通过创建外部 API 要实现的*路径操作*（您的 API 要调用的）。
-/// tip | "提示"
+/// tip | 提示
编写存档回调的代码时，假设您是*外部开发者*可能会用的上。并且您当前正在实现的是*外部 API*，不是*您自己的 API*。
}
```
-/// tip | "提示"
+/// tip | 提示
注意，回调 URL包含 `callback_url` （`https://www.external.org/events`）中的查询参数，还有 JSON 请求体内部的发票 ID（`2expen51ve`）。
{!../../docs_src/openapi_callbacks/tutorial001.py!}
```
-/// tip | "提示"
+/// tip | 提示
注意，不能把路由本身（`invoices_callback_router`）传递给 `callback=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。
### 更多信息
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。
事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。
-/// tip | "小贴士"
+/// tip | 小贴士
`JSONResponse` 本身是一个 `Response` 的子类。
{!../../docs_src/response_directly/tutorial001.py!}
```
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用 `from starlette.responses import JSONResponse`。
```
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用`from starlette.responses import Response`或`from starlette.responses import JSONResponse`。
除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性.
-/// tip | "小贴士"
+/// tip | 小贴士
接下来的章节 **并不一定是 "高级的"**.
本章介绍如何在 **FastAPI** 应用中使用 OAuth2 作用域管理验证与授权。
-/// warning | "警告"
+/// warning | 警告
本章内容较难，刚接触 FastAPI 的新手可以跳过。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-/// info | "说明"
+/// info | 说明
OAuth2 中，**作用域**只是声明特定权限的字符串。
这样，返回的 JWT 令牌中就包含了作用域。
-/// danger | "危险"
+/// danger | 危险
为了简明起见，本例把接收的作用域直接添加到了令牌里。
本例要求使用作用域 `me`（还可以使用更多作用域）。
-/// note | "笔记"
+/// note | 笔记
不必在不同位置添加不同的作用域。
{!../../docs_src/security/tutorial005.py!}
```
-/// info | "技术细节"
+/// info | 技术细节
`Security` 实际上是 `Depends` 的子类，而且只比 `Depends` 多一个参数。
* `security_scopes.scopes` 包含*路径操作* `read_users_me` 的 `["me"]`，因为它在依赖项里被声明
* `security_scopes.scopes` 包含用于*路径操作* `read_system_status` 的 `[]`（空列表），并且它的依赖项 `get_current_user` 也没有声明任何 `scope`
-/// tip | "提示"
+/// tip | 提示
此处重要且**神奇**的事情是，`get_current_user` 检查每个*路径操作*时可以使用不同的 `scopes` 列表。
最安全的是代码流，但实现起来更复杂，而且需要更多步骤。因为它更复杂，很多第三方身份验证应用最终建议使用隐式流。
-/// note | "笔记"
+/// note | 笔记
每个身份验证应用都会采用不同方式会命名流，以便融合入自己的品牌。
{!../../docs_src/templates/tutorial001.py!}
```
-/// note | "笔记"
+/// note | 笔记
在FastAPI 0.108.0，Starlette 0.29.0之前，`name`是第一个参数。
并且，在此之前，`request`对象是作为context的一部分以键值对的形式传递的。
///
-/// tip | "提示"
+/// tip | 提示
通过声明 `response_class=HTMLResponse`，API 文档就能识别响应的对象是 HTML。
///
-/// note | "技术细节"
+/// note | 技术细节
您还可以使用 `from starlette.templating import Jinja2Templates`。
{!../../docs_src/dependency_testing/tutorial001.py!}
```
-/// tip | "提示"
+/// tip | 提示
**FastAPI** 应用中的任何位置都可以实现覆盖依赖项。
app.dependency_overrides = {}
```
-/// tip | "提示"
+/// tip | 提示
如果只在某些测试时覆盖依赖项，您可以在测试开始时（在测试函数内）设置覆盖依赖项，并在结束时（在测试函数结尾）重置覆盖依赖项。
{!../../docs_src/app_testing/tutorial002.py!}
```
-/// note | "笔记"
+/// note | 笔记
更多细节详见 <a href="https://www.starlette.io/testclient/#testing-websocket-sessions" class="external-link" target="_blank">Starlette 官档 - 测试 WebSockets</a>。
把*路径操作函数*的参数类型声明为 `Request`，**FastAPI** 就能把 `Request` 传递到参数里。
-/// tip | "提示"
+/// tip | 提示
注意，本例除了声明请求参数之外，还声明了路径参数。
更多细节详见 <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">Starlette 官档 - `Request` 对象</a>。
-/// note | "技术细节"
+/// note | 技术细节
您也可以使用 `from starlette.requests import Request`。
{!../../docs_src/websockets/tutorial001.py!}
```
-/// note | "技术细节"
+/// note | 技术细节
您也可以使用 `from starlette.websockets import WebSocket`。
这样，你不必再去重新"安装"你的本地版本即可测试所有更改。
-/// note | "技术细节"
+/// note | 技术细节
仅当你使用此项目中的 `requirements.txt` 安装而不是直接使用 `pip install fastapi` 安装时，才会发生这种情况。
在大多数情况下，你会（且应该）有一个“终止代理”在上层为你处理 HTTPS，这取决于你如何部署应用程序，你的服务提供商可能会为你处理此事，或者你可能需要自己设置。
-/// tip | "提示"
+/// tip | 提示
你可以在 [deployment documentation](deployment/index.md){.internal-link target=_blank} 获得更多信息。
快加入 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">Discord 聊天服务器</a> 👥 和 FastAPI 社区里的小伙伴一起哈皮吧。
-/// tip | "提示"
+/// tip | 提示
如有问题，请在 <a href="https://github.com/fastapi/fastapi/issues/new/choose" class="external-link" target="_blank">GitHub Issues</a> 里提问，在这里更容易得到 [FastAPI 专家](fastapi-people.md#_3){.internal-link target=_blank}的帮助。
它将包含来自该路由器的所有路由作为其一部分。
-/// note | "技术细节"
+/// note | 技术细节
实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。
-/// info | "特别的技术细节"
+/// info | 特别的技术细节
**注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。
////
-/// warning | "警告"
+/// warning | 警告
注意，与从 `fastapi` 导入 `Query`，`Path`、`Body` 不同，要直接从 `pydantic` 导入 `Field` 。
`Field` 的工作方式和 `Query`、`Path`、`Body` 相同，参数也相同。
-/// note | "技术细节"
+/// note | 技术细节
实际上，`Query`、`Path` 都是 `Params` 的子类，而 `Params` 类又是 Pydantic 中 `FieldInfo` 的子类。
///
-/// tip | "提示"
+/// tip | 提示
注意，模型属性的类型、默认值及 `Field` 的代码结构与*路径操作函数*的参数相同，只不过是用 `Field` 替换了`Path`、`Query`、`Body`。
即，只发送要更新的数据，其余数据保持不变。
-/// note | "笔记"
+/// note | 笔记
`PATCH` 没有 `PUT` 知名，也怎么不常用。
{!../../docs_src/body_updates/tutorial002.py!}
```
-/// tip | "提示"
+/// tip | 提示
实际上，HTTP `PUT` 也可以完成相同的操作。
但本节以 `PATCH` 为例的原因是，该操作就是为了这种用例创建的。
///
-/// note | "笔记"
+/// note | 笔记
注意，输入模型仍需验证。
使用 <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> 模型声明**请求体**，能充分利用它的功能和优点。
-/// info | "说明"
+/// info | 说明
发送数据使用 `POST`（最常用）、`PUT`、`DELETE`、`PATCH` 等操作。
<img src="/img/tutorial/body/image05.png">
-/// tip | "提示"
+/// tip | 提示
使用 <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> 编辑器时，推荐安装 <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm 插件</a>。
- 类型是（`int`、`float`、`str`、`bool` 等）**单类型**的参数，是**查询**参数
- 类型是 **Pydantic 模型**的参数，是**请求体**
-/// note | "笔记"
+/// note | 笔记
因为默认值是 `None`， FastAPI 会把 `q` 当作可选参数。
////
-/// note | "技术细节"
+/// note | 技术细节
`Cookie` 、`Path` 、`Query` 是**兄弟类**，都继承自共用的 `Param` 类。
///
-/// info | "说明"
+/// info | 说明
必须使用 `Cookie` 声明 cookie 参数，否则该参数会被解释为查询参数。
更多关于 <abbr title="Cross-Origin Resource Sharing">CORS</abbr> 的信息，请查看 <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS 文档</a>。
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用 `from starlette.middleware.cors import CORSMiddleware`。
路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
-/// tip | "提示"
+/// tip | 提示
有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
///
-/// info | "说明"
+/// info | 说明
本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
///
-/// note | "技术细节"
+/// note | 技术细节
任何一个可以与以下内容一起使用的函数：
**FastAPI** 将确保按正确的顺序运行所有内容。
-/// note | "技术细节"
+/// note | 技术细节
这是由 Python 的<a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">上下文管理器</a>完成的。
该函数接收的参数和*路径操作函数*的参数一样。
-/// tip | "提示"
+/// tip | 提示
下一章介绍，除了函数还有哪些「对象」可以用作依赖项。
这样，只编写一次代码，**FastAPI** 就可以为多个*路径操作*共享这段代码 。
-/// check | "检查"
+/// check | 检查
注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
上述这些操作都是可行的，**FastAPI** 知道该怎么处理。
-/// note | "笔记"
+/// note | 笔记
如里不了解异步，请参阅[异步：*“着急了？”*](../../async.md){.internal-link target=_blank} 一章中 `async` 和 `await` 的内容。
{!../../docs_src/dependencies/tutorial005.py!}
```
-/// info | "信息"
+/// info | 信息
注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
但它依然非常强大，能够声明任意嵌套深度的「图」或树状的依赖结构。
-/// tip | "提示"
+/// tip | 提示
这些简单的例子现在看上去虽然没有什么实用价值，
* **输出模型**不应含密码
* **数据库模型**需要加密的密码
-/// danger | "危险"
+/// danger | 危险
千万不要存储用户的明文密码。始终存储可以进行验证的**安全哈希值**。
)
```
-/// warning | "警告"
+/// warning | 警告
辅助的附加函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全机制。
为此，请使用 Python 标准类型提示 <a href="https://docs.python.org/3/library/typing.html#typing.Union" class="external-link" target="_blank">`typing.Union`</a>：
-/// note | "笔记"
+/// note | 笔记
定义 <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" class="external-link" target="_blank">`Union`</a> 类型时，要把详细的类型写在前面，然后是不太详细的类型。下例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。
`FastAPI` 是一个为你的 API 提供了所有功能的 Python 类。
-/// note | "技术细节"
+/// note | 技术细节
`FastAPI` 是直接从 `Starlette` 继承的类。
* 请求路径为 `/`
* 使用 <abbr title="HTTP GET 方法"><code>get</code> 操作</abbr>
-/// info | "`@decorator` Info"
+/// info | `@decorator` Info
`@something` 语法在 Python 中被称为「装饰器」。
```
-/// tip | "提示"
+/// tip | 提示
触发 `HTTPException` 时，可以用参数 `detail` 传递任何能转换为 JSON 的值，不仅限于 `str`。
```
-/// note | "技术细节"
+/// note | 技术细节
`from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。
### `RequestValidationError` vs `ValidationError`
-/// warning | "警告"
+/// warning | 警告
如果您觉得现在还用不到以下技术细节，可以先跳过下面的内容。
```
-/// note | "技术细节"
+/// note | 技术细节
还可以使用 `from starlette.responses import PlainTextResponse`。
////
-/// note | "技术细节"
+/// note | 技术细节
`Header` 是 `Path`、`Query`、`Cookie` 的**兄弟类**，都继承自共用的 `Param` 类。
///
-/// info | "说明"
+/// info | 说明
必须使用 `Header` 声明 header 参数，否则该参数会被解释为查询参数。
////
-/// warning | "警告"
+/// warning | 警告
注意，使用 `convert_underscores = False` 要慎重，有些 HTTP 代理和服务器不支持使用带有下划线的请求头。
注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（**login**）以及「fancy」会显示为斜体（_fancy_）。
-/// tip | "提示"
+/// tip | 提示
不必为你使用的所有标签都添加元数据。
{!../../docs_src/metadata/tutorial004.py!}
```
-/// info | "信息"
+/// info | 信息
阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags){.internal-link target=_blank}。
* 它可以对该**响应**做些什么或者执行任何需要的代码.
* 然后它返回这个 **响应**.
-/// note | "技术细节"
+/// note | 技术细节
如果你使用了 `yield` 关键字依赖, 依赖中的退出代码将在执行中间件*后*执行.
///
-/// note | "技术细节"
+/// note | 技术细节
你也可以使用 `from starlette.requests import Request`.
*路径操作装饰器*支持多种配置参数。
-/// warning | "警告"
+/// warning | 警告
注意：以下参数应直接传递给**路径操作装饰器**，不能传递给*路径操作函数*。
状态码在响应中使用，并会被添加到 OpenAPI 概图。
-/// note | "技术细节"
+/// note | 技术细节
也可以使用 `from starlette import status` 导入状态码。
{!../../docs_src/path_operation_configuration/tutorial005.py!}
```
-/// info | "说明"
+/// info | 说明
注意，`response_description` 只用于描述响应，`description` 一般则用于描述*路径操作*。
///
-/// check | "检查"
+/// check | 检查
OpenAPI 规定每个*路径操作*都要有响应描述。
///
-/// note | "技术细节"
+/// note | 技术细节
当你从 `fastapi` 导入 `Query`、`Path` 和其他同类对象时，它们实际上是函数。
本例把 `item_id` 的类型声明为 `int`。
-/// check | "检查"
+/// check | 检查
类型声明将为函数提供错误检查、代码补全等编辑器支持。
{"item_id":3}
```
-/// check | "检查"
+/// check | 检查
注意，函数接收并返回的值是 `3`（ `int`），不是 `"3"`（`str`）。
值的类型不是 `int ` 而是浮点数（`float`）时也会显示同样的错误，比如： <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2。</a>
-/// check | "检查"
+/// check | 检查
**FastAPI** 使用 Python 类型声明实现了数据校验。
<img src="/img/tutorial/path-params/image01.png">
-/// check | "检查"
+/// check | 检查
还是使用 Python 类型声明，**FastAPI** 提供了（集成 Swagger UI 的）API 文档。
{!../../docs_src/path_params/tutorial005.py!}
```
-/// info | "说明"
+/// info | 说明
Python 3.4 及之后版本支持<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">枚举（即 enums）</a>。
///
-/// tip | "提示"
+/// tip | 提示
**AlexNet**、**ResNet**、**LeNet** 是机器学习<abbr title="技术上来说是深度学习模型架构">模型</abbr>。
{!../../docs_src/path_params/tutorial005.py!}
```
-/// tip | "提示"
+/// tip | 提示
使用 `ModelName.lenet.value` 也能获取值 `"lenet"`。
{!../../docs_src/path_params/tutorial004.py!}
```
-/// tip | "提示"
+/// tip | 提示
注意，包含 `/home/johndoe/myfile.txt` 的路径参数要以斜杠（`/`）开头。
本例中，查询参数 `q` 是可选的，默认值为 `None`。
-/// check | "检查"
+/// check | 检查
注意，**FastAPI** 可以识别出 `item_id` 是路径参数，`q` 不是路径参数，而是查询参数。
///
-/// note | "笔记"
+/// note | 笔记
因为默认值为 `= None`，FastAPI 把 `q` 识别为可选参数。
* `skip`，默认值为 `0` 的 `int` 类型参数
* `limit`，可选的 `int` 类型参数
-/// tip | "提示"
+/// tip | 提示
还可以像在[路径参数](path-params.md#_8){.internal-link target=_blank} 中那样使用 `Enum`。
`File` 用于定义客户端的上传文件。
-/// info | "说明"
+/// info | 说明
因为上传文件以「表单数据」形式发送。
{!../../docs_src/request_files/tutorial001.py!}
```
-/// info | "说明"
+/// info | 说明
`File` 是直接继承自 `Form` 的类。
///
-/// tip | "提示"
+/// tip | 提示
声明文件体必须使用 `File`，否则，FastAPI 会把该参数当作查询参数或请求体（JSON）参数。
contents = myfile.file.read()
```
-/// note | "`async` 技术细节"
+/// note | `async` 技术细节
使用 `async` 方法时，**FastAPI** 在线程池中执行文件方法，并 `await` 操作完成。
///
-/// note | "Starlette 技术细节"
+/// note | Starlette 技术细节
**FastAPI** 的 `UploadFile` 直接继承自 **Starlette** 的 `UploadFile`，但添加了一些必要功能，使之与 **Pydantic** 及 FastAPI 的其它部件兼容。
**FastAPI** 要确保从正确的位置读取数据，而不是读取 JSON。
-/// note | "技术细节"
+/// note | 技术细节
不包含文件时，表单数据一般用 `application/x-www-form-urlencoded`「媒体类型」编码。
///
-/// warning | "警告"
+/// warning | 警告
可在一个*路径操作*中声明多个 `File` 和 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `multipart/form-data`，不是 `application/json`。
接收的也是含 `bytes` 或 `UploadFile` 的列表（`list`）。
-/// note | "技术细节"
+/// note | 技术细节
也可以使用 `from starlette.responses import HTMLResponse`。
FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。
-/// info | "说明"
+/// info | 说明
接收上传文件或表单数据，要预先安装 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>。
声明文件可以使用 `bytes` 或 `UploadFile` 。
-/// warning | "警告"
+/// warning | 警告
可在一个*路径操作*中声明多个 `File` 与 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码为 `multipart/form-data`，不是 `application/json`。
接收的不是 JSON，而是表单字段时，要使用 `Form`。
-/// info | "说明"
+/// info | 说明
要使用表单，需预先安装 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>。
使用 `Form` 可以声明与 `Body` （及 `Query`、`Path`、`Cookie`）相同的元数据和验证。
-/// info | "说明"
+/// info | 说明
`Form` 是直接继承自 `Body` 的类。
///
-/// tip | "提示"
+/// tip | 提示
声明表单体要显式使用 `Form` ，否则，FastAPI 会把该参数当作查询参数或请求体（JSON）参数。
**FastAPI** 要确保从正确的位置读取数据，而不是读取 JSON。
-/// note | "技术细节"
+/// note | 技术细节
表单数据的「媒体类型」编码一般为 `application/x-www-form-urlencoded`。
///
-/// warning | "警告"
+/// warning | 警告
可在一个*路径操作*中声明多个 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`，不是 `application/json`。
* 会将输出数据限制在该模型定义内。下面我们会看到这一点有多重要。
-/// note | "技术细节"
+/// note | 技术细节
响应模型在参数中被声明，而不是作为函数返回类型的注解，这是因为路径函数可能不会真正返回该响应模型，而是返回一个 `dict`、数据库对象或其他模型，然后再使用 `response_model` 来执行字段约束和序列化。
{!../../docs_src/response_status_code/tutorial001.py!}
```
-/// note | "笔记"
+/// note | 笔记
注意，`status_code` 是（`get`、`post` 等）**装饰器**方法中的参数。与之前的参数和请求体不同，不是*路径操作函数*的参数。
`status_code` 参数接收表示 HTTP 状态码的数字。
-/// info | "说明"
+/// info | 说明
`status_code` 还能接收 `IntEnum` 类型，比如 Python 的 <a href="https://docs.python.org/3/library/http.html#http.HTTPStatus" class="external-link" target="_blank">`http.HTTPStatus`</a>。
<img src="/img/tutorial/response-status-code/image01.png">
-/// note | "笔记"
+/// note | 笔记
某些响应状态码表示响应没有响应体（参阅下一章）。
## 关于 HTTP 状态码
-/// note | "笔记"
+/// note | 笔记
如果已经了解 HTTP 状态码，请跳到下一章。
* 对于来自客户端的一般错误，可以只使用 `400`
* `500` 及以上的状态码用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时，会自动返回这些状态代码
-/// tip | "提示"
+/// tip | 提示
状态码及适用场景的详情，请参阅 <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN 的 HTTP 状态码</abbr>文档</a>。
<img src="../../../../../../img/tutorial/response-status-code/image02.png">
-/// note | "技术细节"
+/// note | 技术细节
也可以使用 `from starlette import status`。
## 运行
-/// info | "说明"
+/// info | 说明
先安装 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>。
<img src="/img/tutorial/security/image01.png">
-/// check | "Authorize 按钮！"
+/// check | Authorize 按钮！
页面右上角出现了一个「**Authorize**」按钮。
<img src="/img/tutorial/security/image02.png">
-/// note | "笔记"
+/// note | 笔记
目前，在表单中输入内容不会有任何反应，后文会介绍相关内容。
本例使用 **OAuth2** 的 **Password** 流以及 **Bearer** 令牌（`Token`）。为此要使用 `OAuth2PasswordBearer` 类。
-/// info | "说明"
+/// info | 说明
`Bearer` 令牌不是唯一的选择。
{!../../docs_src/security/tutorial001.py!}
```
-/// tip | "提示"
+/// tip | 提示
在此，`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。
接下来，学习如何创建实际的路径操作。
-/// info | "说明"
+/// info | 说明
严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。
**FastAPI** 使用依赖项在 OpenAPI 概图（及 API 文档）中定义**安全方案**。
-/// info | "技术细节"
+/// info | 技术细节
**FastAPI** 使用（在依赖项中声明的）类 `OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案，这是因为它继承自 `fastapi.security.oauth2.OAuth2`，而该类又是继承自`fastapi.security.base.SecurityBase`。
这有助于在函数内部使用代码补全和类型检查。
-/// tip | "提示"
+/// tip | 提示
还记得请求体也是使用 Pydantic 模型声明的吧。
///
-/// check | "检查"
+/// check | 检查
依赖系统的这种设计方式可以支持不同的依赖项返回同一个 `User` 模型。
</div>
-/// info | "说明"
+/// info | 说明
如果您打算使用类似 RSA 或 ECDSA 的数字签名算法，您应该安装加密库依赖项 `pyjwt[crypto]`。
</div>
-/// tip | "提示"
+/// tip | 提示
`passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。
创建用于密码哈希和身份校验的 PassLib **上下文**。
-/// tip | "提示"
+/// tip | 提示
PassLib 上下文还支持使用不同哈希算法的功能，包括只能校验的已弃用旧算法等。
////
-/// note | "笔记"
+/// note | 笔记
查看新的（伪）数据库 `fake_users_db`，就能看到哈希后的密码：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
用户名: `johndoe` 密码: `secret`
-/// check | "检查"
+/// check | 检查
注意，代码中没有明文密码**`secret`**，只保存了它的哈希值。
<img src="https://fastapi.tiangolo.com/img/tutorial/security/image10.png">
-/// note | "笔记"
+/// note | 笔记
注意，请求中 `Authorization` 响应头的值以 `Bearer` 开头。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-/// info | "说明"
+/// info | 说明
OAuth2 中，**作用域**只是声明指定权限的字符串。
* 可选的 `scope` 字段，由多个空格分隔的字符串组成的长字符串
* 可选的 `grant_type`
-/// tip | "提示"
+/// tip | 提示
实际上，OAuth2 规范*要求* `grant_type` 字段使用固定值 `password`，但 `OAuth2PasswordRequestForm` 没有作强制约束。
* 可选的 `client_id`（本例未使用）
* 可选的 `client_secret`（本例未使用）
-/// info | "说明"
+/// info | 说明
`OAuth2PasswordRequestForm` 与 `OAuth2PasswordBearer` 一样，都不是 FastAPI 的特殊类。
### 使用表单数据
-/// tip | "提示"
+/// tip | 提示
`OAuth2PasswordRequestForm` 类依赖项的实例没有以空格分隔的长字符串属性 `scope`，但它支持 `scopes` 属性，由已发送的 scope 字符串列表组成。
)
```
-/// info | "说明"
+/// info | 说明
`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。
本例只是简单的演示，返回的 Token 就是 `username`，但这种方式极不安全。
-/// tip | "提示"
+/// tip | 提示
下一章介绍使用哈希密码和 <abbr title="JSON Web Tokens">JWT</abbr> Token 的真正安全机制。
{!../../docs_src/security/tutorial003.py!}
```
-/// tip | "提示"
+/// tip | 提示
按规范的要求，应像本示例一样，返回带有 `access_token` 和 `token_type` 的 JSON 对象。
{!../../docs_src/security/tutorial003.py!}
```
-/// info | "说明"
+/// info | 说明
此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。
...仅用于`SQLite`，在其他数据库不需要它。
-/// info | "技术细节"
+/// info | 技术细节
默认情况下，SQLite 只允许一个线程与其通信，假设有多个线程的话，也只将处理一个独立的请求。
////
-/// info | "技术细节"
+/// info | 技术细节
参数`db`实际上是 type `SessionLocal`，但是这个类（用 创建`sessionmaker()`）是 SQLAlchemy 的“代理” `Session`，所以，编辑器并不真正知道提供了哪些方法。
///
-/// note | "Very Technical Details"
+/// note | Very Technical Details
如果您很好奇并且拥有深厚的技术知识，您可以在[Async](https://fastapi.tiangolo.com/zh/async/#very-technical-details)文档中查看有关如何处理 `async def`于`def`差别的技术细节。
{!../../docs_src/static_files/tutorial001.py!}
```
-/// note | "技术细节"
+/// note | 技术细节
你也可以用 `from starlette.staticfiles import StaticFiles`。
## 使用 `TestClient`
-/// info | "信息"
+/// info | 信息
要使用 `TestClient`，先要安装 <a href="https://www.python-httpx.org" class="external-link" target="_blank">`httpx`</a>.
{!../../docs_src/app_testing/tutorial001.py!}
```
-/// tip | "提示"
+/// tip | 提示
注意测试函数是普通的 `def`，不是 `async def`。
///
-/// note | "技术细节"
+/// note | 技术细节
你也可以用 `from starlette.testclient import TestClient`。
///
-/// tip | "提示"
+/// tip | 提示
除了发送请求之外，如果你还想测试时在FastAPI应用中调用 `async` 函数（例如异步数据库函数）， 可以在高级教程中看下 [Async Tests](../advanced/async-tests.md){.internal-link target=_blank} 。
//// tab | Python 3.10+ non-Annotated
-/// tip | "提示"
+/// tip | 提示
Prefer to use the `Annotated` version if possible.
//// tab | Python 3.8+ non-Annotated
-/// tip | "提示"
+/// tip | 提示
Prefer to use the `Annotated` version if possible.
关于如何传数据给后端的更多信息 (使用`httpx` 或 `TestClient`)，请查阅 <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX 文档</a>.
-/// info | "信息"
+/// info | 信息
注意 `TestClient` 接收可以被转化为JSON的数据，而不是Pydantic模型。
projects / thirdparty / fastapi / fastapi.git / commitdiff
