///
-/// info | 情報
+/// note | 備考
`model` キーは OpenAPI の一部ではありません。
///
-/// info | 情報
+/// note | 備考
`responses` パラメータで明示的に別のメディアタイプを指定しない限り、FastAPI はレスポンスがメインのレスポンスクラスと同じメディアタイプ（デフォルトは `application/json`）であるとみなします。
この挙動は 0.118.0 で元に戻され、`yield` の後の終了コードはレスポンス送信後に実行されるようになりました。
-/// info | 情報
+/// note | 備考
以下で見るように、これはバージョン 0.106.0 より前の挙動ととても似ていますが、いくつかのコーナーケースに対する改良とバグ修正が含まれています。
{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}
-/// info | 情報
+/// note | 備考
パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するためにも使用されます。
///
-/// info | 情報
+/// note | 備考
もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返した `Response` オブジェクトに由来します。
これは Pydantic モデルの場合と同じように動作します。内部的にも同様に Pydantic を使って実現されています。
-/// info | 情報
+/// note | 備考
dataclasses は、Pydantic モデルができることをすべては行えない点に留意してください。
ここでは、`shutdown` のイベントハンドラ関数が、テキスト行 `"Application shutdown"` をファイル `log.txt` に書き込みます。
-/// info | 情報
+/// note | 情報
`open()` 関数の `mode="a"` は「追加」（append）を意味します。つまり、そのファイルに既にある内容を上書きせず、行が後ろに追記されます。
内部的には、ASGI の技術仕様において、これは [Lifespan プロトコル](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) の一部であり、`startup` と `shutdown` というイベントが定義されています。
-/// info | 情報
+/// note | 情報
Starlette の `lifespan` ハンドラについては、[Starlette の Lifespan ドキュメント](https://www.starlette.dev/lifespan/)で詳しく読むことができます。
例えば、次のようなものがあります:
* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral)
-* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi)
これらのソリューションの中にはオープンソースや無料枠を提供するものもあり、金銭的コミットメントなしで試すことができます。他の商用 SDK ジェネレータも存在し、オンラインで見つけられます。🤓
これで、上で作成したコールバック用ルーター内に、必要なコールバックの *path operation(s)*（*外部開発者* が *外部 API* に実装すべきもの）が用意できました。
-次に、*あなたの API の path operation デコレータ*の `callbacks` パラメータに、そのコールバック用ルーターの属性 `.routes`（実体はルート/*path operations* の `list`）を渡します:
+次に、*あなたの API の path operation デコレータ*の `callbacks` パラメータに、そのコールバック用ルーターの属性 `.routes` を渡します:
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | 豆知識
-`callback=` に渡すのはルーター本体（`invoices_callback_router`）ではなく、属性 `.routes`（`invoices_callback_router.routes`）である点に注意してください。
+`callbacks=` に渡すのはルーター本体（`invoices_callback_router`）ではなく、属性 `.routes`（`invoices_callback_router.routes`）である点に注意してください。FastAPI はそれらのルートを使ってコールバックの OpenAPI ドキュメントを生成します。
///
これにより、ユーザーがあなたの **Webhook** リクエストを受け取るための**API を実装**するのが大幅に簡単になります。場合によっては、ユーザーが自分たちの API コードを自動生成できるかもしれません。
-/// info | 情報
+/// note | 備考
Webhook は OpenAPI 3.1.0 以上で利用可能で、FastAPI `0.99.0` 以上が対応しています。
定義した webhook は **OpenAPI** スキーマおよび自動生成される **ドキュメント UI** に反映されます。
-/// info | 情報
+/// note | 備考
`app.webhooks` オブジェクトは実際には単なる `APIRouter` で、複数ファイルでアプリを構成する際に使うものと同じ型です。
### *path operation関数* の名前をoperationIdとして使用する { #using-the-path-operation-function-name-as-the-operationid }
-APIの関数名を `operationId` として利用したい場合、すべてのAPI関数をイテレーションし、各 *path operation* の `operation_id` を `APIRoute.name` で上書きすれば可能です。
+API の関数名を `operationId` として使いたい場合は、`FastAPI` にカスタムの `generate_unique_id_function` を渡せます。
-ã\81\99ã\81¹ã\81¦ã\81® *path operation* ã\82\92追å\8a ã\81\97ã\81\9få¾\8cã\81«è¡\8cã\81\86ã\81¹ã\81\8dã\81§す。
+ã\81\93ã\81®é\96¢æ\95°ã\81¯å\90\84 `APIRoute` ã\82\92å\8f\97ã\81\91å\8f\96ã\82\8aã\80\81ã\81\9dã\81® *path operation* ã\81§ä½¿ã\81\86 `operationId` ã\82\92è¿\94ã\81\97ã\81¾す。
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
-
-/// tip | 豆知識
-
-`app.openapi()` を手動で呼び出す場合、その前に `operationId` を更新するべきです。
-
-///
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}
/// warning | 注意
実際は、`Response` やそのサブクラスを返すことができます。
-/// info
+/// note
`JSONResponse` それ自体は、`Response` のサブクラスです。
- `instagram_basic` は Facebook / Instagram で使われています。
- `https://www.googleapis.com/auth/drive` は Google で使われています。
-/// info | 情報
+/// note | 備考
OAuth2 において「スコープ」は、必要な特定の権限を宣言する単なる文字列です。
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
-/// info | 技術詳細
+/// note | 技術詳細
`Security` は実際には `Depends` のサブクラスで、後述する追加パラメータが 1 つあるだけです。
しかし、純粋なバイナリデータや文字列をストリームしたい場合は、次のようにできます。
-/// info | 情報
+/// note | 情報
FastAPI 0.134.0 で追加されました。
また、多くの場合、ディスクやネットワークから読み出すため、読み取りはブロッキング（イベントループをブロックし得る）処理になります。
-/// info | 情報
+/// note | 情報
上記の例は例外で、`io.BytesIO` は既にメモリ上にあるため、読み取りが何かをブロックすることはありません。
この設定では、`Content-Type` ヘッダーがないリクエストでもボディが JSON として解析されます。これは古いバージョンの FastAPI と同じ挙動です。
-/// info | 情報
+/// note | 備考
この挙動と設定は FastAPI 0.132.0 で追加されました。
{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}
-/// info | 情報
+/// note | 備考
これはWebSocketであるため、`HTTPException` を発生させることはあまり意味がありません。代わりに `WebSocketException` を発生させます。
## `WSGIMiddleware` の使用 { #using-wsgimiddleware }
-/// info | 情報
+/// note | 備考
これには `a2wsgi` のインストールが必要です。例: `pip install a2wsgi`。
</div>
-/// info | 情報
+/// note | 備考
パッケージの依存関係を定義しインストールするためのフォーマットやツールは他にもあります。
コンテナという観点から、[デプロイのコンセプト](concepts.md)に共通するいくつかについて、もう一度説明しましょう。
-コンテナは主に、アプリケーションの**ビルドとデプロイ**のプロセスを簡素化するためのツールですが、これらの**デプロイのコンセプト**を扱うための特定のアプローチを強制するものではなく、いくつかの戦略があります。
+コンテナは主に、アプリケーションの**ビルドとデプロイ**のプロセスを簡素化するための工具ですが、これらの**デプロイのコンセプト**を扱うための特定のアプローチを強制するものではなく、いくつかの戦略があります。
**良いニュース**は、それぞれの異なる戦略には、すべてのデプロイメントのコンセプトをカバーする方法があるということです。🎉
複数の**コンテナ**があり、おそらくそれぞれが**単一のプロセス**を実行している場合（例えば、**Kubernetes**クラスタなど）、レプリケートされたワーカーコンテナを実行する**前に**、単一のコンテナで**事前のステップ**の作業を行う**別のコンテナ**を持ちたいと思うでしょう。
-/// info | 情報
+/// note | 備考
もしKubernetesを使用している場合, これはおそらく[Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)でしょう。
# FastAPI Cloud { #fastapi-cloud }
-[FastAPI Cloud](https://fastapicloud.com) に **コマンド1つ** でデプロイできます。まだならウェイティングリストにご登録ください。🚀
-
-## ログイン { #login }
-
-すでに **FastAPI Cloud** アカウントをお持ちであることを確認してください（ウェイティングリストからご招待しています 😉）。
-
-次にログインします:
-
-<div class="termy">
-
-```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
-```
-
-</div>
-
-## デプロイ { #deploy }
-
-では、**コマンド1つ** でアプリをデプロイします:
+[FastAPI Cloud](https://fastapicloud.com) に **コマンド1つ** で FastAPI アプリをデプロイできます。🚀
<div class="termy">
</div>
+CLI は FastAPI アプリケーションを自動検出してクラウドにデプロイします。ログインしていない場合は、認証を完了するためにブラウザが開きます。
+
以上です！その URL からアプリにアクセスできます。✨
## FastAPI Cloud について { #about-fastapi-cloud }
* [Hypercorn](https://hypercorn.readthedocs.io/): HTTP/2 や Trio に対応する ASGI サーバーなど。
* [Daphne](https://github.com/django/daphne): Django Channels のために作られた ASGI サーバー。
* [Granian](https://github.com/emmett-framework/granian): Python アプリケーション向けの Rust 製 HTTP サーバー。
-* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): 軽量で多用途な Web アプリケーションランタイム。
## サーバーマシンとサーバープログラム { #server-machine-and-server-program }
ここでは、`fastapi` コマンド、または `uvicorn` コマンドを直接使って、**ワーカープロセス**付きの **Uvicorn** を使う方法を紹介します。
-/// info | 情報
+/// note
DockerやKubernetesなどのコンテナを使用している場合は、次の章で詳しく説明します： [コンテナ内のFastAPI - Docker](docker.md)。
- `openapi_version`: 使用する OpenAPI 仕様のバージョン。デフォルトは最新の `3.1.0`。
- `summary`: API の短い概要。
- `description`: API の説明。Markdown を含めることができ、ドキュメントに表示されます。
-- `routes`: ã\83«ã\83¼ã\83\88ã\81®ã\83ªã\82¹ã\83\88ã\80\82ç\99»é\8c²æ¸\88ã\81¿ã\81®å\90\84 path operation ã\81§ã\81\99ã\80\82`app.routes` ã\81\8bã\82\89å\8f\96å¾\97ã\81\95ã\82\8cます。
+- `routes`: ã\82¢ã\83\97ã\83ªã\82±ã\83¼ã\82·ã\83§ã\83³ã\81®ã\83«ã\83¼ã\83\88ã\80\82`app.routes` ã\81\8bã\82\89å\8f\96å¾\97ã\81\95ã\82\8cã\81¾ã\81\99ã\80\82FastAPI ã\81¯ã\81\93ã\82\8cã\82\89ã\82\92使ç\94¨ã\81\97ã\81¦ã\80\81ç\99»é\8c²æ¸\88ã\81¿ã\81® path operationï¼\88å\8f\96ã\82\8aè¾¼ã\82\93ã\81 ã\83«ã\83¼ã\82¿ã\83¼ç\94±æ\9d¥ã\81®ã\82\82ã\81®ã\82\82å\90«ã\82\80ï¼\89ã\82\92å\8f\8eé\9b\86ã\81\97ます。
-/// info | 情報
+/// tip | 技術詳細
+
+`app.routes` はより低レベルなルートツリーです。最終的な `APIRoute` オブジェクトだけでなく、FastAPI が内部で使用する、取り込まれたルーター向けの候補ルートも含まれることがあります。
+
+それでも `app.routes` を `get_openapi()` に渡せます。FastAPI はそのルートツリーを走査して、有効な path operation を収集します。
+
+///
+
+/// note | 備考
パラメータ `summary` は OpenAPI 3.1.0 以降で利用可能で、FastAPI 0.99.0 以降が対応しています。
ドキュメントから試してレスポンスを確認すると、コードでは一方の `description` フィールドに何も追加していないにもかかわらず、JSON レスポンスにはデフォルト値（`null`）が含まれています:
<div class="screenshot">
-<img src="/img/tutorial/separate-openapi-schemas/image02.png">
+<img src="/img/tutorial/separate-openapi_schemas/image02.png">
</div>
つまりそのフィールドには **常に値があります**。値が `None`（JSON では `null`）になることがあるだけです。
一方、`Item-Output` では、`description` は **必須**（赤いアスタリスクあり）です。
<div class="screenshot">
-<img src="/img/tutorial/separate-openapi-schemas/image04.png">
+<img src="/img/tutorial/separate-openapi_schemas/image04.png">
</div>
この **Pydantic v2** の機能により、API ドキュメントはより **正確** になり、自動生成されたクライアントや SDK もより正確になります。これにより、より良い **開発者エクスペリエンス** と一貫性が得られます。🎉
その場合は、**FastAPI** のパラメータ `separate_input_output_schemas=False` でこの機能を無効化できます。
-/// info | 情報
+/// note | 備考
`separate_input_output_schemas` のサポートは FastAPI `0.102.0` で追加されました。🤓
### アプリをデプロイ（任意） { #deploy-your-app-optional }
-必要に応じて FastAPI アプリを [FastAPI Cloud](https://fastapicloud.com) にデプロイできます。まだの場合はウェイティングリストに参加してください。 🚀
-
-すでに **FastAPI Cloud** アカウント（ウェイティングリストから招待されました 😉）がある場合は、1 コマンドでアプリケーションをデプロイできます。
+1 コマンドで FastAPI アプリを [FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 🚀
<div class="termy">
</div>
+CLI は自動的に FastAPI アプリケーションを検出し、クラウドへデプロイします。ログインしていない場合は、認証を完了するためにブラウザが開きます。
+
これで完了です！その URL でアプリにアクセスできます。 ✨
#### FastAPI Cloud について { #about-fastapi-cloud }
/// note | 技術詳細
-実際には、`APIRouter` で宣言された各 *path operation* ごとに内部的に *path operation* が作成されます。
+FastAPI は、ルーターをメインアプリに取り込んだ後も、元の `APIRouter` とその `APIRoute` を有効なまま保持します。
-ã\81¤ã\81¾ã\82\8aè£\8få\81´ã\81§ã\81¯ã\80\81ã\81\99ã\81¹ã\81¦ã\81\8cå\90\8cã\81\98å\8d\98ä¸\80ã\81®ã\82¢ã\83\97ã\83ªã\81§ã\81\82ã\82\8bã\81\8bã\81®ã\82\88ã\81\86ã\81«å\8b\95ä½\9cします。
+ã\81\9dã\81®ã\81\9fã\82\81ã\80\81ã\82«ã\82¹ã\82¿ã\83 ã\81® `APIRouter` ã\82\84 `APIRoute` ã\81®ã\82µã\83\96ã\82¯ã\83©ã\82¹ã\82\82ã\80\81å\8f\96ã\82\8aè¾¼ã\81¿å¾\8cã\81«å¼\95ã\81\8dç¶\9aã\81\8dæ©\9fè\83½します。
///
ルーターを取り込んでもパフォーマンスを心配する必要はありません。
-ã\81\93ã\82\8cã\81¯èµ·å\8b\95æ\99\82ã\81«ã\83\9eã\82¤ã\82¯ã\83ç§\92ã\81§è¡\8cã\82\8fã\82\8cます。
+ã\81\93ã\82\8cã\81¯è»½é\87\8fã\81«è¨è¨\88ã\81\95ã\82\8cã\80\81å\90\84ã\83ªã\82¯ã\82¨ã\82¹ã\83\88ã\81«ã\82ªã\83¼ã\83\90ã\83¼ã\83\98ã\83\83ã\83\89ã\82\92追å\8a ã\81\97ã\81ªã\81\84ã\82\88ã\81\86ã\81«ã\81ªã\81£ã\81¦ã\81\84ます。
したがってパフォーマンスには影響しません。⚡
これは、それらの *path operations* を OpenAPI スキーマやユーザーインターフェースに含めたいからです。
-完全に分離して独立に「マウント」できないため、*path operations* は直接取り込まれるのではなく「クローン（再作成）」されます。
+FastAPI は元のルーターと *path operations* を有効なまま保持し、リクエスト処理や OpenAPI 生成の際に、ルーターの prefix、dependencies、tags、responses、その他のメタデータを組み合わせます。
///
router.include_router(other_router)
```
-`router` を `FastAPI` アプリに取り込む前にこれを実行して、`other_router` の *path operations* も含まれるようにしてください。
+これは、`router` を `FastAPI` アプリに取り込む前でも後でも実行できます。FastAPI は `other_router` の *path operations* をルーティングと OpenAPI に含めます。
+
+同様に、後からルーターに追加された *path operations* も、以前の取り込みを通して見えるようになります。
+
+/// warning | 注意
+
+`router` を取り込んだ後に、`router.routes` を直接ミューテートするのは避けてください。FastAPI はルーターの取り込みをライブとして扱うため、元のルーターとそのルートはルーティングと OpenAPI 生成の一部のままです。
+
+ルートやルーターを追加するには、path operation デコレータや `.include_router()` などのドキュメント化された API を使用してください。
+
+`router.routes` は、ルート定義や取り込まれたルーターを含みうる低レベルのルートツリーとして扱い、最終的な *path operations* のフラットな一覧として当てにしないでください。
+
+///
{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-/// info | 情報
+/// note | 備考
`Body`もまた、後述する `Query` や `Path` などと同様に、すべての追加検証パラメータとメタデータパラメータを持っています。
しかし、追加のボディパラメータを宣言したときのように、キー `item` を持つ JSON と、その中のモデル内容を期待したい場合は、特別な `Body` パラメータ `embed` を使うことができます:
```Python
-item: Item = Body(embed=True)
+item: Annotated[Item, Body(embed=True)]
```
以下において:
]
}
```
-
-/// info | 情報
+/// note | 備考
`images`キーが画像オブジェクトのリストを持つようになったことに注目してください。
{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
-/// info | 情報
+/// note | 備考
`Offer`は`Item`のリストであり、それらがさらにオプションの`Image`のリストを持っていることに注目してください。
**リクエスト**ボディを宣言するには、[Pydantic](https://docs.pydantic.dev/) モデルを使用し、その強力な機能とメリットをすべて利用します。
-/// info | 情報
+/// note | 備考
データを送信するには、`POST`（より一般的）、`PUT`、`DELETE`、`PATCH` のいずれかを使用すべきです。
<img src="/img/tutorial/cookie-param-models/image01.png">
</div>
-/// info | 情報
+/// note | 備考
**ブラウザがクッキーを処理し**ていますが、特別な方法で内部的に処理を行っているために、**JavaScript**からは簡単に操作**できない**ことに留意してください。
///
-/// info | 情報
+/// note | 備考
クッキーを宣言するには、`Cookie`を使う必要があります。なぜなら、そうしないとパラメータがクエリのパラメータとして解釈されてしまうからです。
///
-/// info | 情報
+/// note | 備考
**ブラウザがクッキーを**特殊な方法で裏側で扱うため、**JavaScript** から簡単には触れられないことを念頭に置いてください。
///
-/// info | 情報
+/// note | 備考
この例では、架空のカスタムヘッダー `X-Key` と `X-Token` を使用しています。
-しかし実際のケースでセキュリティを実装する際は、統合された[Security utilities（次の章）](../security/index.md)を使うことで、より多くの利点を得られます。
+しかし実際のケースでセキュリティを実装する際は、統合された[セキュリティユーティリティ（次の章）](../security/index.md)を使うことで、より多くの利点を得られます。
///
## *path operation*のグループに対する依存関係 { #dependencies-for-a-group-of-path-operations }
-後で、より大きなアプリケーションを（おそらく複数ファイルで）構造化する方法（[Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md)）について読むときに、*path operation*のグループに対して単一の`dependencies`パラメータを宣言する方法を学びます。
+後で、より大きなアプリケーションを（おそらく複数ファイルで）構造化する方法（[より大きなアプリケーション - 複数ファイル](../../tutorial/bigger-applications.md)）について読むときに、*path operation*のグループに対して単一の`dependencies`パラメータを宣言する方法を学びます。
## グローバル依存関係 { #global-dependencies }
end
```
-/// info | 情報
+/// note | 備考
**１つのレスポンス** だけがクライアントに送信されます。それはエラーレスポンスの一つかもしれませんし、*path operation*からのレスポンスかもしれません。
そして、これらの値を含む`dict`を返します。
-/// info | 情報
+/// note | 備考
FastAPI はバージョン 0.95.0 で `Annotated` のサポートを追加し（そして推奨し始めました）。
この方法では、共有されるコードを一度書き、**FastAPI** が*path operation*のための呼び出しを行います。
-/// check | 確認
+/// tip | 豆知識
特別なクラスを作成してどこかで **FastAPI** に渡して「登録」する必要はないことに注意してください。
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
-/// info | 情報
+/// note | 備考
*path operation 関数*の中で宣言している依存関係は`query_or_cookie_extractor`の1つだけであることに注意してください。
from backend.main import app
```
-### パス付きの`fastapi dev` { #fastapi-dev-with-path }
+### パス指定の`fastapi dev`または`--entrypoint` CLIオプション { #fastapi-dev-with-path-or-with-entrypoint-cli-option }
`fastapi dev`コマンドにファイルパスを渡すこともでき、使用すべきFastAPIのappオブジェクトを推測します:
$ fastapi dev main.py
```
-ただし、その場合は毎回`fastapi`コマンドを呼ぶたびに正しいパスを渡すことを覚えておく必要があります。
-
-さらに、他のツール（たとえば、[VS Code 拡張機能](../editor-support.md)や[FastAPI Cloud](https://fastapicloud.com)）が見つけられない場合があります。そのため、`pyproject.toml`の`entrypoint`を使うことを推奨します。
-
-### アプリをデプロイ（任意） { #deploy-your-app-optional }
-
-任意でFastAPIアプリを[FastAPI Cloud](https://fastapicloud.com)にデプロイできます。まだなら、待機リストに登録してください。 🚀
-
-すでに**FastAPI Cloud**アカウントがある場合（待機リストから招待済みの場合😉）、1コマンドでアプリケーションをデプロイできます。
-
-デプロイする前に、ログインしていることを確認してください:
-
-<div class="termy">
+または、`fastapi dev`コマンドに`--entrypoint`オプションを渡すこともできます:
```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
+$ fastapi dev --entrypoint main:app
```
-</div>
+ただし、その場合は毎回`fastapi`コマンドを呼ぶたびに正しいパスや`entrypoint`を渡すことを覚えておく必要があります。
+
+さらに、他のツール（たとえば、[VS Code 拡張機能](../editor-support.md)や[FastAPI Cloud](https://fastapicloud.com)）が見つけられない場合があります。そのため、`pyproject.toml`の`entrypoint`を使うことを推奨します。
-その後、アプリをデプロイします:
+### アプリをデプロイ（任意） { #deploy-your-app-optional }
+
+任意でFastAPIアプリを[FastAPI Cloud](https://fastapicloud.com)に1コマンドでデプロイできます。 🚀
<div class="termy">
</div>
+CLIはFastAPIアプリケーションを自動検出してクラウドにデプロイします。ログインしていない場合、認証を完了するためにブラウザが開きます。
+
以上です！これで、そのURLでアプリにアクセスできます。 ✨
## ステップ毎の要約 { #recap-step-by-step }
/items/foo
```
-/// info | 情報
+/// note | 備考
「パス」は一般に「エンドポイント」または「ルート」とも呼ばれます。
* パス `/`
* <dfn title="HTTP GET メソッド"><code>get</code> オペレーション</dfn>
-/// info | `@decorator` 情報
+/// note | `@decorator` 情報
Pythonにおける`@something`シンタックスはデコレータと呼ばれます。
{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}
-/// info | 情報
+/// note | 備考
タグの詳細は [Path Operation の設定](path-operation-configuration.md#tags) を参照してください。
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
-/// info | 情報
+/// note | 備考
`response_description`は具体的にレスポンスを参照し、`description`は*path operation*全般を参照していることに注意してください。
///
-/// check | 確認
+/// tip | 豆知識
OpenAPIは*path operation*ごとにレスポンスの説明を必要としています。
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-/// info | 情報
+/// note | 備考
FastAPI はバージョン 0.95.0 で`Annotated`のサポートを追加し（そして推奨し始めました）。
* `lt`: `l`ess `t`han
* `le`: `l`ess than or `e`qual
-/// info | 情報
+/// note | 備考
`Query`、`Path`、および後で見る他のクラスは、共通の`Param`クラスのサブクラスです。
ここでは、 `item_id` は `int` として宣言されています。
-/// check | 確認
+/// tip | 豆知識
これにより、関数内でのエディターサポート (エラーチェックや補完など) が提供されます。
{"item_id":3}
```
-/// check | 確認
+/// tip | 豆知識
関数が受け取った（および返した）値は、文字列の `"3"` ではなく、Pythonの `int` としての `3` であることに注意してください。
[http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) で見られるように、`int` のかわりに `float` が与えられた場合にも同様なエラーが表示されます。
-/// check | 確認
+/// tip | 豆知識
したがって、同じPythonの型宣言を使用することで、**FastAPI**はデータのバリデーションを行います。
<img src="/img/tutorial/path-params/image01.png">
-/// check | 確認
+/// tip | 豆知識
繰り返しになりますが、同じPython型宣言を使用するだけで、**FastAPI**は対話的なドキュメントを自動的に生成します（Swagger UIを統合）。
そのために、まずは以下をインポートします:
-* `fastapi` から `Query`
-* `typing` から `Annotated`
+- `fastapi` から `Query`
+- `typing` から `Annotated`
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-/// info | 情報
+/// note | 備考
FastAPI はバージョン 0.95.0 で `Annotated` のサポートを追加し（推奨し始め）ました。
FastAPI は次を行います:
-* 最大長が 50 文字であることを確かめるようデータを **検証** する
-* データが有効でないときに、クライアントに **明確なエラー** を表示する
-* OpenAPI スキーマの *path operation* にパラメータを **ドキュメント化** する（その結果、**自動ドキュメント UI** に表示されます）
+- 最大長が 50 文字であることを確かめるようデータを **検証** する
+- データが有効でないときに、クライアントに **明確なエラー** を表示する
+- OpenAPI スキーマの *path operation* にパラメータを **ドキュメント化** する（その結果、**自動ドキュメント UI** に表示されます）
## 代替（古い方法）: デフォルト値としての `Query` { #alternative-old-query-as-the-default-value }
この特定の正規表現パターンは受け取ったパラメータの値をチェックします:
-* `^`: は、これ以降の文字で始まり、これより以前には文字はありません。
-* `fixedquery`: は、正確な`fixedquery`を持っています.
-* `$`: で終わる場合、`fixedquery`以降には文字はありません.
+- `^`: は、これ以降の文字で始まり、これより以前には文字はありません。
+- `fixedquery`: は、正確な`fixedquery`を持っています.
+- `$`: で終わる場合、`fixedquery`以降には文字はありません.
もしこれらすべての **「正規表現」** のアイデアについて迷っていても、心配しないでください。多くの人にとって難しい話題です。正規表現を必要としなくても、まだ、多くのことができます。
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
-/// info | 情報
+/// note | 備考
これは Pydantic バージョン 2 以上で利用できます。 😎
一般的なバリデーションとメタデータ:
-* `alias`
-* `title`
-* `description`
-* `deprecated`
+- `alias`
+- `title`
+- `description`
+- `deprecated`
文字列に固有のバリデーション:
-* `min_length`
-* `max_length`
-* `pattern`
+- `min_length`
+- `max_length`
+- `pattern`
`AfterValidator` を使ったカスタムバリデーション。
この場合、関数パラメータ `q` はオプショナルとなり、デフォルトでは `None` になります。
-/// check | 確認
+/// tip | 豆知識
パスパラメータ `item_id` はパスパラメータであり、`q` はそれとは違ってクエリパラメータであると判別できるほど**FastAPI** が賢いということにも注意してください。
`File` を使って、クライアントがアップロードするファイルを定義できます。
-/// info | 情報
+/// note | 備考
アップロードされたファイルを受け取るには、まず [`python-multipart`](https://github.com/Kludex/python-multipart) をインストールします。
{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}
-/// info | 情報
+/// note | 備考
`File` は `Form` を直接継承したクラスです。
FastAPI では、フォームフィールドを宣言するために **Pydantic モデル**を使用できます。
-/// info | 情報
+/// note | 備考
フォームを使うには、まず [`python-multipart`](https://github.com/Kludex/python-multipart) をインストールします。
`File`と`Form`を同時に使うことでファイルとフォームフィールドを定義することができます。
-/// info | 情報
+/// note | 備考
アップロードされたファイルやフォームデータを受信するには、まず[`python-multipart`](https://github.com/Kludex/python-multipart)をインストールします。
JSONの代わりにフィールドを受け取る場合は、`Form`を使用します。
-/// info | 情報
+/// note | 備考
フォームを使うためには、まず[`python-multipart`](https://github.com/Kludex/python-multipart)をインストールします。
`Form`では`Body`（および`Query`や`Path`、`Cookie`）と同じ設定を宣言することができます。これには、バリデーション、例、エイリアス（例えば`username`の代わりに`user-name`）などが含まれます。
-/// info | 情報
+/// note | 備考
`Form`は`Body`を直接継承するクラスです。
しかし、フォームがファイルを含む場合は、`multipart/form-data`としてエンコードされます。ファイルの扱いについては次の章で説明します。
-これらのエンコーディングやフォームフィールドの詳細については、[<abbr title="Mozilla Developer Network - Mozilla 開発者ネットワーク">MDN</abbr> の `POST` ウェブドキュメント](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)を参照してください。
+ã
\81\93ã
\82\8cã
\82\89ã
\81®ã
\82¨ã
\83³ã
\82³ã
\83¼ã
\83\87ã
\82£ã
\83³ã
\82°ã
\82\84ã
\83\95ã
\82©ã
\83¼ã
\83 ã
\83\95ã
\82£ã
\83¼ã
\83«ã
\83\89ã
\81®è©³ç´°ã
\81«ã
\81¤ã
\81\84ã
\81¦ã
\81¯ã
\80\81[<abbr title="Mozilla Developer Network - Mozilla é
\96\8bç
\99ºè
\80\85ã
\83\8dã
\83\83ã
\83\88ã
\83¯ã
\83¼ã
\82¯">MDN</abbr> ã
\81® `POST` ã
\81®ã\82¦ã
\82§ã
\83\96ã
\83\89ã
\82ã
\83¥ã
\83¡ã
\83³ã
\83\88](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)ã
\82\92å
\8f\82ç
\85§ã
\81\97ã
\81¦ã
\81\8fã
\81 ã
\81\95ã
\81\84ã
\80\82
///
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-/// info | 情報
+/// note | 備考
`EmailStr` を使用するには、最初に [`email-validator`](https://github.com/JoshData/python-email-validator) をインストールしてください。
}
```
-/// info | 情報
+/// note | 備考
以下も使用できます:
`status_code`パラメータはHTTPステータスコードを含む数値を受け取ります。
-/// info | 情報
+/// note | 備考
`status_code`は代わりに、Pythonの[`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus)のように、`IntEnum`を受け取ることもできます。
///
-/// info | 情報
+/// note | 備考
OpenAPI 3.1.0（FastAPI 0.99.0以降で使用）では、**JSON Schema**標準の一部である`examples`がサポートされました。
* `File()`
* `Form()`
-/// info | 情報
+/// note | 備考
この古いOpenAPI固有の`examples`パラメータは、FastAPI `0.103.0`以降は`openapi_examples`になりました。
JSON Schemaのこの新しい`examples`フィールドは、OpenAPIの他の場所（上で説明）にあるような追加メタデータを持つdictではなく、**単なる例の`list`**です。
-/// info | 情報
+/// note | 備考
OpenAPI 3.1.0がこのJSON Schemaとの新しいよりシンプルな統合とともにリリースされた後も、しばらくの間、自動ドキュメントを提供するツールであるSwagger UIはOpenAPI 3.1.0をサポートしていませんでした（バージョン5.0.0からサポートされています🎉）。
## 実行 { #run-it }
-/// info | 情報
+/// note | 備考
[`python-multipart`](https://github.com/Kludex/python-multipart) パッケージは、`pip install "fastapi[standard]"` コマンドを実行すると **FastAPI** と一緒に自動的にインストールされます。
<img src="/img/tutorial/security/image01.png">
-/// check | Authorizeボタン!
+/// tip | Authorizeボタン!
すでにピカピカの新しい「Authorize」ボタンがあります。
この例では、**Bearer**トークンを使用して**OAuth2**を**Password**フローで使用します。これには`OAuth2PasswordBearer`クラスを使用します。
-/// info | 情報
+/// note | 備考
「bearer」トークンが、唯一の選択肢ではありません。
実際の path operation もすぐに作ります。
-/// info | 情報
+/// note | 備考
非常に厳格な「Pythonista」であれば、パラメーター名のスタイルが`tokenUrl`ではなく`token_url`であることを気に入らないかもしれません。
**FastAPI**は、この依存関係を使用してOpenAPIスキーマ (および自動APIドキュメント) で「セキュリティスキーム」を定義できることを知っています。
-/// info | 技術詳細
+/// note | 技術詳細
**FastAPI**は、`OAuth2PasswordBearer` クラス (依存関係で宣言されている) を使用してOpenAPIのセキュリティスキームを定義できることを知っています。これは`fastapi.security.oauth2.OAuth2`、`fastapi.security.base.SecurityBase`を継承しているからです。
///
-/// check | 確認
+/// tip | 豆知識
依存関係システムがこのように設計されているおかげで、 `User` モデルを返却する別の依存関係（別の「dependables」）を持つことができます。
</div>
-/// info | 情報
+/// note | 備考
RSAやECDSAのようなデジタル署名アルゴリズムを使用する予定がある場合は、cryptographyライブラリの依存関係`pyjwt[crypto]`をインストールしてください。
Username: `johndoe`
Password: `secret`
-/// check | 確認
+/// tip | 豆知識
コードのどこにも平文のパスワード"`secret`"はなく、ハッシュ化されたものしかないことを確認してください。
- `instagram_basic` は Facebook / Instagram で使われます。
- `https://www.googleapis.com/auth/drive` は Google で使われます。
-/// info | 情報
+/// note | 備考
OAuth2 における「スコープ」は、要求される特定の権限を表す単なる文字列です。
- オプションの `client_id`（この例では不要）
- オプションの `client_secret`（この例では不要）
-/// info | 情報
+/// note | 備考
`OAuth2PasswordRequestForm` は、`OAuth2PasswordBearer` のように **FastAPI** にとって特別なクラスではありません。
)
```
-/// info | 情報
+/// note | 備考
`**user_dict` のより完全な解説は、[**追加モデル**のドキュメント](../extra-models.md#about-user-in-dict)を参照してください。
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info | 情報
+/// note | 備考
ここで返している値が `Bearer` の追加ヘッダー `WWW-Authenticate` も仕様の一部です。
これは[JSON Lines のストリーミング](stream-json-lines.md)に似ていますが、`text/event-stream` フォーマットを使用します。これはブラウザがネイティブに [`EventSource` API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) でサポートしています。
-/// info | 情報
+/// note
FastAPI 0.135.0 で追加されました。
SSE は、AI チャットのストリーミング、ライブ通知、ログやオブザビリティなど、サーバーがクライアントへ更新をプッシュする用途で一般的に使われます。
-/// tip | 豆知識
+/// tip
バイナリデータ（例: 動画や音声）をストリーミングしたい場合は、上級ガイド [データのストリーミング](../advanced/stream-data.md) を参照してください。
{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[1:25] hl[10:12,23] *}
-/// tip | 豆知識
+/// tip
Pydantic が**Rust** 側でシリアライズを行うため、戻り値の型を宣言しない場合に比べて大幅に**高性能**になります。
## 生データ { #raw-data }
-JSON エンコードせずにデータを送る必要がある場合は、`data` の代わりに `raw_data` を使用します。
+JSON エンコードせずにデータを送る必要がある場合は、`raw_data` を使用します。
-これは、整形済みテキスト、ログ行、または `[DONE]` のような特別な <dfn title="特別な条件や状態を示すために用いられる値">"センチネル"</dfn> 値を送るのに有用です。
+これは、整形済みテキスト、ログ行、または <dfn title="特別な条件や状態を示すために用いられる値">「センチネル」</dfn> といった特別な値（例: `[DONE]`）を送るのに有用です。
{* ../../docs_src/server_sent_events/tutorial003_py310.py hl[17] *}
-/// note | 備考
+/// note
`data` と `raw_data` は相互排他的です。各 `ServerSentEvent` ではどちらか一方しか設定できません。
データのシーケンスを**「ストリーム」**で送りたい場合、**JSON Lines** を使って実現できます。
-/// info | 情報
+/// note | 備考
FastAPI 0.134.0 で追加されました。
これは JSON 配列（Python の list に相当）にとてもよく似ていますが、`[]` で囲まず、アイテム間の `,` もありません。その代わりに、**1 行に 1 つの JSON オブジェクト**で、改行文字で区切られます。
-/// info | 情報
+/// note | 備考
重要な点は、クライアントが前の行を消費している間に、アプリ側は次の行を順次生成して送れることです。
## `TestClient` を使用 { #using-testclient }
-/// info
+/// note | 備考
`TestClient` を使用するには、まず [`httpx`](https://www.python-httpx.org) をインストールします。
{* ../../docs_src/app_testing/tutorial001_py310.py hl[2,12,15:18] *}
-/// tip
+/// tip | 豆知識
テスト関数は `async def` ではなく、通常の `def` であることに注意してください。
///
-/// tip
+/// tip | 豆知識
FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md) を参照してください。
(`httpx` または `TestClient` を使用して) バックエンドにデータを渡す方法の詳細は、[HTTPXのドキュメント](https://www.python-httpx.org)を確認してください。
-/// info
+/// note | 備考
`TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。
projects / thirdparty / fastapi / fastapi.git / commitdiff
