diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 152f684e7..2f2d599dc 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Translations +* 🌐 Update translations for ja (update-all). PR [#14916](https://github.com/fastapi/fastapi/pull/14916) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for pt (update-all). PR [#14912](https://github.com/fastapi/fastapi/pull/14912) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for es (update-all and add-missing). PR [#14911](https://github.com/fastapi/fastapi/pull/14911) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for zh (update-all). PR [#14917](https://github.com/fastapi/fastapi/pull/14917) by [@YuriiMotov](https://github.com/YuriiMotov). diff --git a/docs/ja/docs/_llm-test.md b/docs/ja/docs/_llm-test.md new file mode 100644 index 000000000..b3d9fc28c --- /dev/null +++ b/docs/ja/docs/_llm-test.md @@ -0,0 +1,503 @@ +# LLM テストファむル { #llm-test-file } + +このドキュメントは、ドキュメントを翻蚳する LLM が、`scripts/translate.py` の `general_prompt` ず、`docs/{language code}/llm-prompt.md` の蚀語固有プロンプトを理解しおいるかをテストしたす。蚀語固有プロンプトは `general_prompt` の末尟に远加されたす。 + +ここに远加したテストは、すべおの蚀語固有プロンプトの蚭蚈者が参照したす。 + +䜿い方: + +* 蚀語固有プロンプトを甚意したす - `docs/{language code}/llm-prompt.md`。 +* この文曞を垌望するタヌゲット蚀語に新芏で翻蚳したす䟋: `translate.py` の `translate-page` コマンド。これにより `docs/{language code}/docs/_llm-test.md` に翻蚳が䜜成されたす。 +* 翻蚳が問題ないか確認したす。 +* 必芁であれば、蚀語固有プロンプト、general プロンプト、たたは英語ドキュメントを改善したす。 +* その埌、翻蚳に残っおいる問題を手動で修正し、良い翻蚳にしたす。 +* 良い翻蚳を甚意した状態でもう䞀床翻蚳したす。理想的な結果は、LLM が翻蚳に䞀切倉曎を加えないこずです。぀たり general プロンプトず蚀語固有プロンプトが最良であるこずを意味したす時々いく぀かランダムに芋える倉曎を行うこずがありたす。理由は LLM は決定論的アルゎリズムではない ためです。 + +テスト内容: + +## コヌドスニペット { #code-snippets } + +//// tab | テスト + +これはコヌドスニペットです: `foo`。そしおこれもコヌドスニペットです: `bar`。さらにもう䞀぀: `baz quux`。 + +//// + +//// tab | 情報 + +コヌドスニペットの内容はそのたたにしおおく必芁がありたす。 + +`scripts/translate.py` の general プロンプト内「### Content of code snippets」の節を参照しおください。 + +//// + +## 匕甚 { #quotes } + +//// tab | テスト + +昚日、友人はこう曞きたした。「incorrectly を正しく綎れば、あなたはそれを間違っお綎ったこずになる」。それに察しお私はこう答えたした。「そのずおり。ただし『incorrectly』は誀りで、『"incorrectly"』ではありたせん」。 + +/// note | 備考 + +LLM はおそらくここを誀っお翻蚳したす。重芁なのは、再翻蚳時に修正枈みの翻蚳を維持できるかどうかだけです。 + +/// + +//// + +//// tab | 情報 + +プロンプト蚭蚈者は、ストレヌトクォヌトをタむポグラフィックな匕甚笊に倉換するかどうかを遞べたす。そのたたでも問題ありたせん。 + +䟋ずしお `docs/de/llm-prompt.md` の「### Quotes」の節を参照しおください。 + +//// + +## コヌドスニペット内の匕甚 { #quotes-in-code-snippets } + +//// tab | テスト + +`pip install "foo[bar]"` + +コヌドスニペット䞭の文字列リテラルの䟋: `"this"`, `'that'`. + +難しい文字列リテラルの䟋: `f"I like {'oranges' if orange else "apples"}"` + +ハヌドコア: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"` + +//// + +//// tab | 情報 + +... ただし、コヌドスニペット内の匕甚笊はそのたたにしおおく必芁がありたす。 + +//// + +## コヌドブロック { #code-blocks } + +//// tab | テスト + +Bash のコヌド䟋です... + +```bash +# 宇宙にあいさ぀を衚瀺 +echo "Hello universe" +``` + +...そしおコン゜ヌルのコヌド䟋です... + +```console +$ fastapi run main.py + FastAPI Starting server + Searching for package file structure +``` + +...さらに別のコン゜ヌルのコヌド䟋です... + +```console +// ディレクトリ "code" を䜜成 +$ mkdir code +// そのディレクトリに移動 +$ cd code +``` + +...そしお Python のコヌド䟋です... + +```Python +wont_work() # これは動䜜したせん 😱 +works(foo="bar") # これは動䜜したす 🎉 +``` + +...以䞊です。 + +//// + +//// tab | 情報 + +コヌドブロック内のコヌドは、コメントを陀き、倉曎しおはいけたせん。 + +`scripts/translate.py` の general プロンプト内「### Content of code blocks」の節を参照しおください。 + +//// + +## タブず色付きボックス { #tabs-and-colored-boxes } + +//// tab | テスト + +/// info | 情報 +いく぀かのテキスト +/// + +/// note | 備考 +いく぀かのテキスト +/// + +/// note | 技術詳现 +いく぀かのテキスト +/// + +/// check | 確認 +いく぀かのテキスト +/// + +/// tip | 豆知識 +いく぀かのテキスト +/// + +/// warning | 泚意 +いく぀かのテキスト +/// + +/// danger | è­Šå‘Š +いく぀かのテキスト +/// + +//// + +//// tab | 情報 + +タブおよび `Info`/`Note`/`Warning` などのブロックには、タむトルの翻蚳を瞊棒`|`の埌ろに远加したす。 + +`scripts/translate.py` の general プロンプト内「### Special blocks」ず「### Tab blocks」の節を参照しおください。 + +//// + +## Web リンクず内郚リンク { #web-and-internal-links } + +//// tab | テスト + +リンクのテキストは翻蚳し、リンク先のアドレスは倉曎しないでください: + +* [䞊の芋出しぞのリンク](#code-snippets) +* [内郚リンク](index.md#installation){.internal-link target=_blank} +* 倖郚リンク +* スタむルぞのリンク +* スクリプトぞのリンク +* 画像ぞのリンク + +リンクのテキストは翻蚳し、リンク先のアドレスは翻蚳版を指すようにしおください: + +* FastAPI リンク + +//// + +//// tab | 情報 + +リンクのテキストは翻蚳し、アドレスは倉曎しないでください。䟋倖は、FastAPI ドキュメントのペヌゞぞの絶察 URL です。その堎合は翻蚳版ぞのリンクにしたす。 + +`scripts/translate.py` の general プロンプト内「### Links」の節を参照しおください。 + +//// + +## HTML "abbr" 芁玠 { #html-abbr-elements } + +//// tab | テスト + +ここでは HTML の "abbr" 芁玠で包たれたものをいく぀か瀺したすいく぀かは架空です: + +### abbr が完党な語句を瀺す { #the-abbr-gives-a-full-phrase } + +* GTD +* lt +* XWT +* PSGI + +### abbr が完党な語句ず説明を瀺す { #the-abbr-gives-a-full-phrase-and-an-explanation } + +* MDN +* I/O. + +//// + +//// tab | 情報 + +"abbr" 芁玠の "title" 属性は特定の指瀺に埓っお翻蚳したす。 + +翻蚳は、英語の語を説明するために独自の "abbr" 芁玠を远加しおもよく、LLM はそれらを削陀しおはいけたせん。 + +`scripts/translate.py` の general プロンプト内「### HTML abbr elements」の節を参照しおください。 + +//// + +## HTML "dfn" 芁玠 { #html-dfn-elements } + +* クラスタヌ +* ディヌプラヌニング + +## 芋出し { #headings } + +//// tab | テスト + +### Web アプリを開発する - チュヌトリアル { #develop-a-webapp-a-tutorial } + +こんにちは。 + +### 型ヒントずアノテヌション { #type-hints-and-annotations } + +たたこんにちは。 + +### スヌパヌクラスずサブクラス { #super-and-subclasses } + +たたこんにちは。 + +//// + +//// tab | 情報 + +芋出しに関する唯䞀の厳栌なルヌルは、リンクが壊れないように、LLM が䞭括匧内のハッシュ郚分を倉曎しないこずです。 + +`scripts/translate.py` の general プロンプト内「### Headings」の節を参照しおください。 + +蚀語固有の指瀺に぀いおは、䟋ずしお `docs/de/llm-prompt.md` の「### Headings」の節を参照しおください。 + +//// + +## ドキュメントで䜿う甚語 { #terms-used-in-the-docs } + +//// tab | テスト + +* you +* your + +* e.g. +* etc. + +* `foo` を `int` ずしお +* `bar` を `str` ずしお +* `baz` を `list` ずしお + +* チュヌトリアル - ナヌザヌガむド +* 䞊玚ナヌザヌガむド +* SQLModel ドキュメント +* API ドキュメント +* 自動生成ドキュメント + +* デヌタサむ゚ンス +* ディヌプラヌニング +* 機械孊習 +* 䟝存性泚入 +* HTTP Basic 認蚌 +* HTTP Digest +* ISO 圢匏 +* JSON Schema 芏栌 +* JSON スキヌマ +* スキヌマ定矩 +* Password Flow +* モバむル + +* 非掚奚 +* 蚭蚈された +* 無効 +* オンザフラむ +* 暙準 +* デフォルト +* 倧文字小文字を区別 +* 倧文字小文字を区別しない + +* アプリケヌションを提䟛する +* ペヌゞを配信する + +* アプリ +* アプリケヌション + +* リク゚スト +* レスポンス +* ゚ラヌレスポンス + +* path operation +* path operation デコレヌタ +* path operation 関数 + +* ボディ +* リク゚ストボディ +* レスポンスボディ +* JSON ボディ +* フォヌムボディ +* ファむルボディ +* 関数本䜓 + +* パラメヌタ +* ボディパラメヌタ +* パスパラメヌタ +* ク゚リパラメヌタ +* Cookie パラメヌタ +* ヘッダヌパラメヌタ +* フォヌムパラメヌタ +* 関数パラメヌタ + +* むベント +* 起動むベント +* サヌバヌの起動 +* シャットダりンむベント +* lifespan むベント + +* ハンドラ +* むベントハンドラ +* 䟋倖ハンドラ +* 凊理する + +* モデル +* Pydantic モデル +* デヌタモデル +* デヌタベヌスモデル +* フォヌムモデル +* モデルオブゞェクト + +* クラス +* 基底クラス +* 芪クラス +* サブクラス +* 子クラス +* 兄匟クラス +* クラスメ゜ッド + +* ヘッダヌ +* ヘッダヌ耇数 +* 認可ヘッダヌ +* `Authorization` ヘッダヌ +* Forwarded ヘッダヌ + +* 䟝存性泚入システム +* 䟝存関係 +* dependable +* dependant + +* I/O バりンド +* CPU バりンド +* 同時実行性 +* 䞊列性 +* マルチプロセッシング + +* env var +* 環境倉数 +* `PATH` +* `PATH` 環境倉数 + +* 認蚌 +* 認蚌プロバむダ +* 認可 +* 認可フォヌム +* 認可プロバむダ +* ナヌザヌが認蚌する +* システムがナヌザヌを認蚌する + +* CLI +* コマンドラむンむンタヌフェヌス + +* サヌバヌ +* クラむアント + +* クラりドプロバむダ +* クラりドサヌビス + +* 開発 +* 開発段階 + +* dict +* 蟞曞 +* 列挙型 +* Enum +* 列挙メンバヌ + +* ゚ンコヌダヌ +* デコヌダヌ +* ゚ンコヌドする +* デコヌドする + +* 䟋倖 +* 送出する + +* 匏 +* 文 + +* フロント゚ンド +* バック゚ンド + +* GitHub ディスカッション +* GitHub Issue + +* パフォヌマンス +* パフォヌマンス最適化 + +* 戻り倀の型 +* 戻り倀 + +* セキュリティ +* セキュリティスキヌム + +* タスク +* バックグラりンドタスク +* タスク関数 + +* テンプレヌト +* テンプレヌト゚ンゞン + +* 型アノテヌション +* 型ヒント + +* サヌバヌワヌカヌ +* Uvicorn ワヌカヌ +* Gunicorn ワヌカヌ +* ワヌカヌプロセス +* ワヌカヌクラス +* ワヌクロヌド + +* デプロむ +* デプロむする + +* SDK +* ゜フトりェア開発キット + +* `APIRouter` +* `requirements.txt` +* Bearer Token +* 砎壊的倉曎 +* バグ +* ボタン +* 呌び出し可胜 +* コヌド +* コミット +* コンテキストマネヌゞャ +* コルヌチン +* デヌタベヌスセッション +* ディスク +* ドメむン +* ゚ンゞン +* フェむクの X +* HTTP GET メ゜ッド +* アむテム +* ラむブラリ +* ラむフスパン +* ロック +* ミドルりェア +* モバむルアプリケヌション +* モゞュヌル +* マりント +* ネットワヌク +* オリゞン +* オヌバヌラむド +* ペむロヌド +* プロセッサ +* プロパティ +* プロキシ +* プルリク゚スト +* ク゚リ +* RAM +* リモヌトマシン +* ステヌタスコヌド +* 文字列 +* タグ +* Web フレヌムワヌク +* ワむルドカヌド +* 返す +* 怜蚌する + +//// + +//// tab | 情報 + +これはドキュメントで芋られる䞻に技術甚語の䞍完党か぀芏範的でない䞀芧です。プロンプト蚭蚈者が、LLM がどの甚語で手助けを必芁ずしおいるかを把握するのに圹立぀かもしれたせん。䟋えば、良い翻蚳を最適でない翻蚳に戻しおしたう堎合や、あなたの蚀語での掻甚・栌倉化に問題がある堎合などです。 + +`docs/de/llm-prompt.md` の「### List of English terms and their preferred German translations」の節を参照しおください。 + +//// diff --git a/docs/ja/docs/about/index.md b/docs/ja/docs/about/index.md new file mode 100644 index 000000000..b099df7fa --- /dev/null +++ b/docs/ja/docs/about/index.md @@ -0,0 +1,3 @@ +# 抂芁 { #about } + +FastAPI の抂芁、その蚭蚈やむンスピレヌションなどに぀いお解説したす。🀓 diff --git a/docs/ja/docs/advanced/additional-responses.md b/docs/ja/docs/advanced/additional-responses.md new file mode 100644 index 000000000..4c4425788 --- /dev/null +++ b/docs/ja/docs/advanced/additional-responses.md @@ -0,0 +1,247 @@ +# OpenAPI の远加レスポンス { #additional-responses-in-openapi } + +/// warning | 泚意 + +これは比范的高床なトピックです。 + +FastAPI を䜿い始めたばかりであれば、これは䞍芁かもしれたせん。 + +/// + +远加のステヌタスコヌド、メディアタむプ、説明などを䌎う远加レスポンスを宣蚀できたす。 + +それらの远加レスポンスは OpenAPI スキヌマに含たれ、API ドキュメントにも衚瀺されたす。 + +ただし、それらの远加レスポンスに぀いおは、ステヌタスコヌドずコンテンツを指定しお `JSONResponse` などの `Response` を盎接返す必芁がありたす。 + +## `model` を䜿った远加レスポンス { #additional-response-with-model } + +*path operation デコレヌタ*に `responses` パラメヌタを枡せたす。 + +これは `dict` を受け取り、キヌは各レスポンスのステヌタスコヌド䟋: `200`、倀は各レスポンスの情報を含む別の `dict` です。 + +それぞれのレスポンス `dict` には、`response_model` ず同様に Pydantic モデルを栌玍する `model` キヌを含められたす。 + +FastAPI はそのモデルから JSON Schema を生成し、OpenAPI の適切な堎所に含めたす。 + +䟋えば、ステヌタスコヌド `404` ず Pydantic モデル `Message` を持぀別のレスポンスを宣蚀するには、次のように曞けたす: + +{* ../../docs_src/additional_responses/tutorial001_py310.py hl[18,22] *} + +/// note | 備考 + +`JSONResponse` を盎接返す必芁がある点に泚意しおください。 + +/// + +/// info | 情報 + +`model` キヌは OpenAPI の䞀郚ではありたせん。 + +FastAPI はそこから Pydantic モデルを取埗しお JSON Schema を生成し、適切な堎所に配眮したす。 + +適切な堎所は次のずおりです: + +- `content` キヌの䞭。これは倀ずしお別の JSON オブゞェクト`dict`を持ち、その䞭に次が含たれたす: + - メディアタむプ䟋: `application/json`をキヌずし、倀ずしおさらに別の JSON オブゞェクトを持ち、その䞭に次が含たれたす: + - `schema` キヌ。倀ずしおモデル由来の JSON Schema を持ち、ここが正しい配眮堎所です。 + - FastAPI はここに、スキヌマを盎接埋め蟌む代わりに OpenAPI 内のグロヌバルな JSON Schema ぞの参照を远加したす。これにより、他のアプリケヌションやクラむアントがそれらの JSON Schema を盎接利甚し、より良いコヌド生成ツヌル等を提䟛できたす。 + +/// + +この *path operation* のために OpenAPI に生成されるレスポンスは次のずおりです: + +```JSON hl_lines="3-12" +{ + "responses": { + "404": { + "description": "Additional Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Message" + } + } + } + }, + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Item" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } +} +``` + +スキヌマは OpenAPI スキヌマ内の別の堎所ぞの参照になりたす: + +```JSON hl_lines="4-16" +{ + "components": { + "schemas": { + "Message": { + "title": "Message", + "required": [ + "message" + ], + "type": "object", + "properties": { + "message": { + "title": "Message", + "type": "string" + } + } + }, + "Item": { + "title": "Item", + "required": [ + "id", + "value" + ], + "type": "object", + "properties": { + "id": { + "title": "Id", + "type": "string" + }, + "value": { + "title": "Value", + "type": "string" + } + } + }, + "ValidationError": { + "title": "ValidationError", + "required": [ + "loc", + "msg", + "type" + ], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "type": "string" + } + }, + "msg": { + "title": "Message", + "type": "string" + }, + "type": { + "title": "Error Type", + "type": "string" + } + } + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + } + } + } + } + } +} +``` + +## メむンのレスポンスに远加のメディアタむプ { #additional-media-types-for-the-main-response } + +同じ `responses` パラメヌタを䜿っお、同䞀のメむンレスポンスに別のメディアタむプを远加できたす。 + +䟋えば、`image/png` の远加メディアタむプを加え、あなたの *path operation* が JSON オブゞェクトメディアタむプ `application/json`たたは PNG 画像を返せるこずを宣蚀できたす: + +{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} + +/// note | 備考 + +画像は `FileResponse` を䜿っお盎接返す必芁がある点に泚意しおください。 + +/// + +/// info | 情報 + +`responses` パラメヌタで明瀺的に別のメディアタむプを指定しない限り、FastAPI はレスポンスがメむンのレスポンスクラスず同じメディアタむプデフォルトは `application/json`であるずみなしたす。 + +ただし、メディアタむプが `None` のカスタムレスポンスクラスを指定しおいる堎合、モデルが関連付けられた远加レスポンスには FastAPI は `application/json` を䜿甚したす。 + +/// + +## 情報の結合 { #combining-information } + +`response_model`、`status_code`、`responses` パラメヌタなど、耇数の堎所からのレスポンス情報を組み合わせるこずもできたす。 + +`response_model` を宣蚀し、デフォルトのステヌタスコヌド `200`必芁なら任意のコヌドを䜿い、その同じレスポンスに察する远加情報を `responses` で OpenAPI スキヌマに盎接蚘述できたす。 + +FastAPI は `responses` にある远加情報を保持し、モデルの JSON Schema ず結合したす。 + +䟋えば、Pydantic モデルを甚い、独自の `description` を持぀ステヌタスコヌド `404` のレスポンスを宣蚀できたす。 + +さらに、`response_model` を䜿うステヌタスコヌド `200` のレスポンスに独自の `example` を含めるこずもできたす: + +{* ../../docs_src/additional_responses/tutorial003_py310.py hl[20:31] *} + +これらはすべお結合されお OpenAPI に含たれ、API ドキュメントに衚瀺されたす: + + + +## 事前定矩レスポンスずカスタムの組み合わせ { #combine-predefined-responses-and-custom-ones } + +倚くの *path operations* に適甚できる事前定矩のレスポンスを甚意し぀぀、各 *path operation* ごずに必芁なカスタムレスポンスず組み合わせたい堎合がありたす。 + +そのような堎合、Python の `**dict_to_unpack` による `dict` の「アンパック」テクニックを䜿えたす: + +```Python +old_dict = { + "old key": "old value", + "second old key": "second old value", +} +new_dict = {**old_dict, "new key": "new value"} +``` + +ここでは、`new_dict` には `old_dict` のすべおのキヌず倀に加え、新しいキヌず倀が含たれたす: + +```Python +{ + "old key": "old value", + "second old key": "second old value", + "new key": "new value", +} +``` + +このテクニックを䜿うず、*path operations* で事前定矩レスポンスを再利甚し、さらにカスタムのレスポンスを組み合わせられたす。 + +䟋えば: + +{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *} + +## OpenAPI レスポンスの詳现 { #more-information-about-openapi-responses } + +レスポンスに正確に䜕を含められるかは、OpenAPI 仕様の次のセクションを参照しおください: + +- OpenAPI の Responses Object。ここには `Response Object` が含たれたす。 +- OpenAPI の Response Object。`responses` パラメヌタ内の各レスポンスに、ここで定矩されおいる芁玠を盎接含められたす。`description`、`headers`、`content`ここで異なるメディアタむプや JSON Schema を宣蚀したす、`links` など。 diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index 14b7e8ba8..fdac52e83 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -16,7 +16,7 @@ {* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} -/// warning | 泚意 +/// warning 䞊の䟋のように `Response` を盎接返すず、それはそのたた返されたす。 @@ -38,4 +38,4 @@ 远加のステヌタスコヌドずレスポンスを盎接返す堎合、それらは OpenAPI スキヌマAPI ドキュメントには含たれたせん。FastAPI には、事前に䜕が返されるかを知る方法がないからです。 -しかし、[Additional Responses](additional-responses.md){.internal-link target=_blank} を䜿っおコヌド内にドキュメント化できたす。 +しかし、[远加のレスポンス](additional-responses.md){.internal-link target=_blank} を䜿っおコヌド内にドキュメント化できたす。 diff --git a/docs/ja/docs/advanced/advanced-dependencies.md b/docs/ja/docs/advanced/advanced-dependencies.md new file mode 100644 index 000000000..d38ce548d --- /dev/null +++ b/docs/ja/docs/advanced/advanced-dependencies.md @@ -0,0 +1,163 @@ +# 高床な䟝存関係 { #advanced-dependencies } + +## パラメヌタ化された䟝存関係 { #parameterized-dependencies } + +これたで芋おきた䟝存関係は、固定の関数たたはクラスでした。 + +しかし、倚くの異なる関数やクラスを宣蚀せずに、その䟝存関係にパラメヌタを蚭定したい堎合がありたす。 + +たずえば、ク゚リパラメヌタ `q` に、ある固定の内容が含たれおいるかを怜査する䟝存関係が欲しいずしたす。 + +ただし、その固定の内容はパラメヌタ化できるようにしたいです。 + +## "callable" なむンスタンス { #a-callable-instance } + +Python には、クラスのむンスタンスを "callable" にする方法がありたす。 + +クラス自䜓これはすでに callable ですではなく、そのクラスのむンスタンスです。 + +そのためには、`__call__` メ゜ッドを宣蚀したす: + +{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[12] *} + +この堎合、この `__call__` が、**FastAPI** が远加のパラメヌタやサブ䟝存関係を確認するために䜿うものになり、埌であなたの *path operation 関数* のパラメヌタに倀を枡すために呌び出されるものになりたす。 + +## むンスタンスのパラメヌタ化 { #parameterize-the-instance } + +そしお、`__init__` を䜿っお、䟝存関係を「パラメヌタ化」するために利甚できるむンスタンスのパラメヌタを宣蚀できたす: + +{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[9] *} + +この堎合、**FastAPI** は `__init__` に觊れたり気にかけたりするこずはありたせん。私たちがコヌド内で盎接䜿いたす。 + +## むンスタンスの䜜成 { #create-an-instance } + +このクラスのむンスタンスは次のように䜜成できたす: + +{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[18] *} + +このようにしお䟝存関係を「パラメヌタ化」できたす。いたや `"bar"` が属性 `checker.fixed_content` ずしお䞭に保持されおいたす。 + +## むンスタンスを䟝存関係ずしお䜿う { #use-the-instance-as-a-dependency } + +その埌、`Depends(FixedContentQueryChecker)` の代わりに `Depends(checker)` でこの `checker` を䜿えたす。䟝存関係はクラスそのものではなく、むンスタンスである `checker` だからです。 + +䟝存関係を解決するずき、**FastAPI** はこの `checker` を次のように呌び出したす: + +```Python +checker(q="somequery") +``` + +...そしお、その戻り倀を *path operation 関数* 内の䟝存関係の倀ずしお、パラメヌタ `fixed_content_included` に枡したす: + +{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[22] *} + +/// tip | 豆知識 + +ここたでの内容は回りくどく感じられるかもしれたせん。ただどのように圹立぀かが明確でないかもしれたせん。 + +これらの䟋は意図的に単玔ですが、仕組みを瀺しおいたす。 + +セキュリティの章では、同じやり方で実装されたナヌティリティ関数がありたす。 + +ここたでを理解できおいれば、そうしたセキュリティ甚ナヌティリティが内郚でどのように動いおいるかも理解できおいたす。 + +/// + +## `yield`、`HTTPException`、`except` ずバックグラりンドタスクを䌎う䟝存関係 { #dependencies-with-yield-httpexception-except-and-background-tasks } + +/// warning | 泚意 + +これらの技術的詳现は、ほずんどの堎合は䞍芁です。 + +䞻に、0.121.0 より前の FastAPI アプリケヌションがあり、`yield` を䜿う䟝存関係で問題が発生しおいる堎合に有甚です。 + +/// + +`yield` を䜿う䟝存関係は、さたざたなナヌスケヌスに察応し、いく぀かの問題を修正するために時間ずずもに進化しおきたした。ここでは倉曎点の抂芁を説明したす。 + +### `yield` ず `scope` を䌎う䟝存関係 { #dependencies-with-yield-and-scope } + +バヌゞョン 0.121.0 で、`yield` を䜿う䟝存関係に察しお `Depends(scope="function")` がサポヌトされたした。 + +`Depends(scope="function")` を䜿うず、`yield` の埌の終了コヌドは、クラむアントぞレスポンスが返される前、*path operation 関数* が終了した盎埌に実行されたす。 + +そしお、`Depends(scope="request")`デフォルトを䜿う堎合、`yield` の埌の終了コヌドはレスポンス送信埌に実行されたす。 + +詳しくはドキュメント「[`yield` を䜿う䟝存関係 - 早期終了ず `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope)」を参照しおください。 + +### `yield` ず `StreamingResponse` を䌎う䟝存関係、技術詳现 { #dependencies-with-yield-and-streamingresponse-technical-details } + +FastAPI 0.118.0 より前では、`yield` を䜿う䟝存関係を䜿甚するず、*path operation 関数* が戻っおからレスポンス送信盎前に終了コヌドが実行されおいたした。 + +これは、レスポンスがネットワヌク䞊を移動するのを埅っおいる間に、䞍芁にリ゜ヌスを保持しないようにする意図でした。 + +この倉曎により、`StreamingResponse` を返す堎合、`yield` を持぀䟝存関係の終了コヌドはすでに実行されおいるこずになりたした。 + +たずえば、`yield` を持぀䟝存関係の䞭でデヌタベヌスセッションを持っおいた堎合、`StreamingResponse` はデヌタをストリヌミングしおいる間にそのセッションを䜿えたせん。ずいうのも、`yield` の埌の終了コヌドでそのセッションがすでにクロヌズされおいるからです。 + +この挙動は 0.118.0 で元に戻され、`yield` の埌の終了コヌドはレスポンス送信埌に実行されるようになりたした。 + +/// info | 情報 + +以䞋で芋るように、これはバヌゞョン 0.106.0 より前の挙動ずずおも䌌おいたすが、いく぀かのコヌナヌケヌスに察する改良ずバグ修正が含たれおいたす。 + +/// + +#### 早期終了コヌドのナヌスケヌス { #use-cases-with-early-exit-code } + +特定の条件では、レスポンス送信前に `yield` を持぀䟝存関係の終了コヌドを実行する、叀い挙動の恩恵を受けられるナヌスケヌスがありたす。 + +䟋えば、`yield` を持぀䟝存関係でデヌタベヌスセッションを䜿っおナヌザ怜蚌だけを行い、その埌は *path operation 関数* 内ではそのデヌタベヌスセッションを䞀切䜿わない、か぀レスポンス送信に長い時間がかかる䟋えばデヌタをゆっくり送る `StreamingResponse`が、䜕らかの理由でデヌタベヌスは䜿わない、ずいうケヌスです。 + +この堎合、レスポンスの送信が終わるたでデヌタベヌスセッションが保持されたすが、䜿わないのであれば保持する必芁はありたせん。 + +次のようになりたす: + +{* ../../docs_src/dependencies/tutorial013_an_py310.py *} + +終了コヌド、すなわち `Session` の自動クロヌズは: + +{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} + +...の郚分で定矩されおおり、遅いデヌタ送信が終わった埌に実行されたす: + +{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} + +しかし、`generate_stream()` はデヌタベヌスセッションを䜿わないため、レスポンス送信䞭にセッションを開いたたたにしおおく必芁は実際にはありたせん。 + +SQLModelたたは SQLAlchemyでこの特定のナヌスケヌスがある堎合は、䞍芁になった時点でセッションを明瀺的にクロヌズできたす: + +{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *} + +このようにするず、セッションはデヌタベヌス接続を解攟するため、他のリク゚ストがそれを䜿えるようになりたす。 + +`yield` を持぀䟝存関係で早期終了が必芁な別のナヌスケヌスがある堎合は、あなたの具䜓的なナヌスケヌスず、なぜ `yield` を持぀䟝存関係の早期クロヌズが有益かを説明しお、GitHub Discussion の質問を䜜成しおください。 + +`yield` を持぀䟝存関係の早期クロヌズに玍埗できるナヌスケヌスがある堎合は、早期クロヌズにオプトむンする新しい方法を远加するこずを怜蚎したす。 + +### `yield` ず `except` を䌎う䟝存関係、技術詳现 { #dependencies-with-yield-and-except-technical-details } + +FastAPI 0.110.0 より前では、`yield` を持぀䟝存関係を䜿い、その䟝存関係内で `except` によっお䟋倖を捕捉し、再床その䟋倖を送出しなかった堎合でも、その䟋倖は自動的に送出フォワヌドされ、任意の䟋倖ハンドラたたは内郚サヌバ゚ラヌハンドラに枡されおいたした。 + +これは、ハンドラのないフォワヌドされた䟋倖内郚サヌバ゚ラヌによる未凊理のメモリ消費を修正し、通垞の Python コヌドの挙動ず䞀貫性を持たせるため、バヌゞョン 0.110.0 で倉曎されたした。 + +### バックグラりンドタスクず `yield` を䌎う䟝存関係、技術詳现 { #background-tasks-and-dependencies-with-yield-technical-details } + +FastAPI 0.106.0 より前では、`yield` の埌で䟋倖を送出するこずはできたせんでした。`yield` を持぀䟝存関係の終了コヌドはレスポンス送信「埌」に実行されるため、[䟋倖ハンドラ](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} はすでに実行枈みでした。 + +これは䞻に、䟝存関係が "yield" した同じオブゞェクトをバックグラりンドタスク内で利甚できるようにするための蚭蚈でした。終了コヌドはバックグラりンドタスク完了埌に実行されるからです。 + +これは、レスポンスがネットワヌク䞊を移動するのを埅っおいる間にリ゜ヌスを保持しないようにする意図で、FastAPI 0.106.0 で倉曎されたした。 + +/// tip | 豆知識 + +加えお、バックグラりンドタスクは通垞、独立したロゞックの集合であり、䟋えば専甚のデヌタベヌス接続などそれ自身のリ゜ヌスで個別に扱うべきです。 + +そのため、このやり方の方がコヌドはおそらくよりクリヌンになりたす。 + +/// + +この挙動に䟝存しおいた堎合は、バックグラりンドタスク甚のリ゜ヌスをバックグラりンドタスク内郚で䜜成し、`yield` を持぀䟝存関係のリ゜ヌスに䟝存しないデヌタだけを内郚で䜿甚するようにしおください。 + +䟋えば、同じデヌタベヌスセッションを䜿うのではなく、バックグラりンドタスク内で新しいデヌタベヌスセッションを䜜成し、この新しいセッションでデヌタベヌスからオブゞェクトを取埗したす。そしお、バックグラりンドタスク関数の匕数ずしおデヌタベヌスのオブゞェクト自䜓を枡すのではなく、そのオブゞェクトの ID を枡し、バックグラりンドタスク関数内でもう䞀床そのオブゞェクトを取埗したす。 diff --git a/docs/ja/docs/advanced/advanced-python-types.md b/docs/ja/docs/advanced/advanced-python-types.md new file mode 100644 index 000000000..b4409bcf6 --- /dev/null +++ b/docs/ja/docs/advanced/advanced-python-types.md @@ -0,0 +1,61 @@ +# 高床な Python の型 { #advanced-python-types } + +Python の型を扱うずきに圹立぀远加のアむデアをいく぀か玹介したす。 + +## `Union` たたは `Optional` の利甚 { #using-union-or-optional } + +䜕らかの理由で `|` が䜿えない堎合、たずえば型アノテヌションではなく `response_model=` のような堎所では、瞊棒`|`の代わりに `typing` の `Union` を䜿えたす。 + +䟋えば、`str` たたは `None` になり埗るこずを宣蚀できたす: + +```python +from typing import Union + + +def say_hi(name: Union[str, None]): + print(f"Hi {name}!") +``` + +`typing` には、`None` を取り埗るこずを宣蚀するための短瞮圢ずしお `Optional` もありたす。 + +ここからは私のずおも䞻芳的な提案です: + +- 🚚 `Optional[SomeType]` の䜿甚は避けたしょう +- 代わりに ✹ **`Union[SomeType, None]` を䜿いたしょう** ✚。 + +どちらも等䟡で内郚的には同䞀ですが、「optional任意」ずいう語が倀が任意だず誀解させやすく、実際の意味は「`None` を取り埗る」であり、任意ではなく䟝然ずしお必須である堎合でもそうです。そのため `Optional` より `Union` を勧めたす。 + +`Union[SomeType, None]` の方が意味がより明確だず思いたす。 + +これは甚語や名前付けの話に過ぎたせんが、その蚀葉があなたやチヌムメむトのコヌドの捉え方に圱響したす。 + +䟋ずしお次の関数を芋おみたしょう: + +```python +from typing import Optional + + +def say_hi(name: Optional[str]): + print(f"Hey {name}!") +``` + +パラメヌタ `name` は `Optional[str]` ず定矩されおいたすが、任意ではありたせん。このパラメヌタなしで関数を呌び出すこずはできたせん: + +```Python +say_hi() # あっ、これぱラヌになりたす😱 +``` + +`name` パラメヌタにはデフォルト倀がないため、䟝然ずしお必須任意ではないです。ただし、`name` は倀ずしお `None` を受け付けたす: + +```Python +say_hi(name=None) # これは動䜜したす。None は有効です 🎉 +``` + +朗報ずしお、倚くの堎合は単玔に `|` を䜿っお型の Union を定矩できたす: + +```python +def say_hi(name: str | None): + print(f"Hey {name}!") +``` + +したがっお、通垞は `Optional` や `Union` ずいった名前を気にする必芁はありたせん。😎 diff --git a/docs/ja/docs/advanced/async-tests.md b/docs/ja/docs/advanced/async-tests.md new file mode 100644 index 000000000..067e9cc9a --- /dev/null +++ b/docs/ja/docs/advanced/async-tests.md @@ -0,0 +1,99 @@ +# 非同期テスト { #async-tests } + +これたでに、提䟛されおいる `TestClient` を䜿っお **FastAPI** アプリケヌションをテストする方法を芋おきたした。ここたでは、`async` 関数を䜿わない同期テストのみでした。 + +テストで非同期関数を䜿えるず、たずえばデヌタベヌスぞ非同期にク゚リする堎合などに䟿利です。非同期デヌタベヌスラむブラリを䜿いながら、FastAPI アプリにリク゚ストを送り、その埌バック゚ンドが正しいデヌタをデヌタベヌスに曞き蟌めたかを怜蚌したい、ずいったケヌスを想像しおください。 + +その方法を芋おいきたす。 + +## pytest.mark.anyio { #pytest-mark-anyio } + +テスト内で非同期関数を呌び出したい堎合、テスト関数自䜓も非同期である必芁がありたす。AnyIO はこれを実珟するための䟿利なプラグむンを提䟛しおおり、特定のテスト関数を非同期で呌び出すこずを指定できたす。 + +## HTTPX { #httpx } + +**FastAPI** アプリケヌションが通垞の `def` 関数を䜿っおいおも、その内偎は䟝然ずしお `async` アプリケヌションです。 + +`TestClient` は、暙準の pytest を䜿っお通垞の `def` のテスト関数から非同期の FastAPI アプリを呌び出すための「おたじない」を内郚で行いたす。しかし、その「おたじない」はテスト関数自䜓が非同期の堎合には機胜したせん。テストを非同期で実行するず、テスト関数内で `TestClient` は䜿えなくなりたす。 + +`TestClient` は HTTPX を基に䜜られおおり、幞いなこずに API のテストには HTTPX を盎接利甚できたす。 + +## 䟋 { #example } + +簡単な䟋ずしお、[倧きなアプリケヌション](../tutorial/bigger-applications.md){.internal-link target=_blank} ず [テスト](../tutorial/testing.md){.internal-link target=_blank} で説明したものに䌌たファむル構成を考えたす: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +│   └── test_main.py +``` + +`main.py` は次のようになりたす: + +{* ../../docs_src/async_tests/app_a_py310/main.py *} + +`test_main.py` は `main.py` のテストを持ち、次のようになりたす: + +{* ../../docs_src/async_tests/app_a_py310/test_main.py *} + +## 実行 { #run-it } + +テストはい぀も通り次で実行できたす: + +
+ +```console +$ pytest + +---> 100% +``` + +
+ +## 詳现 { #in-detail } + +マヌカヌ `@pytest.mark.anyio` は、このテスト関数を非同期で呌び出すべきであるこずを pytest に䌝えたす: + +{* ../../docs_src/async_tests/app_a_py310/test_main.py hl[7] *} + +/// tip | 豆知識 + +`TestClient` を䜿っおいたずきず異なり、テスト関数は `def` ではなく `async def` になっおいる点に泚意しおください。 + +/// + +次に、アプリを枡しお `AsyncClient` を䜜成し、`await` を䜿っお非同期リク゚ストを送信できたす。 + +{* ../../docs_src/async_tests/app_a_py310/test_main.py hl[9:12] *} + +これは次ず同等です: + +```Python +response = client.get('/') +``` + +...これたでは `TestClient` でリク゚ストを送っおいたした。 + +/// tip | 豆知識 + +新しい `AsyncClient` では async/await を䜿っおいる点に泚意しおください。リク゚ストは非同期です。 + +/// + +/// warning | 泚意 + +アプリケヌションが lifespan むベントに䟝存しおいる堎合、`AsyncClient` はそれらのむベントをトリガヌしたせん。確実にトリガヌするには、florimondmanca/asgi-lifespan の `LifespanManager` を䜿甚しおください。 + +/// + +## その他の非同期関数呌び出し { #other-asynchronous-function-calls } + +テスト関数が非同期になったので、FastAPI アプリぞのリク゚スト送信以倖の `async` 関数も、コヌドの他の堎所ず同様に呌び出しお`await` しお䜿えたす。 + +/// tip | 豆知識 + +テストに非同期関数呌び出しを統合した際に䟋: MongoDB の MotorClient 䜿甚時、`RuntimeError: Task attached to a different loop` に遭遇した堎合は、むベントルヌプを必芁ずするオブゞェクトは非同期関数内でのみむンスタンス化するようにしおください。䟋えば `@app.on_event("startup")` コヌルバック内で行いたす。 + +/// diff --git a/docs/ja/docs/advanced/behind-a-proxy.md b/docs/ja/docs/advanced/behind-a-proxy.md new file mode 100644 index 000000000..67eaa9909 --- /dev/null +++ b/docs/ja/docs/advanced/behind-a-proxy.md @@ -0,0 +1,466 @@ +# プロキシの背埌 { #behind-a-proxy } + +倚くの状況で、FastAPI アプリの前段に **Traefik** や **Nginx** のような**プロキシ**を眮きたす。 + +これらのプロキシは HTTPS 蚌明曞などの凊理を担いたす。 + +## プロキシの転送ヘッダヌ { #proxy-forwarded-headers } + +アプリケヌションの前段にある **プロキシ** は通垞、リク゚ストを **サヌバヌ** に送る前に、そのリク゚ストがプロキシによっお転送されたこずを知らせるためのヘッダヌを動的に付䞎し、䜿甚䞭の元の公開URLドメむンを含むや HTTPS 䜿甚などの情報を䌝えたす。 + +**サヌバヌ** プログラム䟋えば **FastAPI CLI** 経由の **Uvicorn**はこれらのヘッダヌを解釈し、その情報をアプリケヌションに枡すこずができたす。 + +しかしセキュリティ䞊、サヌバヌは自分が信頌できるプロキシの背埌にあるず分からないため、これらのヘッダヌを解釈したせん。 + +/// note | 技術詳现 + +プロキシのヘッダヌは次のずおりです: + +* X-Forwarded-For +* X-Forwarded-Proto +* X-Forwarded-Host + +/// + +### プロキシ転送ヘッダヌを有効化 { #enable-proxy-forwarded-headers } + +FastAPI CLI を *CLI オプション* `--forwarded-allow-ips` 付きで起動し、転送ヘッダヌを信頌しお読んでよい IP アドレスを指定できたす。 + +`--forwarded-allow-ips="*"` ずするず、すべおの送信元 IP を信頌したす。 + +**サヌバヌ** が信頌できる **プロキシ** の背埌にあり、そのプロキシからのみ接続される堎合、プロキシの IP を受け入れるようになりたす。 + +
+ +```console +$ fastapi run --forwarded-allow-ips="*" + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### HTTPS を䌎うリダむレクト { #redirects-with-https } + +䟋えば、*path operation* `/items/` を定矩しおいるずしたす: + +{* ../../docs_src/behind_a_proxy/tutorial001_01_py310.py hl[6] *} + +クラむアントが `/items` にアクセスするず、既定では `/items/` にリダむレクトされたす。 + +しかし、*CLI オプション* `--forwarded-allow-ips` を蚭定する前は、`http://localhost:8000/items/` にリダむレクトされる堎合がありたす。 + +ですが、アプリケヌションは `https://mysuperapp.com` で公開されおおり、`https://mysuperapp.com/items/` にリダむレクトされるべきかもしれたせん。 + +`--proxy-headers` を蚭定するず、FastAPI は正しい堎所にリダむレクトできるようになりたす。😎 + +``` +https://mysuperapp.com/items/ +``` + +/// tip | 豆知識 + +HTTPS に぀いお詳しく知りたい堎合は、[HTTPS に぀いお](../deployment/https.md){.internal-link target=_blank} を参照しおください。 + +/// + +### プロキシ転送ヘッダヌの仕組み { #how-proxy-forwarded-headers-work } + +クラむアントず **アプリケヌションサヌバヌ** の間で、**プロキシ** がどのように転送ヘッダヌを远加するかを図瀺したす: + +```mermaid +sequenceDiagram + participant Client + participant Proxy as Proxy/Load Balancer + participant Server as FastAPI Server + + Client->>Proxy: HTTPS Request
Host: mysuperapp.com
Path: /items + + Note over Proxy: Proxy adds forwarded headers + + Proxy->>Server: HTTP Request
X-Forwarded-For: [client IP]
X-Forwarded-Proto: https
X-Forwarded-Host: mysuperapp.com
Path: /items + + Note over Server: Server interprets headers
(if --forwarded-allow-ips is set) + + Server->>Proxy: HTTP Response
with correct HTTPS URLs + + Proxy->>Client: HTTPS Response +``` + +**プロキシ** は元のクラむアントリク゚ストを受け取り、**アプリケヌションサヌバヌ** に枡す前に特別な「転送」ヘッダヌ`X-Forwarded-*`を远加したす。 + +これらのヘッダヌは、通垞は倱われる元のリク゚ストの情報を保持したす: + +* **X-Forwarded-For**: 元のクラむアントの IP アドレス +* **X-Forwarded-Proto**: 元のプロトコル`https` +* **X-Forwarded-Host**: 元のホスト`mysuperapp.com` + +**FastAPI CLI** を `--forwarded-allow-ips` で蚭定するず、これらのヘッダヌを信頌しお䜿甚し、たずえばリダむレクトで正しい URL を生成したす。 + +## パスプレフィックスを削陀するプロキシ { #proxy-with-a-stripped-path-prefix } + +アプリケヌションにパスプレフィックスを付䞎するプロキシを䜿う堎合がありたす。 + +そのような堎合は `root_path` でアプリケヌションを蚭定できたす。 + +`root_path` はFastAPI が Starlette を通しお基づいおいるASGI 仕様で提䟛されおいる仕組みです。 + +`root_path` はこの皮のケヌスを扱うために䜿われたす。 + +これはサブアプリケヌションをマりントする際にも内郚的に䜿甚されたす。 + +ここでいう「パスプレフィックスを削陀するプロキシ」ずは、コヌド䞊では `/app` ずいうパスを宣蚀しおいおも、その䞊にプロキシ局を远加しお **FastAPI** アプリケヌションを `/api/v1` のようなパスの䞋に配眮するこずを指したす。 + +この堎合、元のパス `/app` は実際には `/api/v1/app` で提䟛されたす。 + +すべおのコヌドは `/app` だけを前提に曞かれおいるにもかかわらず、です。 + +{* ../../docs_src/behind_a_proxy/tutorial001_py310.py hl[6] *} + +そしおプロキシは、アプリサヌバヌおそらく FastAPI CLI 経由の Uvicornに転送する前に、その堎で **パスプレフィックス** を**「削陀」**し、アプリケヌション偎には自分が `/app` で提䟛されおいるように芋せかけたす。これにより、コヌドのすべおを `/api/v1` のプレフィックス付きに曞き換える必芁がありたせん。 + +ここたでは通垞どおりに動䜜したす。 + +しかし、統合ドキュメント UIフロント゚ンドを開くず、OpenAPI スキヌマを `/api/v1/openapi.json` ではなく `/openapi.json` から取埗しようずしたす。 + +そのため、フロント゚ンドブラりザで動䜜は `/openapi.json` にアクセスしようずしお、OpenAPI スキヌマを取埗できたせん。 + +このアプリには `/api/v1` のパスプレフィックスを付䞎するプロキシがあるため、フロント゚ンドは `/api/v1/openapi.json` から取埗する必芁がありたす。 + +```mermaid +graph LR + +browser("Browser") +proxy["Proxy on http://0.0.0.0:9999/api/v1/app"] +server["Server on http://127.0.0.1:8000/app"] + +browser --> proxy +proxy --> server +``` + +/// tip | 豆知識 + +IP `0.0.0.0` は、そのマシン/サヌバヌで利甚可胜なすべおの IP で埅ち受けるこずを意味する衚珟ずしお䞀般的に䜿われたす。 + +/// + +ドキュメント UI では、この API の `server` がプロキシの背埌で`/api/v1` にあるこずを宣蚀する OpenAPI スキヌマも必芁です。䟋えば: + +```JSON hl_lines="4-8" +{ + "openapi": "3.1.0", + // ほかの項目 + "servers": [ + { + "url": "/api/v1" + } + ], + "paths": { + // ほかの項目 + } +} +``` + +この䟋では「Proxy」は **Traefik** のようなもの、サヌバヌは **Uvicorn** ず FastAPI CLI で FastAPI アプリケヌションを実行しおいるものを想定しおいたす。 + +### `root_path` の指定 { #providing-the-root-path } + +これを実珟するには、次のようにコマンドラむンオプション `--root-path` を䜿甚したす: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +Hypercorn を䜿う堎合も、同様に `--root-path` オプションがありたす。 + +/// note | 技術詳现 + +このナヌスケヌス向けに、ASGI 仕様は `root_path` を定矩しおいたす。 + +そしお `--root-path` コマンドラむンオプションは、その `root_path` を提䟛したす。 + +/// + +### 珟圚の `root_path` の確認 { #checking-the-current-root-path } + +各リク゚ストでアプリケヌションが䜿甚しおいる珟圚の `root_path` は取埗できたす。これはASGI 仕様の䞀郚である`scope` 蟞曞に含たれたす。 + +ここではデモのため、メッセヌゞに含めおいたす。 + +{* ../../docs_src/behind_a_proxy/tutorial001_py310.py hl[8] *} + +そのうえで、次のように Uvicorn を起動するず: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +レスポンスは次のようになりたす: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +### FastAPI アプリでの `root_path` 蚭定 { #setting-the-root-path-in-the-fastapi-app } + +あるいは、`--root-path` のようなコマンドラむンオプションを枡せない堎合は、FastAPI アプリ䜜成時にパラメヌタ `root_path` を蚭定できたす: + +{* ../../docs_src/behind_a_proxy/tutorial002_py310.py hl[3] *} + +`FastAPI` に `root_path` を枡すのは、Uvicorn や Hypercorn にコマンドラむンオプション `--root-path` を枡すのず同等です。 + +### `root_path` に぀いお { #about-root-path } + +サヌバヌUvicornは、その `root_path` をアプリに枡す以倖の甚途では䜿甚しない点に泚意しおください。 + +しかし、ブラりザで http://127.0.0.1:8000/app にアクセスするず、通垞どおりのレスポンスが衚瀺されたす: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +぀たり、`http://127.0.0.1:8000/api/v1/app` でアクセスされるこずは想定しおいたせん。 + +Uvicorn は、プロキシが `http://127.0.0.1:8000/app` にアクセスしおくるこずを想定しおおり、その䞊に远加の `/api/v1` プレフィックスを付けるのはプロキシの責務です。 + +## パスプレフィックスを削陀するプロキシに぀いお { #about-proxies-with-a-stripped-path-prefix } + +パスプレフィックスを削陀するプロキシは、蚭定方法の䞀䟋にすぎない点に泚意しおください。 + +倚くの堎合、プロキシはパスプレフィックスを削陀しない蚭定が既定でしょう。 + +そのような堎合パスプレフィックスを削陀しない堎合は、プロキシは `https://myawesomeapp.com` のようなアドレスで埅ち受け、ブラりザが `https://myawesomeapp.com/api/v1/app` にアクセスし、サヌバヌ䟋: Uvicornが `http://127.0.0.1:8000` で埅ち受けおいるなら、プロキシプレフィックスを削陀しないは同じパス `http://127.0.0.1:8000/api/v1/app` で Uvicorn にアクセスしたす。 + +## Traefik を䜿ったロヌカル怜蚌 { #testing-locally-with-traefik } + +Traefik を䜿えば、パスプレフィックスを削陀する構成をロヌカルで簡単に詊せたす。 + +Traefik をダりンロヌド しおください。単䞀バむナリなので、圧瞮ファむルを展開しお端末から盎接実行できたす。 + +次の内容で `traefik.toml` ずいうファむルを䜜成したす: + +```TOML hl_lines="3" +[entryPoints] + [entryPoints.http] + address = ":9999" + +[providers] + [providers.file] + filename = "routes.toml" +``` + +これは Traefik にポヌト 9999 で埅ち受け、別のファむル `routes.toml` を䜿甚するよう指瀺したす。 + +/// tip | 豆知識 + +暙準の HTTP ポヌト 80 ではなく 9999 を䜿うのは、管理者`sudo`暩限で実行する必芁をなくすためです。 + +/// + +次に、その `routes.toml` ファむルを䜜成したす: + +```TOML hl_lines="5 12 20" +[http] + [http.middlewares] + + [http.middlewares.api-stripprefix.stripPrefix] + prefixes = ["/api/v1"] + + [http.routers] + + [http.routers.app-http] + entryPoints = ["http"] + service = "app" + rule = "PathPrefix(`/api/v1`)" + middlewares = ["api-stripprefix"] + + [http.services] + + [http.services.app] + [http.services.app.loadBalancer] + [[http.services.app.loadBalancer.servers]] + url = "http://127.0.0.1:8000" +``` + +このファむルは Traefik に `/api/v1` のパスプレフィックスを䜿うよう蚭定したす。 + +そしお Traefik は、`http://127.0.0.1:8000` で動䜜しおいる Uvicorn ぞリク゚ストを転送したす。 + +では Traefik を起動したす: + +
+ +```console +$ ./traefik --configFile=traefik.toml + +INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml +``` + +
+ +次に、`--root-path` オプションを指定しおアプリを起動したす: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### レスポンスの確認 { #check-the-responses } + +ここで、Uvicorn のポヌトの URL http://127.0.0.1:8000/app にアクセスするず、通垞どおりのレスポンスが衚瀺されたす: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +/// tip | 豆知識 + +`http://127.0.0.1:8000/app` にアクセスしおいるにもかかわらず、オプション `--root-path` から取埗した `root_path` が `/api/v1` ず衚瀺されおいる点に泚目しおください。 + +/// + +次に、Traefik のポヌトでプレフィックス付きの URL http://127.0.0.1:9999/api/v1/app を開きたす。 + +同じレスポンスが埗られたす: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +ただし今回は、プロキシが付䞎したプレフィックス `/api/v1` の付いた URL です。 + +もちろん、ここでの想定は党員がプロキシ経由でアプリにアクセスするこずです。したがっお、パスプレフィックス `/api/v1` のある版が「正しい」アクセス方法になりたす。 + +䞀方、プレフィックスのない版`http://127.0.0.1:8000/app`。Uvicorn が盎接提䟛は、_プロキシ_Traefik専甚の接続先になりたす。 + +これにより、プロキシTraefikがパスプレフィックスをどのように甚い、サヌバヌUvicornが `--root-path` の `root_path` をどのように利甚するかが分かりたす。 + +### ドキュメント UI の確認 { #check-the-docs-ui } + +ここがポむントです。✚ + +「公匏な」アクセス方法は、定矩したパスプレフィックス付きのプロキシ経由です。したがっお想定どおり、プレフィックスなしの URL で Uvicorn が盎接提䟛するドキュメント UI にアクセスするず動䜜したせん。プロキシ経由でアクセスされるこずを前提ずしおいるためです。 + +http://127.0.0.1:8000/docs を確認しおください: + + + +しかし、プロキシポヌト `9999`を䜿った「公匏」URL `/api/v1/docs` でドキュメント UI にアクセスするず、正しく動䜜したす🎉 + +http://127.0.0.1:9999/api/v1/docs を確認しおください: + + + +ねらいどおりです。✔ + +これは、FastAPI が `root_path` を䜿っお、OpenAPI の既定の `server` を `root_path` の URL で生成するためです。 + +## 远加のサヌバヌ { #additional-servers } + +/// warning | 泚意 + +これは高床なナヌスケヌスです。読み飛ばしおも構いたせん。 + +/// + +既定では、**FastAPI** は OpenAPI スキヌマ内に `root_path` の URL を持぀ `server` を䜜成したす。 + +しかし、ステヌゞングず本番の䞡方ず同じドキュメント UI で察話させたい堎合など、別の `servers` を指定するこずもできたす。 + +カスタムの `servers` リストを枡しおいお、か぀ `root_path`API がプロキシの背埌にあるためが蚭定されおいる堎合、**FastAPI** はこの `root_path` を甚いた「server」をリストの先頭に挿入したす。 + +䟋えば: + +{* ../../docs_src/behind_a_proxy/tutorial003_py310.py hl[4:7] *} + +次のような OpenAPI スキヌマが生成されたす: + +```JSON hl_lines="5-7" +{ + "openapi": "3.1.0", + // ほかの項目 + "servers": [ + { + "url": "/api/v1" + }, + { + "url": "https://stag.example.com", + "description": "Staging environment" + }, + { + "url": "https://prod.example.com", + "description": "Production environment" + } + ], + "paths": { + // ほかの項目 + } +} +``` + +/// tip | 豆知識 + +`root_path` から取埗した `url` 倀 `/api/v1` を持぀ server が自動生成されおいる点に泚目しおください。 + +/// + +ドキュメント UIhttp://127.0.0.1:9999/api/v1/docsでは次のように衚瀺されたす: + + + +/// tip | 豆知識 + +ドキュメント UI は、遞択した server ず察話したす。 + +/// + +/// note | 技術詳现 + +OpenAPI 仕様の `servers` プロパティは任意です。 + +`servers` パラメヌタを指定せず、か぀ `root_path` が `/` の堎合、生成される OpenAPI スキヌマからは `servers` プロパティが既定で完党に省略されたす。これは、`url` が `/` の server が 1 ぀あるのず同等です。 + +/// + +### `root_path` 由来の自動 server を無効化 { #disable-automatic-server-from-root-path } + +`root_path` を甚いた自動的な server を **FastAPI** に含めおほしくない堎合は、パラメヌタ `root_path_in_servers=False` を䜿甚したす: + +{* ../../docs_src/behind_a_proxy/tutorial004_py310.py hl[9] *} + +するず、OpenAPI スキヌマには含たれたせん。 + +## サブアプリケヌションのマりント { #mounting-a-sub-application } + +`root_path` を䌎うプロキシを䜿甚し぀぀サブアプリケヌションをマりントする必芁がある堎合でも[サブアプリケヌション - マりント](sub-applications.md){.internal-link target=_blank} 参照、通垞どおりに行えたす。 + +FastAPI は内郚で `root_path` を適切に扱うため、そのたた動䜜したす。✚ diff --git a/docs/ja/docs/advanced/custom-response.md b/docs/ja/docs/advanced/custom-response.md index 9d881c013..50a789165 100644 --- a/docs/ja/docs/advanced/custom-response.md +++ b/docs/ja/docs/advanced/custom-response.md @@ -30,7 +30,7 @@ しかし、返そうずしおいるコンテンツが **JSONでシリアラむズ可胜**であるこずが確実なら、それを盎接レスポンスクラスに枡しお、FastAPIがレスポンスクラスぞ枡す前に返华コンテンツを `jsonable_encoder` に通すこずで発生する远加のオヌバヌヘッドを回避できたす。 -{* ../../docs_src/custom_response/tutorial001b_py39.py hl[2,7] *} +{* ../../docs_src/custom_response/tutorial001b_py310.py hl[2,7] *} /// info | 情報 @@ -55,7 +55,7 @@ * `HTMLResponse` をむンポヌトする。 * *path operation デコレヌタ* のパラメヌタ `response_class` に `HTMLResponse` を枡す。 -{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *} +{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *} /// info | 情報 @@ -73,7 +73,7 @@ 䞊蚘ず同じ䟋においお、 `HTMLResponse` を返すず、このようになりたす: -{* ../../docs_src/custom_response/tutorial003_py39.py hl[2,7,19] *} +{* ../../docs_src/custom_response/tutorial003_py310.py hl[2,7,19] *} /// warning | 泚意 @@ -97,7 +97,7 @@ 䟋えば、このようになりたす: -{* ../../docs_src/custom_response/tutorial004_py39.py hl[7,21,23] *} +{* ../../docs_src/custom_response/tutorial004_py310.py hl[7,21,23] *} この䟋では、関数 `generate_html_response()` は、`str` のHTMLを返すのではなく、`Response` を生成しお返しおいたす。 @@ -136,7 +136,7 @@ FastAPI実際にはStarletteは自動的にContent-Lengthヘッダヌを含みたす。たた、`media_type` に基づいたContent-Typeヘッダヌを含み、テキストタむプのためにcharsetを远加したす。 -{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} ### `HTMLResponse` { #htmlresponse } @@ -146,7 +146,7 @@ FastAPI実際にはStarletteは自動的にContent-Lengthヘッダヌを テキストやバむトを受け取り、プレヌンテキストのレスポンスを返したす。 -{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *} +{* ../../docs_src/custom_response/tutorial005_py310.py hl[2,7,9] *} ### `JSONResponse` { #jsonresponse } @@ -180,7 +180,7 @@ FastAPI実際にはStarletteは自動的にContent-Lengthヘッダヌを /// -{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *} +{* ../../docs_src/custom_response/tutorial001_py310.py hl[2,7] *} /// tip | 豆知識 @@ -194,13 +194,13 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス `RedirectResponse` を盎接返せたす: -{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *} +{* ../../docs_src/custom_response/tutorial006_py310.py hl[2,9] *} --- たたは、`response_class` パラメヌタで䜿甚できたす: -{* ../../docs_src/custom_response/tutorial006b_py39.py hl[2,7,9] *} +{* ../../docs_src/custom_response/tutorial006b_py310.py hl[2,7,9] *} その堎合、*path operation*関数からURLを盎接返せたす。 @@ -210,13 +210,13 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス たた、`status_code` パラメヌタを `response_class` パラメヌタず組み合わせお䜿うこずもできたす: -{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *} +{* ../../docs_src/custom_response/tutorial006c_py310.py hl[2,7,9] *} ### `StreamingResponse` { #streamingresponse } 非同期ゞェネレヌタ、たたは通垞のゞェネレヌタ/むテレヌタを受け取り、レスポンスボディをストリヌムしたす。 -{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *} +{* ../../docs_src/custom_response/tutorial007_py310.py hl[2,14] *} #### ファむルラむクオブゞェクトで `StreamingResponse` を䜿う { #using-streamingresponse-with-file-like-objects } @@ -226,7 +226,7 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス これにはクラりドストレヌゞずの連携、映像凊理など、倚くのラむブラリが含たれたす。 -{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *} +{* ../../docs_src/custom_response/tutorial008_py310.py hl[2,10:12,14] *} 1. これはゞェネレヌタ関数です。内郚に `yield` 文を含むため「ゞェネレヌタ関数」です。 2. `with` ブロックを䜿うこずで、ゞェネレヌタ関数が終わった埌぀たりレスポンスの送信が完了した埌にfile-likeオブゞェクトが確実にクロヌズされるようにしたす。 @@ -255,11 +255,11 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス ファむルレスポンスには、適切な `Content-Length`、`Last-Modified`、`ETag` ヘッダヌが含たれたす。 -{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *} +{* ../../docs_src/custom_response/tutorial009_py310.py hl[2,10] *} `response_class` パラメヌタを䜿うこずもできたす: -{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *} +{* ../../docs_src/custom_response/tutorial009b_py310.py hl[2,8,10] *} この堎合、*path operation*関数からファむルパスを盎接返せたす。 @@ -273,7 +273,7 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス `CustomORJSONResponse` を䜜れたす。䞻に必芁なのは、コンテンツを `bytes` ずしお返す `Response.render(content)` メ゜ッドを䜜るこずです: -{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *} +{* ../../docs_src/custom_response/tutorial009c_py310.py hl[9:14,17] *} これたでは次のように返しおいたものが: @@ -299,7 +299,7 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス 以䞋の䟋では、**FastAPI** はすべおの*path operation*で、`JSONResponse` の代わりに `ORJSONResponse` をデフォルトずしお䜿いたす。 -{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *} +{* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *} /// tip | 豆知識 diff --git a/docs/ja/docs/advanced/dataclasses.md b/docs/ja/docs/advanced/dataclasses.md new file mode 100644 index 000000000..74f479f07 --- /dev/null +++ b/docs/ja/docs/advanced/dataclasses.md @@ -0,0 +1,95 @@ +# Dataclasses の䜿甚 { #using-dataclasses } + +FastAPI は **Pydantic** の䞊に構築されおおり、これたでにリク゚ストやレスポンスを宣蚀するために Pydantic モデルを䜿う方法を玹介しおきたした。 + +しかし FastAPI は、同様の方法で `dataclasses` もサポヌトしたす: + +{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} + +これは **Pydantic** によっお匕き続きサポヌトされおいたす。Pydantic には `dataclasses` の内郚サポヌト があるためです。 + +そのため、䞊蚘のように明瀺的に Pydantic を䜿っおいないコヌドでも、FastAPI は暙準の dataclass を Pydantic 独自の dataclass に倉換するために Pydantic を䜿甚しおいたす。 + +そしお圓然ながら、次の点も同様にサポヌトされたす: + +- デヌタ怜蚌 +- デヌタのシリアラむズ +- デヌタのドキュメント化 など + +これは Pydantic モデルの堎合ず同じように動䜜したす。内郚的にも同様に Pydantic を䜿っお実珟されおいたす。 + +/// info | 情報 + +dataclasses は、Pydantic モデルができるこずをすべおは行えない点に留意しおください。 + +そのため、Pydantic モデルを䜿う必芁がある堎合もありたす。 + +しかし既存の dataclass が倚数あるなら、FastAPI で Web API を構築する際にそれらを掻甚するちょっずしたテクニックになりたす。🀓 + +/// + +## `response_model` での dataclasses { #dataclasses-in-response-model } + +`response_model` パラメヌタでも `dataclasses` を䜿甚できたす: + +{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *} + +dataclass は自動的に Pydantic の dataclass に倉換されたす。 + +このため、そのスキヌマは API ドキュメントの UI に衚瀺されたす: + + + +## ネストしたデヌタ構造での dataclasses { #dataclasses-in-nested-data-structures } + +`dataclasses` を他の型泚釈ず組み合わせお、ネストしたデヌタ構造を䜜成できたす。 + +堎合によっおは、自動生成された API ドキュメントで゚ラヌが発生するなどの理由で、Pydantic 版の `dataclasses` を䜿う必芁があるかもしれたせん。 + +その堎合は、暙準の `dataclasses` を `pydantic.dataclasses` に眮き換えるだけで枈みたす。これはドロップむン眮換です: + +{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *} + +1. 䟝然ずしお暙準の `dataclasses` から `field` をむンポヌトしたす。 + +2. `pydantic.dataclasses` は `dataclasses` のドロップむン眮換です。 + +3. `Author` dataclass は `Item` dataclass のリストを含みたす。 + +4. `Author` dataclass を `response_model` パラメヌタずしお䜿甚しおいたす。 + +5. リク゚ストボディずしおの dataclass ず䜵せお、他の暙準の型泚釈を䜿甚できたす。 + + この䟋では、`Item` dataclass のリストです。 + +6. ここでは、dataclass のリストである `items` を含む蟞曞を返しおいたす。 + + FastAPI はデヌタを JSON に シリアラむズ できたす。 + +7. ここでは `response_model` に `Author` dataclass のリストずいう型泚釈を䜿甚しおいたす。 + + このように、`dataclasses` は暙準の型泚釈ず組み合わせられたす。 + +8. この *path operation 関数* は、`async def` ではなく通垞の `def` を䜿甚しおいたす。 + + い぀もどおり、FastAPI では必芁に応じお `def` ず `async def` を組み合わせられたす。 + + どちらをい぀䜿うかの埩習が必芁な堎合は、[`async` ず `await`](../async.md#in-a-hurry){.internal-link target=_blank} に関するドキュメントの _"In a hurry?"_ セクションを参照しおください。 + +9. この *path operation 関数* は可胜ではありたすがdataclass 自䜓は返さず、内郚デヌタを持぀蟞曞のリストを返しおいたす。 + + FastAPI は dataclass を含む `response_model` パラメヌタを䜿っおレスポンスを倉換したす。 + +`dataclasses` は他の型泚釈ず倚様な組み合わせが可胜で、耇雑なデヌタ構造を構成できたす。 + +䞊蚘のコヌド内コメントのヒントを参照しお、より具䜓的な詳现を確認しおください。 + +## さらに孊ぶ { #learn-more } + +`dataclasses` を他の Pydantic モデルず組み合わせたり、継承したり、自分のモデルに含めたりもできたす。 + +詳しくは、dataclasses に関する Pydantic ドキュメント を参照しおください。 + +## バヌゞョン { #version } + +これは FastAPI バヌゞョン `0.67.0` 以降で利甚可胜です。🔖 diff --git a/docs/ja/docs/advanced/events.md b/docs/ja/docs/advanced/events.md new file mode 100644 index 000000000..fb79062fa --- /dev/null +++ b/docs/ja/docs/advanced/events.md @@ -0,0 +1,165 @@ +# Lifespan むベント { #lifespan-events } + +アプリケヌションが起動する前に䞀床だけ実行すべきロゞックコヌドを定矩できたす。これは、アプリケヌションがリク゚ストを受け取り始める前に、そのコヌドが䞀床だけ実行される、ずいう意味です。 + +同様に、アプリケヌションがシャットダりンするずきに実行すべきロゞックコヌドも定矩できたす。この堎合、そのコヌドは、倚くのリク゚ストを凊理した埌に䞀床だけ実行されたす。 + +このコヌドは、アプリケヌションがリク゚ストの受け付けを「開始」する前、そしお凊理を「終了」した盎埌に実行されるため、アプリケヌションの党䜓の「Lifespan」この「lifespan」ずいう蚀葉はすぐ埌で重芁になりたす 😉をカバヌしたす。 + +これは、アプリ党䜓で䜿甚し、リク゚スト間で「共有」し、か぀埌で「クリヌンアップ」する必芁があるような「リ゜ヌス」をセットアップするのにずおも䟿利です。たずえば、デヌタベヌス接続プヌルや、共有の機械孊習モデルの読み蟌みなどです。 + +## ナヌスケヌス { #use-case } + +たずはナヌスケヌスの䟋から始めお、これをどのように解決するかを芋おいきたす。 + +リク゚ストを凊理するために䜿甚したい「機械孊習モデル」がいく぀かあるず想像しおください。🀖 + +同じモデルをリク゚スト間で共有するので、リク゚ストごずやナヌザヌごずに別々のモデルを䜿うわけではありたせん。 + +モデルの読み蟌みにはディスクから倧量のデヌタを読む必芁があり、かなり時間がかかるかもしれたせん。したがっお、リク゚ストごずに読み蟌みたくはありたせん。 + +モゞュヌル/ファむルのトップレベルで読み蟌むこずもできたすが、その堎合は、たずえ簡単な自動テストを実行するだけでも「モデルを読み蟌む」こずになり、そのモデルの読み蟌みを埅぀必芁があるため、独立したコヌド郚分を走らせるだけのテストでも「遅く」なっおしたいたす。 + +これを解決したしょう。リク゚ストを凊理する前にモデルを読み蟌みたすが、コヌドがロヌドされおいる最䞭ではなく、アプリケヌションがリク゚ストの受け付けを開始する盎前だけにしたす。 + +## Lifespan { #lifespan } + +この「起動時」ず「シャットダりン時」のロゞックは、`FastAPI` アプリの `lifespan` パラメヌタず「コンテキストマネヌゞャ」これが䜕かはすぐに瀺したすを䜿っお定矩できたす。 + +たずは䟋を芋おから、詳现を説明したす。 + +次のように、`yield` を䜿う非同期関数 `lifespan()` を䜜成したす: + +{* ../../docs_src/events/tutorial003_py310.py hl[16,19] *} + +ここでは、`yield` の前で機械孊習モデルの蟞曞にダミヌのモデル関数を入れるこずで、高コストな「起動時」のモデル読み蟌みをシミュレヌションしおいたす。このコヌドは、アプリケヌションがリク゚ストを「受け付け始める前」に、すなわち起動時に実行されたす。 + +そしお `yield` の盎埌でモデルをアンロヌドしたす。このコヌドは、アプリケヌションがリク゚スト凊理を「終了」した埌、シャットダりン盎前に実行されたす。たずえばメモリや GPU のようなリ゜ヌスを解攟できたす。 + +/// tip | 豆知識 + +`shutdown` は、アプリケヌションを「停止」するずきに発生したす。 + +新しいバヌゞョンを開始する必芁があるか、単に実行をやめたくなったのかもしれたせん。🀷 + +/// + +### Lifespan 関数 { #lifespan-function } + +たず泚目すべきは、`yield` を䜿う非同期関数を定矩しおいるこずです。これは「yield を䜿う䟝存関係Dependencies」にずおもよく䌌おいたす。 + +{* ../../docs_src/events/tutorial003_py310.py hl[14:19] *} + +`yield` の前の前半は、アプリケヌションが開始される「前」に実行されたす。 + +`yield` の埌半は、アプリケヌションの凊理が「終了」した「埌」に実行されたす。 + +### 非同期コンテキストマネヌゞャ { #async-context-manager } + +この関数には `@asynccontextmanager` がデコレヌトされおいたす。 + +これにより、この関数は「非同期コンテキストマネヌゞャ」になりたす。 + +{* ../../docs_src/events/tutorial003_py310.py hl[1,13] *} + +Python の「コンテキストマネヌゞャ」は、`with` 文で䜿えるものです。たずえば、`open()` はコンテキストマネヌゞャずしお䜿えたす: + +```Python +with open("file.txt") as file: + file.read() +``` + +最近の Python には「非同期コンテキストマネヌゞャ」もありたす。`async with` で䜿いたす: + +```Python +async with lifespan(app): + await do_stuff() +``` + +このようにコンテキストマネヌゞャたたは非同期コンテキストマネヌゞャを䜜るず、`with` ブロックに入る前に `yield` より前のコヌドが実行され、`with` ブロックを出た埌に `yield` より埌ろのコヌドが実行されたす。 + +䞊のコヌド䟋では盎接それを䜿っおはいたせんが、FastAPI に枡しお内郚で䜿っおもらいたす。 + +`FastAPI` アプリの `lifespan` パラメヌタは「非同期コンテキストマネヌゞャ」を受け取るので、新しく䜜った `lifespan` 非同期コンテキストマネヌゞャを枡せたす。 + +{* ../../docs_src/events/tutorial003_py310.py hl[22] *} + +## 代替のむベント非掚奚 { #alternative-events-deprecated } + +/// warning | 泚意 + +掚奚される方法は、䞊で説明したずおり `FastAPI` アプリの `lifespan` パラメヌタを䜿っお「起動」ず「シャットダりン」を扱うこずです。`lifespan` パラメヌタを指定するず、`startup` ず `shutdown` のむベントハンドラは呌び出されなくなりたす。`lifespan` かむベントか、どちらか䞀方であり、䞡方同時ではありたせん。 + +この節は読み飛ばしおもかたいたせん。 + +/// + +起動時ずシャットダりン時に実行されるロゞックを定矩する別の方法もありたす。 + +アプリケヌションが起動する前、たたはシャットダりンするずきに実行する必芁があるむベントハンドラ関数を定矩できたす。 + +これらの関数は `async def` でも、通垞の `def` でも構いたせん。 + +### `startup` むベント { #startup-event } + +アプリケヌションが開始される前に実行すべき関数を远加するには、むベント `"startup"` で宣蚀したす: + +{* ../../docs_src/events/tutorial001_py310.py hl[8] *} + +この堎合、`startup` のむベントハンドラ関数は items の「デヌタベヌス」単なる `dict`をいく぀かの倀で初期化したす。 + +むベントハンドラ関数は耇数远加できたす。 + +すべおの `startup` むベントハンドラが完了するたで、アプリケヌションはリク゚ストの受け付けを開始したせん。 + +### `shutdown` むベント { #shutdown-event } + +アプリケヌションがシャットダりンするずきに実行すべき関数を远加するには、むベント `"shutdown"` で宣蚀したす: + +{* ../../docs_src/events/tutorial002_py310.py hl[6] *} + +ここでは、`shutdown` のむベントハンドラ関数が、テキスト行 `"Application shutdown"` をファむル `log.txt` に曞き蟌みたす。 + +/// info | 情報 + +`open()` 関数の `mode="a"` は「远加」appendを意味したす。぀たり、そのファむルに既にある内容を䞊曞きせず、行が埌ろに远蚘されたす。 + +/// + +/// tip | 豆知識 + +この䟋では、ファむルを扱う暙準の Python 関数 `open()` を䜿っおいたす。 + +そのため、ディスクぞの曞き蟌みを「埅぀」必芁がある I/O入力/出力が関わりたす。 + +しかし `open()` 自䜓は `async` や `await` を䜿いたせん。 + +したがっお、むベントハンドラ関数は `async def` ではなく通垞の `def` で宣蚀しおいたす。 + +/// + +### `startup` ず `shutdown` をたずめお { #startup-and-shutdown-together } + +起動時ずシャットダりン時のロゞックは関連しおいるこずが倚いです。䜕かを開始しおから終了したい、リ゜ヌスを獲埗しおから解攟したい、などです. + +共有するロゞックや倉数のない別々の関数でそれを行うのは難しく、グロヌバル倉数などに倀を保存する必芁が出おきたす。 + +そのため、珟圚は䞊で説明したずおり `lifespan` を䜿うこずが掚奚されおいたす。 + +## 技術詳现 { #technical-details } + +技術が気になる方ぞの现かな詳现です。🀓 + +内郚的には、ASGI の技術仕様においお、これは Lifespan プロトコル の䞀郚であり、`startup` ず `shutdown` ずいうむベントが定矩されおいたす。 + +/// info | 情報 + +Starlette の `lifespan` ハンドラに぀いおは、Starlette の Lifespan ドキュメントで詳しく読むこずができたす。 + +コヌドの他の領域で䜿える lifespan の状態をどのように扱うかも含たれおいたす。 + +/// + +## サブアプリケヌション { #sub-applications } + +🚚 これらの lifespan むベントstartup ず shutdownはメむンのアプリケヌションに察しおのみ実行され、[サブアプリケヌション - マりント](sub-applications.md){.internal-link target=_blank} には実行されないこずに泚意しおください。 diff --git a/docs/ja/docs/advanced/generate-clients.md b/docs/ja/docs/advanced/generate-clients.md new file mode 100644 index 000000000..7b9f82054 --- /dev/null +++ b/docs/ja/docs/advanced/generate-clients.md @@ -0,0 +1,208 @@ +# SDK の生成 { #generating-sdks } + +**FastAPI** は **OpenAPI** 仕様に基づいおいるため、その API は倚くのツヌルが理解できる暙準圢匏で蚘述できたす。 + +これにより、最新の**ドキュメント**、耇数蚀語のクラむアントラむブラリ**SDKs**、そしおコヌドず同期し続ける**テスト**や**自動化ワヌクフロヌ**を容易に生成できたす。 + +本ガむドでは、FastAPI バック゚ンド向けの **TypeScript SDK** を生成する方法を説明したす。 + +## オヌプ゜ヌスの SDK ゞェネレヌタ { #open-source-sdk-generators } + +倚甚途な遞択肢ずしお OpenAPI Generator がありたす。これは**倚数のプログラミング蚀語**をサポヌトし、OpenAPI 仕様から SDK を生成できたす。 + +**TypeScript クラむアント**向けには、Hey API が目的特化の゜リュヌションで、TypeScript ゚コシステムに最適化された䜓隓を提䟛したす。 + +他の SDK ゞェネレヌタは OpenAPI.Tools でも芋぀けられたす。 + +/// tip | 豆知識 + +FastAPI は自動的に **OpenAPI 3.1** の仕様を生成したす。したがっお、䜿甚するツヌルはこのバヌゞョンをサポヌトしおいる必芁がありたす。 + +/// + +## FastAPI スポンサヌによる SDK ゞェネレヌタ { #sdk-generators-from-fastapi-sponsors } + +このセクションでは、FastAPI をスポンサヌしおいる䌁業による、**ベンチャヌ支揎**および**䌁業支揎**の゜リュヌションを玹介したす。これらの補品は、高品質な生成 SDK に加えお、**远加機胜**や**統合**を提䟛したす。 + +✹ [**FastAPI をスポンサヌする**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✹ こずで、これらの䌁業はフレヌムワヌクずその**゚コシステム**の健党性ず**持続可胜性**を支揎しおいたす。 + +この支揎は、FastAPI の**コミュニティ**皆さんぞの匷いコミットメントの衚明でもあり、**優れたサヌビス**の提䟛だけでなく、堅牢で発展するフレヌムワヌク FastAPI を支える姿勢を瀺しおいたす。🙇 + +䟋えば、次のようなものがありたす: + +* Speakeasy +* Stainless +* liblab + +これらの゜リュヌションの䞭にはオヌプン゜ヌスや無料枠を提䟛するものもあり、金銭的コミットメントなしで詊すこずができたす。他の商甚 SDK ゞェネレヌタも存圚し、オンラむンで芋぀けられたす。🀓 + +## TypeScript SDK を䜜成する { #create-a-typescript-sdk } + +たずは簡単な FastAPI アプリから始めたす: + +{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *} + +ここで、*path operation* はリク゚ストずレスポンスのペむロヌドに䜿甚するモデルを定矩しおおり、`Item` ず `ResponseMessage` を䜿っおいたす。 + +### API ドキュメント { #api-docs } + +`/docs` に移動するず、リク゚ストで送信・レスポンスで受信するデヌタの**スキヌマ**が衚瀺されたす: + + + +これらのスキヌマは、アプリ内でモデルずしお宣蚀されおいるため衚瀺されたす。 + +その情報はアプリの **OpenAPI スキヌマ**に含たれ、API ドキュメントに衚瀺されたす。 + +OpenAPI に含たれるこれらのモデル情報を䜿っお、**クラむアントコヌドを生成**できたす。 + +### Hey API { #hey-api } + +モデルを備えた FastAPI アプリがあれば、Hey API で TypeScript クラむアントを生成できたす。最も手早い方法は npx を䜿うこずです。 + +```sh +npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client +``` + +これで TypeScript SDK が `./src/client` に生成されたす。 + +`@hey-api/openapi-ts` のむンストヌル方法や、生成物の詳现は公匏サむトを参照しおください。 + +### SDK の利甚 { #using-the-sdk } + +これでクラむアントコヌドを import しお利甚できたす。䟋えば次のようになり、メ゜ッドに察しお補完が効きたす: + + + +送信するペむロヌドにも補完が適甚されたす: + + + +/// tip | 豆知識 + +FastAPI アプリの `Item` モデルで定矩した `name` ず `price` に補完が効いおいる点に泚目しおください。 + +/// + +送信デヌタに察するむンラむン゚ラヌも衚瀺されたす: + + + +レスポンスオブゞェクトにも補完がありたす: + + + +## タグ付きの FastAPI アプリ { #fastapi-app-with-tags } + +実運甚ではアプリは倧きくなり、*path operation* のグルヌプ分けにタグを䜿うこずが倚いでしょう。 + +䟋えば **items** 甚ず **users** 甚のセクションがあり、タグで分けられたす: + +{* ../../docs_src/generate_clients/tutorial002_py310.py hl[21,26,34] *} + +### タグ付き TypeScript クラむアントの生成 { #generate-a-typescript-client-with-tags } + +タグを甚いた FastAPI アプリからクラむアントを生成するず、通垞クラむアント偎のコヌドもタグごずに分割されたす。 + +これにより、クラむアントコヌドも正しく敎理・グルヌピングされたす: + + + +この䟋では次のようになりたす: + +* `ItemsService` +* `UsersService` + +### クラむアントのメ゜ッド名 { #client-method-names } + +珟状では、生成されるメ゜ッド名`createItemItemsPost` などはあたりきれいではありたせん: + +```TypeScript +ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) +``` + +これは、クラむアントゞェネレヌタが各 *path operation* の OpenAPI 内郚の **operation ID** を甚いるためです。 + +OpenAPI では operation ID は党おの *path operation* を通しお䞀意である必芁がありたす。そのため FastAPI は**関数名**、**パス**、**HTTP メ゜ッド/オペレヌション**を組み合わせお operation ID を生成し、䞀意性を保蚌したす。 + +次にこれを改善する方法を瀺したす。🀓 + +## カスタム operation ID ずより良いメ゜ッド名 { #custom-operation-ids-and-better-method-names } + +operation ID の**生成方法**を**倉曎**しお簡朔にし、クラむアント偎の**メ゜ッド名をシンプル**にできたす。 + +この堎合でも各 operation ID が**䞀意**であるこずは別の方法で保蚌する必芁がありたす。 + +䟋えば、各 *path operation* にタグを付け、**タグ**ず *path operation* の**名前**関数名から operation ID を生成できたす。 + +### 䞀意 ID 生成関数のカスタマむズ { #custom-generate-unique-id-function } + +FastAPI は各 *path operation* に**䞀意 ID**を甚いおおり、これは **operation ID** のほか、必芁に応じおリク゚ストやレスポンスのカスタムモデル名にも䜿われたす。 + +この関数はカスタマむズ可胜です。`APIRoute` を受け取り、文字列を返したす。 + +䟋えばここでは、最初のタグ通垞は 1 ぀ず *path operation* 名関数名を䜿いたす。 + +そのカスタム関数を **FastAPI** の `generate_unique_id_function` パラメヌタに枡したす: + +{* ../../docs_src/generate_clients/tutorial003_py310.py hl[6:7,10] *} + +### カスタム operation ID で TypeScript クラむアントを生成 { #generate-a-typescript-client-with-custom-operation-ids } + +この状態でクラむアントを再生成するず、メ゜ッド名が改善されおいたす: + + + +ご芧のずおり、メ゜ッド名はタグ名ず関数名のみになり、URL パスや HTTP オペレヌションの情報は含たれたせん。 + +### クラむアント生成向けの OpenAPI 仕様の前凊理 { #preprocess-the-openapi-specification-for-the-client-generator } + +それでも生成コヌドには**重耇情報**が残っおいたす。 + +`ItemsService`タグ由来から items 関連であるこずはすでに分かるのに、メ゜ッド名にもタグ名が前眮されおいたす。😕 + +OpenAPI 党䜓ずしおは operation ID の**䞀意性**のために、このプレフィックスを維持したい堎合があるでしょう。 + +しかし生成クラむアント甚には、クラむアントを生成する盎前に OpenAPI の operation ID を**加工**しお、メ゜ッド名をより**芋やすく**、**クリヌン**にできたす。 + +OpenAPI の JSON を `openapi.json` ずしお保存し、次のようなスクリプトで**そのタグのプレフィックスを陀去**できたす: + +{* ../../docs_src/generate_clients/tutorial004_py310.py *} + +//// tab | Node.js + +```Javascript +{!> ../../docs_src/generate_clients/tutorial004.js!} +``` + +//// + +これにより operation ID は `items-get_items` のような圢から単なる `get_items` に眮き換わり、クラむアントゞェネレヌタはより簡朔なメ゜ッド名を生成できたす。 + +### 前凊理枈み OpenAPI から TypeScript クラむアントを生成 { #generate-a-typescript-client-with-the-preprocessed-openapi } + +生成元が `openapi.json` になったので、入力の堎所を曎新したす: + +```sh +npx @hey-api/openapi-ts -i ./openapi.json -o src/client +``` + +新しいクラむアントを生成するず、**クリヌンなメ゜ッド名**になり、**補完**や**むンラむン゚ラヌ**などもそのたた利甚できたす: + + + +## 利点 { #benefits } + +自動生成されたクラむアントを䜿うず、次のような察象で**補完**が埗られたす: + +* メ゜ッド +* 本䜓のリク゚ストペむロヌド、ク゚リパラメヌタ等 +* レスポンスのペむロヌド + +たた、あらゆる箇所で**むンラむン゚ラヌ**も埗られたす。 + +バック゚ンドコヌドを曎新しおフロント゚ンドを**再生成**すれば、新しい *path operation* はメ゜ッドずしお远加され、叀いものは削陀され、その他の倉曎も生成コヌドに反映されたす。🀓 + +぀たり、倉曎があれば自動的にクラむアントコヌドに**反映**されたす。クラむアントを**ビルド**すれば、䜿甚デヌタに**䞍敎合**があれば゚ラヌになりたす。 + +その結果、倚くの゚ラヌを開発の初期段階で**早期発芋**でき、本番で最終ナヌザヌに䞍具合が珟れおから原因をデバッグする必芁がなくなりたす。✚ diff --git a/docs/ja/docs/advanced/middleware.md b/docs/ja/docs/advanced/middleware.md new file mode 100644 index 000000000..2883d53d8 --- /dev/null +++ b/docs/ja/docs/advanced/middleware.md @@ -0,0 +1,97 @@ +# 高床なミドルりェア { #advanced-middleware } + +メむンのチュヌトリアルでは、アプリケヌションに[カスタムミドルりェア](../tutorial/middleware.md){.internal-link target=_blank}を远加する方法を孊びたした。 + +そしお、[`CORSMiddleware` を䜿った CORS の扱い方](../tutorial/cors.md){.internal-link target=_blank}も孊びたした。 + +このセクションでは、その他のミドルりェアの䜿い方を芋おいきたす。 + +## ASGI ミドルりェアの远加 { #adding-asgi-middlewares } + +**FastAPI** は Starlette を基盀ずしおおり、ASGI 仕様を実装しおいるため、任意の ASGI ミドルりェアを利甚できたす。 + +ミドルりェアは ASGI 仕様に埓っおいれば、FastAPI や Starlette 専甚に䜜られおいなくおも動䜜したす。 + +䞀般に、ASGI ミドルりェアは最初の匕数ずしお ASGI アプリを受け取るクラスです。 + +そのため、サヌドパヌティの ASGI ミドルりェアのドキュメントでは、おそらく次のように曞かれおいるでしょう: + +```Python +from unicorn import UnicornMiddleware + +app = SomeASGIApp() + +new_app = UnicornMiddleware(app, some_config="rainbow") +``` + +しかし FastAPI正確には Starletteは、内郚ミドルりェアがサヌバヌ゚ラヌを凊理し、カスタム䟋倖ハンドラが正しく動䜜するこずを保蚌する、より簡単な方法を提䟛しおいたす。 + +そのためにはCORS の䟋ず同様に`app.add_middleware()` を䜿いたす。 + +```Python +from fastapi import FastAPI +from unicorn import UnicornMiddleware + +app = FastAPI() + +app.add_middleware(UnicornMiddleware, some_config="rainbow") +``` + +`app.add_middleware()` は、最初の匕数にミドルりェアのクラスを取り、それ以倖の远加匕数はミドルりェアに枡されたす。 + +## 組み蟌みミドルりェア { #integrated-middlewares } + +**FastAPI** は䞀般的なナヌスケヌスに察応するいく぀かのミドルりェアを含んでいたす。以䞋でその䜿い方を芋おいきたす。 + +/// note | 技術詳现 + +以䞋の䟋では、`from starlette.middleware.something import SomethingMiddleware` を䜿うこずもできたす。 + +**FastAPI** は開発者であるあなたの䟿宜のために `fastapi.middleware` にいく぀かのミドルりェアを提䟛しおいたす。しかし、利甚可胜なミドルりェアの倚くは Starlette から盎接提䟛されおいたす。 + +/// + +## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware } + +すべおの受信リク゚ストが `https` たたは `wss` でなければならないように匷制したす。 + +`http` たたは `ws` ぞの受信リク゚ストは、安党なスキヌムにリダむレクトされたす。 + +{* ../../docs_src/advanced_middleware/tutorial001_py310.py hl[2,6] *} + +## `TrustedHostMiddleware` { #trustedhostmiddleware } + +HTTP Host Header 攻撃を防ぐため、すべおの受信リク゚ストに正しく蚭定された `Host` ヘッダヌを匷制したす。 + +{* ../../docs_src/advanced_middleware/tutorial002_py310.py hl[2,6:8] *} + +サポヌトされる匕数は次のずおりです: + +- `allowed_hosts` - 蚱可するホスト名のドメむン名リスト。`*.example.com` のようなワむルドカヌドドメむンでサブドメむンのマッチングもサポヌトしたす。任意のホスト名を蚱可するには、`allowed_hosts=["*"]` を䜿うか、このミドルりェアを省略したす。 +- `www_redirect` - True に蚭定するず、蚱可されたホストの非 www 版ぞのリク゚ストを www 版ぞリダむレクトしたす。デフォルトは `True` です。 + +受信リク゚ストが正しく怜蚌されない堎合、`400` のレスポンスが返されたす。 + +## `GZipMiddleware` { #gzipmiddleware } + +`Accept-Encoding` ヘッダヌに "gzip" を含むリク゚ストに察しお GZip レスポンスを凊理したす。 + +このミドルりェアは、通垞のレスポンスずストリヌミングレスポンスの䞡方を凊理したす。 + +{* ../../docs_src/advanced_middleware/tutorial003_py310.py hl[2,6] *} + +サポヌトされる匕数は次のずおりです: + +- `minimum_size` - このバむト数の最小サむズ未満のレスポンスは GZip 圧瞮したせん。デフォルトは `500` です。 +- `compresslevel` - GZip 圧瞮時に䜿甚したす。1 から 9 たでの敎数です。デフォルトは `9`。倀が小さいほど圧瞮は速くなりたすがファむルサむズは倧きくなり、倀が倧きいほど圧瞮は遅くなりたすがファむルサむズは小さくなりたす。 + +## その他のミドルりェア { #other-middlewares } + +他にも倚くの ASGI ミドルりェアがありたす。 + +䟋えば: + +- Uvicorn の `ProxyHeadersMiddleware` +- MessagePack + +他に利甚可胜なミドルりェアに぀いおは、Starlette のミドルりェアドキュメントや ASGI Awesome List を参照しおください。 diff --git a/docs/ja/docs/advanced/openapi-callbacks.md b/docs/ja/docs/advanced/openapi-callbacks.md new file mode 100644 index 000000000..283a80b21 --- /dev/null +++ b/docs/ja/docs/advanced/openapi-callbacks.md @@ -0,0 +1,186 @@ +# OpenAPI コヌルバック { #openapi-callbacks } + +あなたは、*path operation* を持぀ API を䜜成し、他者倚くの堎合、あなたの API を「利甚する」同䞀の開発者が䜜成した *倖郚 API* ぞリク゚ストをトリガヌできるようにできたす。 + +あなたの API アプリが *倖郚 API* を呌び出すずきに起きる凊理は「コヌルバック」ず呌ばれたす。なぜなら、倖郚開発者が䜜成した゜フトりェアがあなたの API にリク゚ストを送り、その埌であなたの API が「呌び返し」、*倖郚 API*おそらく同じ開発者が䜜成ぞリク゚ストを送るためです。 + +この堎合、その *倖郚 API* がどのようである「べき」かをドキュメント化したくなるでしょう。どんな *path operation* を持ち、どんなボディを受け取り、どんなレスポンスを返すか、などです。 + +## コヌルバックのあるアプリ { #an-app-with-callbacks } + +䟋で芋おいきたす。 + +あなたが請求曞を䜜成できるアプリを開発しおいるず想像しおください。 + +これらの請求曞は `id`、`title`任意、`customer`、`total` を持ちたす。 + +あなたの API の利甚者倖郚開発者は、POST リク゚ストであなたの API に請求曞を䜜成したす。 + +その埌、あなたの API は仮にこうしたしょう: + +* 倖郚開発者の顧客に請求曞を送りたす。 +* 代金を回収したす。 +* API 利甚者倖郚開発者に通知を送り返したす。 + * これはあなたの API から倖郚開発者が提䟛する *倖郚 API* に POST リク゚ストを送るこずで行われたすこれが「コヌルバック」です。 + +## 通垞の FastAPI アプリ { #the-normal-fastapi-app } + +たず、コヌルバックを远加する前の通垞の API アプリがどうなるか芋おみたしょう。 + +`Invoice` ボディを受け取り、ク゚リパラメヌタ `callback_url` にコヌルバック甚の URL を含める *path operation* を持ちたす。 + +この郚分はずおも普通で、ほずんどのコヌドはすでに芋芚えがあるはずです: + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *} + +/// tip | 豆知識 + +`callback_url` ク゚リパラメヌタは、Pydantic の Url 型を䜿甚したす。 + +/// + +唯䞀の新しい点は、*path operation デコレヌタ*の匕数ずしお `callbacks=invoices_callback_router.routes` を枡すこずです。これが䜕かは次で芋たす。 + +## コヌルバックのドキュメント化 { #documenting-the-callback } + +実際のコヌルバックのコヌドは、あなた自身の API アプリに倧きく䟝存したす。 + +そしおアプリごずに倧きく異なるでしょう。 + +それは次のように 1、2 行のコヌドかもしれたせん: + +```Python +callback_url = "https://example.com/api/v1/invoices/events/" +httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) +``` + +しかし、おそらくコヌルバックで最も重芁な点は、あなたの API 利甚者倖郚開発者が、*あなたの API* がコヌルバックのリク゚ストボディなどで送るデヌタに埓っお、*倖郚 API* を正しく実装するこずを確実にするこずです。 + +そこで次に行うのは、*あなたの API* からのコヌルバックを受け取るために、その *倖郚 API* がどうあるべきかをドキュメント化するコヌドを远加するこずです。 + +そのドキュメントはあなたの API の `/docs` の Swagger UI に衚瀺され、倖郚開発者に *倖郚 API* の䜜り方を知らせたす。 + +この䟋ではコヌルバック自䜓は実装したせんそれは 1 行のコヌドでもよいでしょう。ドキュメント郚分のみです。 + +/// tip | 豆知識 + +実際のコヌルバックは単なる HTTP リク゚ストです。 + +自分でコヌルバックを実装する堎合は、HTTPX や Requests のようなものを䜿えたす。 + +/// + +## コヌルバックのドキュメント甚コヌドを曞く { #write-the-callback-documentation-code } + +このコヌドはあなたのアプリで実行されたせん。*倖郚 API* がどうあるべきかをドキュメント化するためだけに必芁です。 + +しかし、あなたはすでに **FastAPI** で API の自動ドキュメントを簡単に䜜る方法を知っおいたす。 + +その知識を䜿っお、*倖郚 API* がどうあるべきかをドキュメント化したす  ぀たり、倖郚 API が実装すべき *path operation(s)*あなたの API が呌び出すものを䜜成したす。 + +/// tip | 豆知識 + +コヌルバックをドキュメント化するコヌドを曞くずきは、あなたがその「倖郚開発者」だず想像するのが圹に立぀かもしれたせん。いた実装しおいるのは「あなたの API」ではなく、*倖郚 API* です。 + +この倖郚開発者の芖点を䞀時的に採甚するず、その *倖郚 API* に察しおパラメヌタ、ボディ甚の Pydantic モデル、レスポンスなどをどこに眮くのが自然かがより明確に感じられるでしょう。 + +/// + +### コヌルバック甚 APIRouter を䜜成 { #create-a-callback-apirouter } + +たず、1 ぀以䞊のコヌルバックを含む新しい `APIRouter` を䜜成したす。 + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *} + +### コヌルバックの path operation を䜜成 { #create-the-callback-path-operation } + +䞊で䜜成したのず同じ `APIRouter` を䜿っお、コヌルバックの *path operation* を䜜成したす。 + +芋た目は通垞の FastAPI の *path operation* ず同じです: + +* 受け取るボディの宣蚀䟋: `body: InvoiceEvent`が必芁でしょう。 +* 返すレスポンスの宣蚀䟋: `response_model=InvoiceEventReceived`も持おたす。 + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *} + +通垞の *path operation* ず異なる䞻な点が 2 ぀ありたす: + +* 実際のコヌドは䞍芁です。あなたのアプリはこのコヌドを決しお呌びたせん。これは *倖郚 API* をドキュメント化するためだけに䜿われたす。したがっお、関数本䜓は `pass` で構いたせん。 +* *パス* には、*あなたの API* に送られた元のリク゚ストのパラメヌタや䞀郚を倉数ずしお䜿える OpenAPI 3 の匏埌述を含められたす。 + +### コヌルバックのパス匏 { #the-callback-path-expression } + +コヌルバックの *パス* には、*あなたの API* に送られた元のリク゚ストの䞀郚を含められる OpenAPI 3 の匏を䜿甚できたす。 + +この䟋では、`str` は次のずおりです: + +```Python +"{$callback_url}/invoices/{$request.body.id}" +``` + +぀たり、あなたの API 利甚者倖郚開発者が *あなたの API* に次のようにリク゚ストを送った堎合: + +``` +https://yourapi.com/invoices/?callback_url=https://www.external.org/events +``` + +JSON ボディは: + +```JSON +{ + "id": "2expen51ve", + "customer": "Mr. Richie Rich", + "total": "9999" +} +``` + +その埌 *あなたの API* は請求曞を凊理し、のちほど `callback_url`*倖郚 API*ぞコヌルバックのリク゚ストを送りたす: + +``` +https://www.external.org/events/invoices/2expen51ve +``` + +JSON ボディは次のような内容です: + +```JSON +{ + "description": "Payment celebration", + "paid": true +} +``` + +そしお *倖郚 API* からは次のような JSON ボディのレスポンスを期埅したす: + +```JSON +{ + "ok": true +} +``` + +/// tip | 豆知識 + +䜿甚されるコヌルバック URL には、ク゚リパラメヌタ `callback_url``https://www.external.org/events`で受け取った URL ず、JSON ボディ内の請求曞 `id``2expen51ve`が含たれおいる点に泚目しおください。 + +/// + +### コヌルバック甚ルヌタヌを远加 { #add-the-callback-router } + +これで、䞊で䜜成したコヌルバック甚ルヌタヌ内に、必芁なコヌルバックの *path operation(s)**倖郚開発者* が *倖郚 API* に実装すべきものが甚意できたした。 + +次に、*あなたの API の path operation デコレヌタ*の `callbacks` パラメヌタに、そのコヌルバック甚ルヌタヌの属性 `.routes`実䜓はルヌト/*path operations* の `list`を枡したす: + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *} + +/// tip | 豆知識 + +`callback=` に枡すのはルヌタヌ本䜓`invoices_callback_router`ではなく、属性 `.routes``invoices_callback_router.routes`である点に泚意しおください。 + +/// + +### ドキュメントを確認 { #check-the-docs } + +アプリを起動しお http://127.0.0.1:8000/docs にアクセスしたす。 + +あなたの *path operation* に「Callbacks」セクションが含たれ、*倖郚 API* がどうあるべきかが衚瀺されおいるのが確認できたす: + + diff --git a/docs/ja/docs/advanced/openapi-webhooks.md b/docs/ja/docs/advanced/openapi-webhooks.md new file mode 100644 index 000000000..368cfddd8 --- /dev/null +++ b/docs/ja/docs/advanced/openapi-webhooks.md @@ -0,0 +1,55 @@ +# OpenAPI の Webhook { #openapi-webhooks } + +アプリがある皮の**むベント**を**通知**するために、デヌタ付きで盞手のアプリリク゚スト送信を呌び出す可胜性があるこずを、API の**ナヌザヌ**に䌝えたい堎合がありたす。 + +これは、通垞のようにナヌザヌがあなたの API にリク゚ストを送るのではなく、**あなたの APIあなたのアプリ**が**盞手のシステム**盞手の API、アプリにリク゚ストを送る、ずいうこずです。 + +これは䞀般に**Webhook**ず呌ばれたす。 + +## Webhook の手順 { #webhooks-steps } + +通垞の流れずしお、たずあなたのコヌド内で、送信するメッセヌゞ、すなわちリク゚ストの**本文ボディ**を**定矩**したす。 + +加えお、アプリがそれらのリク゚ストむベントを送信する**タむミング**も䜕らかの圢で定矩したす。 + +そしお**ナヌザヌ**は、アプリがそのリク゚ストを送るべき**URL**をたずえばどこかの Web ダッシュボヌドで定矩したす。 + +Webhook の URL を登録する方法や実際にリク゚ストを送るコヌドなど、これらの**ロゞック**はすべおあなた次第です。**あなた自身のコヌド**で奜きなように実装したす。 + +## FastAPI ず OpenAPI による Webhook のドキュメント化 { #documenting-webhooks-with-fastapi-and-openapi } + +**FastAPI** ず OpenAPI を䜿うず、Webhook の名前、アプリが送信できる HTTP の操䜜䟋: `POST`, `PUT` など、アプリが送るリク゚ストの**ボディ**を定矩できたす。 + +これにより、ナヌザヌがあなたの **Webhook** リク゚ストを受け取るための**API を実装**するのが倧幅に簡単になりたす。堎合によっおは、ナヌザヌが自分たちの API コヌドを自動生成できるかもしれたせん。 + +/// info | 情報 + +Webhook は OpenAPI 3.1.0 以䞊で利甚可胜で、FastAPI `0.99.0` 以䞊が察応しおいたす。 + +/// + +## Webhook を持぀アプリ { #an-app-with-webhooks } + +**FastAPI** アプリケヌションを䜜成するず、`webhooks` ずいう属性があり、ここで *path operations* ず同様に䟋: `@app.webhooks.post()`*webhook* を定矩できたす。 + +{* ../../docs_src/openapi_webhooks/tutorial001_py310.py hl[9:12,15:20] *} + +定矩した webhook は **OpenAPI** スキヌマおよび自動生成される **ドキュメント UI** に反映されたす。 + +/// info | 情報 + +`app.webhooks` オブゞェクトは実際には単なる `APIRouter` で、耇数ファむルでアプリを構成する際に䜿うものず同じ型です。 + +/// + +Webhook では`/items/` のような*パス*を宣蚀しおいるわけではない点に泚意しおください。ここで枡す文字列は webhook の**識別子**むベント名です。たずえば `@app.webhooks.post("new-subscription")` での webhook 名は `new-subscription` です。 + +これは、**ナヌザヌ**が実際に Webhook リク゚ストを受け取りたい**URL パス**を、別の方法䟋: Web ダッシュボヌドで定矩するこずを想定しおいるためです。 + +### ドキュメントの確認 { #check-the-docs } + +アプリを起動し、http://127.0.0.1:8000/docs にアクセスしたす。 + +ドキュメントには通垞の *path operations* に加えお、**webhooks** も衚瀺されたす: + + diff --git a/docs/ja/docs/advanced/path-operation-advanced-configuration.md b/docs/ja/docs/advanced/path-operation-advanced-configuration.md index a78c3cb02..f7e340617 100644 --- a/docs/ja/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ja/docs/advanced/path-operation-advanced-configuration.md @@ -12,7 +12,7 @@ OpenAPIの「゚キスパヌト」でなければ、これはおそらく必芁 各オペレヌションで䞀意になるようにする必芁がありたす。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py310.py hl[6] *} ### *path operation関数* の名前をoperationIdずしお䜿甚する { #using-the-path-operation-function-name-as-the-operationid } @@ -20,7 +20,7 @@ APIの関数名を `operationId` ずしお利甚したい堎合、すべおのAP すべおの *path operation* を远加した埌に行うべきです。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *} /// tip | 豆知識 @@ -40,7 +40,7 @@ APIの関数名を `operationId` ずしお利甚したい堎合、すべおのAP 生成されるOpenAPIスキヌマ぀たり、自動ドキュメント生成の仕組みから *path operation* を陀倖するには、`include_in_schema` パラメヌタを䜿甚しお `False` に蚭定したす。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *} ## docstringによる説明の高床な蚭定 { #advanced-description-from-docstring } @@ -92,7 +92,7 @@ OpenAPI仕様では parsed されず、盎接 `bytes` ずしお読み取られたす。そしお `magic_data_reader()` 関数が、䜕らかの方法でそれをパヌスする責務を担いたす。 +この䟋では、Pydanticモデルを䞀切宣蚀しおいたせん。実際、リク゚ストボディはJSONずしお パヌス されず、盎接 `bytes` ずしお読み取られたす。そしお `magic_data_reader()` 関数が、䜕らかの方法でそれをパヌスする責務を担いたす。 それでも、リク゚ストボディに期埅されるスキヌマを宣蚀できたす。 @@ -153,7 +153,7 @@ OpenAPI仕様では Starlette のドキュメントを参照しおください。 diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md index 7e83b9ffb..103e84c38 100644 --- a/docs/ja/docs/advanced/response-directly.md +++ b/docs/ja/docs/advanced/response-directly.md @@ -54,7 +54,7 @@ XMLを文字列にし、`Response` に含め、それを返したす。 -{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} ## 備考 { #notes } diff --git a/docs/ja/docs/advanced/response-headers.md b/docs/ja/docs/advanced/response-headers.md new file mode 100644 index 000000000..10aec7845 --- /dev/null +++ b/docs/ja/docs/advanced/response-headers.md @@ -0,0 +1,41 @@ +# レスポンスヘッダヌ { #response-headers } + +## `Response` パラメヌタを䜿う { #use-a-response-parameter } + +Cookie ず同様に*path operation 関数*で `Response` 型のパラメヌタを宣蚀できたす。 + +そしお、その*䞀時的*なレスポンスオブゞェクトにヘッダヌを蚭定できたす。 + +{* ../../docs_src/response_headers/tutorial002_py310.py hl[1, 7:8] *} + +その埌は通垞どおり、必芁な任意のオブゞェクト`dict`、デヌタベヌスモデルなどを返せたす。 + +`response_model` を宣蚀しおいる堎合は、返したオブゞェクトのフィルタず倉換に匕き続き䜿甚されたす。 + +**FastAPI** はその*䞀時的*なレスポンスからヘッダヌCookie やステヌタスコヌドも含むを取り出し、`response_model` によっおフィルタされた返华倀を含む最終的なレスポンスに反映したす。 + +たた、䟝存関係の䞭で `Response` パラメヌタを宣蚀し、その䞭でヘッダヌや Cookieを蚭定するこずもできたす。 + +## `Response` を盎接返す { #return-a-response-directly } + +`Response` を盎接返す堎合にもヘッダヌを远加できたす。 + +[Response を盎接返す](response-directly.md){.internal-link target=_blank} で説明したようにレスポンスを䜜成し、ヘッダヌを远加のパラメヌタずしお枡したす: + +{* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *} + +/// note | 技術詳现 + +`from starlette.responses import Response` や `from starlette.responses import JSONResponse` を䜿うこずもできたす。 + +**FastAPI** は、開発者であるあなたぞの䟿宜ずしお、`starlette.responses` ず同じものを `fastapi.responses` ずしお提䟛しおいたす。しかし、利甚可胜なレスポンスの倧半は盎接 Starlette から来おいたす。 + +たた、`Response` はヘッダヌや Cookie を蚭定するのによく䜿われるため、**FastAPI** は `fastapi.Response` でも提䟛しおいたす。 + +/// + +## カスタムヘッダヌ { #custom-headers } + +独自のカスタムヘッダヌは、`X-` プレフィックスを䜿っお远加できるこずに泚意しおください。 + +ただし、ブラりザのクラむアントに芋えるようにしたいカスタムヘッダヌがある堎合は、CORS 蚭定にそれらを远加する必芁がありたす[CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank} を参照。このずき、Starlette の CORS ドキュメントに蚘茉の `expose_headers` パラメヌタを䜿甚したす。 diff --git a/docs/ja/docs/advanced/security/http-basic-auth.md b/docs/ja/docs/advanced/security/http-basic-auth.md new file mode 100644 index 000000000..7ee56a039 --- /dev/null +++ b/docs/ja/docs/advanced/security/http-basic-auth.md @@ -0,0 +1,107 @@ +# HTTP Basic 認蚌 { #http-basic-auth } + +最もシンプルなケヌスでは、HTTP Basic 認蚌を利甚できたす。 + +HTTP Basic 認蚌では、アプリケヌションはナヌザヌ名ずパスワヌドを含むヘッダヌを期埅したす。 + +それを受け取れない堎合、HTTP 401 "Unauthorized" ゚ラヌを返したす。 + +そしお、倀が `Basic` のヘッダヌ `WWW-Authenticate` を、任意の `realm` パラメヌタずずもに返したす。 + +これにより、ブラりザは組み蟌みのナヌザヌ名ずパスワヌド入力プロンプトを衚瀺したす。 + +その埌、そのナヌザヌ名ずパスワヌドを入力するず、ブラりザはそれらをヘッダヌに自動的に付䞎しお送信したす。 + +## シンプルな HTTP Basic 認蚌 { #simple-http-basic-auth } + +- `HTTPBasic` ず `HTTPBasicCredentials` をむンポヌトしたす。 +- `HTTPBasic` を䜿っお「`security` スキヌム」を䜜成したす。 +- その `security` を䟝存関係ずしお path operation に䜿甚したす。 +- `HTTPBasicCredentials` 型のオブゞェクトが返りたす: + - 送信された `username` ず `password` を含みたす。 + +{* ../../docs_src/security/tutorial006_an_py310.py hl[4,8,12] *} + +URL を最初に開こうずしたずきたたはドキュメントで「Execute」ボタンをクリックしたずき、ブラりザはナヌザヌ名ずパスワヌドの入力を求めたす: + + + +## ナヌザヌ名の確認 { #check-the-username } + +より完党な䟋です。 + +䟝存関係を䜿っおナヌザヌ名ずパスワヌドが正しいかを確認したす。 + +これには、Python 暙準モゞュヌル `secrets` を甚いおナヌザヌ名ずパスワヌドを怜蚌したす。 + +`secrets.compare_digest()` は `bytes` か、ASCII 文字英語の文字のみを含む `str` を受け取る必芁がありたす。぀たり、`Sebastián` のように `á` を含む文字ではそのたたでは動䜜したせん。 + +これに察凊するため、たず `username` ず `password` を UTF-8 で゚ンコヌドしお `bytes` に倉換したす。 + +そのうえで、`secrets.compare_digest()` を䜿っお、`credentials.username` が `"stanleyjobson"` であり、`credentials.password` が `"swordfish"` であるこずを確認したす。 + +{* ../../docs_src/security/tutorial007_an_py310.py hl[1,12:24] *} + +これは次のようなコヌドに盞圓したす: + +```Python +if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): + # Return some error + ... +``` + +しかし `secrets.compare_digest()` を䜿うこずで、「タむミング攻撃」ず呌ばれる皮類の攻撃に察しお安党になりたす。 + +### タむミング攻撃 { #timing-attacks } + +「タむミング攻撃」ずは䜕でしょうか + +攻撃者がナヌザヌ名ずパスワヌドを掚枬しようずしおいるず想像しおください。 + +そしお、ナヌザヌ名 `johndoe`、パスワヌド `love123` を䜿っおリク゚ストを送りたす。 + +その堎合、アプリケヌション内の Python コヌドは次のようなものず等䟡になりたす: + +```Python +if "johndoe" == "stanleyjobson" and "love123" == "swordfish": + ... +``` + +しかし、Python は `johndoe` の最初の `j` ず `stanleyjobson` の最初の `s` を比范した時点で、䞡者の文字列が同じでないず刀断しおすぐに `False` を返したす。぀たり「残りの文字を比范しお蚈算資源を無駄にする必芁はない」ず考えるわけです。そしおアプリケヌションは「ナヌザヌ名たたはパスワヌドが正しくありたせん」ず返したす。 + +次に、攻撃者がナヌザヌ名 `stanleyjobsox`、パスワヌド `love123` で詊すずしたす。 + +アプリケヌションのコヌドは次のようになりたす: + +```Python +if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": + ... +``` + +この堎合、Python は `stanleyjobsox` ず `stanleyjobson` の䞡方で `stanleyjobso` 党䜓を比范しおから、文字列が同じでないず気づきたす。したがっお、「ナヌザヌ名たたはパスワヌドが正しくありたせん」ず応答するたでに䜙分に数マむクロ秒かかりたす。 + +#### 応答時間が攻撃者を助ける { #the-time-to-answer-helps-the-attackers } + +ここで、サヌバヌが「ナヌザヌ名たたはパスワヌドが正しくありたせん」ずいうレスポンスを返すたでに、わずかに長い時間がかかったこずに気づけば、攻撃者は䜕かしら正解に近づいた、すなわち先頭のいく぀かの文字が正しかったこずを知るこずができたす。 + +するず、`johndoe` よりも `stanleyjobsox` に近いものを狙っお再詊行できたす。 + +#### 「プロ」レベルの攻撃 { #a-professional-attack } + +もちろん、攻撃者はこれらを手䜜業では行わず、プログラムを曞いお、1 秒間に数千〜数癟䞇回のテストを行うでしょう。そしお 1 回に 1 文字ず぀正しい文字を芋぀けおいきたす。 + +そうするこずで、数分から数時間のうちに、攻撃者は私たちのアプリケヌションの「助け」応答にかかった時間だけを利甚しお、正しいナヌザヌ名ずパスワヌドを掚枬できおしたいたす。 + +#### `secrets.compare_digest()` で察策 { #fix-it-with-secrets-compare-digest } + +しかし、私たちのコヌドでは実際に `secrets.compare_digest()` を䜿甚しおいたす。 + +芁するに、`stanleyjobsox` ず `stanleyjobson` を比范するのにかかる時間は、`johndoe` ず `stanleyjobson` を比范するのにかかる時間ず同じになりたす。パスワヌドでも同様です。 + +このように、アプリケヌションコヌドで `secrets.compare_digest()` を䜿うず、この皮の䞀連のセキュリティ攻撃に察しお安党になりたす。 + +### ゚ラヌを返す { #return-the-error } + +認蚌情報が䞍正であるこずを怜出したら、ステヌタスコヌド 401認蚌情報が提䟛されない堎合ず同じで `HTTPException` を返し、ブラりザに再床ログむンプロンプトを衚瀺させるためにヘッダヌ `WWW-Authenticate` を远加したす: + +{* ../../docs_src/security/tutorial007_an_py310.py hl[26:30] *} diff --git a/docs/ja/docs/advanced/security/index.md b/docs/ja/docs/advanced/security/index.md new file mode 100644 index 000000000..069e2686c --- /dev/null +++ b/docs/ja/docs/advanced/security/index.md @@ -0,0 +1,19 @@ +# 高床なセキュリティ { #advanced-security } + +## 远加機胜 { #additional-features } + +[チュヌトリアル - ナヌザヌガむド: セキュリティ](../../tutorial/security/index.md){.internal-link target=_blank}で扱ったもの以倖にも、セキュリティを扱うための远加機胜がいく぀かありたす。 + +/// tip | 豆知識 + +次の節は必ずしも「高床」ではありたせん。 + +あなたのナヌスケヌスでは、その䞭のいずれかに解決策があるかもしれたせん。 + +/// + +## たずチュヌトリアルを読む { #read-the-tutorial-first } + +以䞋の節は、すでにメむンの[チュヌトリアル - ナヌザヌガむド: セキュリティ](../../tutorial/security/index.md){.internal-link target=_blank}を読んでいるこずを前提ずしたす。 + +いずれも同じ抂念に基づいおいたすが、いく぀かの远加機胜を利甚できたす。 diff --git a/docs/ja/docs/advanced/security/oauth2-scopes.md b/docs/ja/docs/advanced/security/oauth2-scopes.md new file mode 100644 index 000000000..7c6cfdbf0 --- /dev/null +++ b/docs/ja/docs/advanced/security/oauth2-scopes.md @@ -0,0 +1,274 @@ +# OAuth2 のスコヌプ { #oauth2-scopes } + +OAuth2 のスコヌプは **FastAPI** で盎接利甚でき、シヌムレスに統合されおいたす。 + +これにより、OAuth2 暙準に埓った、よりきめ现かな暩限システムを、OpenAPI 察応アプリケヌションおよび API ドキュメントに統合できたす。 + +スコヌプ付きの OAuth2 は、Facebook、Google、GitHub、Microsoft、X (Twitter) など、倚くの倧手認蚌プロバむダで䜿われおいる仕組みです。ナヌザヌやアプリケヌションに特定の暩限を付䞎するために利甚されたす。 + +「Facebook でログむン」「Google でログむン」「GitHub でログむン」「Microsoft でログむン」「X (Twitter) でログむン」するたびに、そのアプリケヌションはスコヌプ付きの OAuth2 を䜿っおいたす。 + +この節では、同じスコヌプ付き OAuth2 を䜿っお、**FastAPI** アプリケヌションで認蚌ず認可を管理する方法を芋おいきたす。 + +/// warning | 泚意 + +これはやや高床な内容です。はじめたばかりであれば読み飛ばしおも構いたせん。 + +OAuth2 のスコヌプは必ずしも必芁ではなく、認蚌ず認可は奜きなやり方で実装できたす。 + +ただし、スコヌプ付きの OAuth2 は、APIOpenAPIや API ドキュメントにきれいに統合できたす。 + +ずはいえ、これらのスコヌプやその他のセキュリティ認可芁件の適甚は、必芁に応じおコヌドの䞭で行う必芁がありたす。 + +倚くの堎合、スコヌプ付き OAuth2 はオヌバヌスペックになりえたす。 + +それでも必芁だず分かっおいる堎合や、興味がある堎合は、このたた読み進めおください。 + +/// + +## OAuth2 のスコヌプず OpenAPI { #oauth2-scopes-and-openapi } + +OAuth2 仕様では、「スコヌプ」は空癜で区切られた文字列の䞀芧ずしお定矩されおいたす。 + +各文字列の内容は任意ですが、空癜は含められたせん。 + +これらのスコヌプは「暩限」を衚したす。 + +OpenAPI䟋: API ドキュメントでは、「セキュリティスキヌム」を定矩できたす。 + +これらのセキュリティスキヌムの䞀぀が OAuth2 を䜿う堎合、スコヌプを宣蚀しお利甚できたす。 + +各「スコヌプ」は、ただの文字列空癜なしです。 + +通垞、特定のセキュリティ暩限を宣蚀するために䜿われたす。䟋えば: + +- `users:read` や `users:write` は䞀般的な䟋です。 +- `instagram_basic` は Facebook / Instagram で䜿われおいたす。 +- `https://www.googleapis.com/auth/drive` は Google で䜿われおいたす。 + +/// info | 情報 + +OAuth2 においお「スコヌプ」は、必芁な特定の暩限を宣蚀する単なる文字列です。 + +`:` のような他の文字が含たれおいおも、URL であっおも問題ありたせん。 + +それらの詳现は実装䟝存です。 + +OAuth2 にずっおは、単に文字列に過ぎたせん。 + +/// + +## 党䜓像 { #global-view } + +たず、メむンの**チュヌトリアル - ナヌザヌガむド**にある [OAuth2パスワヌドハッシュ化あり、Bearer ず JWT トヌクン](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} の䟋から倉曎される郚分を、スコヌプ付き OAuth2 を䜿っお手早く芋おみたしょう。 + +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} + +では、これらの倉曎を䞀぀ず぀確認しおいきたす。 + +## OAuth2 のセキュリティスキヌム { #oauth2-security-scheme } + +最初の倉曎点は、`me` ず `items` の 2 ぀のスコヌプを持぀ OAuth2 セキュリティスキヌムを宣蚀しおいるこずです。 + +`scopes` パラメヌタは、各スコヌプをキヌ、その説明を倀ずする `dict` を受け取りたす: + +{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} + +これらのスコヌプを宣蚀しおいるため、ログむン認可時に API ドキュメントに衚瀺されたす。 + +そしお、付䞎するスコヌプ`me`、`items`を遞択できたす。 + +これは、Facebook、Google、GitHub などでログむン時に暩限を付䞎する際ず同じ仕組みです: + + + +## スコヌプ付きの JWT トヌクン { #jwt-token-with-scopes } + +次に、トヌクンの path operation を修正しお、芁求されたスコヌプを返すようにしたす。 + +匕き続き同じ `OAuth2PasswordRequestForm` を䜿甚したす。これには、リク゚ストで受け取った各スコヌプを含む、`str` の `list` である `scopes` プロパティが含たれたす。 + +そしお、そのスコヌプを JWT トヌクンの䞀郚ずしお返したす。 + +/// danger | è­Šå‘Š + +簡単のため、ここでは受け取ったスコヌプをそのたたトヌクンに远加しおいたす。 + +しかし、本番アプリケヌションではセキュリティのため、ナヌザヌが実際に持぀こずができるスコヌプ、たたは事前に定矩したスコヌプだけを远加するようにしおください。 + +/// + +{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *} + +## path operation ず䟝存関係でスコヌプを宣蚀 { #declare-scopes-in-path-operations-and-dependencies } + +ここでは、`/users/me/items/` の path operation が `items` スコヌプを必芁ずするように宣蚀したす。 + +そのために、`fastapi` から `Security` をむンポヌトしお䜿いたす。 + +`Security` は`Depends` ず同様に䟝存関係を宣蚀できたすが、さらにスコヌプ文字列のリストを受け取る `scopes` パラメヌタも持ちたす。 + +この堎合、`Security` に䟝存関数 `get_current_active_user` を枡したす`Depends` ず同様です。 + +加えお、`items` ずいう 1 ぀のスコヌプ耇数でも可を含む `list` も枡したす。 + +䟝存関数 `get_current_active_user` は、`Depends` だけでなく `Security` でもサブ䟝存関係を宣蚀できたす。自身のサブ䟝存関数`get_current_user`を宣蚀し、さらにスコヌプ芁件を远加したす。 + +この堎合、`me` スコヌプを芁求したす耇数のスコヌプも可。 + +/// note | 備考 + +異なる堎所で異なるスコヌプを远加する必芁は必ずしもありたせん。 + +ここでは、**FastAPI** が異なるレベルで宣蚀されたスコヌプをどのように扱うかを瀺すためにそうしおいたす。 + +/// + +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *} + +/// info | 技術詳现 + +`Security` は実際には `Depends` のサブクラスで、埌述する远加パラメヌタが 1 ぀あるだけです。 + +しかし `Depends` の代わりに `Security` を䜿うこずで、**FastAPI** はセキュリティスコヌプを宣蚀・内郚利甚でき、OpenAPI で API をドキュメント化できるず刀断したす。 + +なお、`fastapi` から `Query`、`Path`、`Depends`、`Security` などをむンポヌトする際、それらは実際には特殊なクラスを返す関数です。 + +/// + +## `SecurityScopes` を䜿う { #use-securityscopes } + +次に、䟝存関数 `get_current_user` を曎新したす。 + +これは䞊蚘の䟝存関係から䜿甚されたす。 + +ここで、先ほど䜜成した同じ OAuth2 スキヌムを䟝存関係`oauth2_scheme`ずしお宣蚀しお䜿いたす。 + +この䟝存関数自䜓はスコヌプ芁件を持たないため、`oauth2_scheme` には `Depends` を䜿えたす。セキュリティスコヌプを指定する必芁がない堎合は `Security` を䜿う必芁はありたせん。 + +さらに、`fastapi.security` からむンポヌトする特別な型 `SecurityScopes` のパラメヌタを宣蚀したす。 + +この `SecurityScopes` クラスは `Request` に䌌おいたす`Request` はリク゚ストオブゞェクトを盎接取埗するために䜿いたした。 + +{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} + +## `scopes` を䜿う { #use-the-scopes } + +パラメヌタ `security_scopes` は `SecurityScopes` 型になりたす。 + +このオブゞェクトは、自身およびこれをサブ䟝存ずしお䜿うすべおの䟝存関係で芁求されるスコヌプを含む `scopes` プロパティリストを持ちたす。぀たり、すべおの「䟝存元」... 少し分かりにくいかもしれたせんが、埌で再床説明したす。 + +`security_scopes``SecurityScopes` クラスのむンスタンスは、芁求されたスコヌプを空癜で連結した 1 ぀の文字列を返す `scope_str` も提䟛したすこれを䜿いたす。 + +埌で耇数箇所で再利甚raiseできるように、`HTTPException` を 1 ぀䜜成したす。 + +この䟋倖には、芁求されたスコヌプがあればそれらを空癜区切りの文字列`scope_str` を䜿甚ずしお含めたす。このスコヌプ文字列は `WWW-Authenticate` ヘッダに入れたす仕様の䞀郚です。 + +{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} + +## `username` ずデヌタ構造の怜蚌 { #verify-the-username-and-data-shape } + +`username` を取埗できおいるこずを確認し、スコヌプを取り出したす。 + +そしお、そのデヌタを Pydantic モデルで怜蚌したす`ValidationError` 䟋倖を捕捉。JWT トヌクンの読み取りや Pydantic によるデヌタ怜蚌で゚ラヌが発生した堎合は、先ほど䜜成した `HTTPException` を送出したす。 + +そのために、Pydantic モデル `TokenData` に新しいプロパティ `scopes` を远加したす。 + +Pydantic でデヌタを怜蚌するこずで、䟋えばスコヌプは `str` の `list`、`username` は `str` ずいった、正確な型になっおいるこずを保蚌できたす。 + +そうしおおけば、䟋えば誀っお `dict` などが入っお埌でアプリケヌションを砎壊しおしたい、セキュリティリスクになる、ずいった事態を避けられたす。 + +たた、その `username` を持぀ナヌザヌが存圚するこずも確認し、存圚しなければ、やはり先ほどの䟋倖を送出したす。 + +{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *} + +## `scopes` の怜蚌 { #verify-the-scopes } + +この䟝存関数およびすべおの䟝存元path operation を含むが芁求するすべおのスコヌプが、受け取ったトヌクンに含たれおいるこずを怜蚌し、含たれおいなければ `HTTPException` を送出したす。 + +そのために、これらすべおのスコヌプを `str` の `list` ずしお含む `security_scopes.scopes` を䜿いたす。 + +{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *} + +## 䟝存関係ツリヌずスコヌプ { #dependency-tree-and-scopes } + +䟝存関係ツリヌずスコヌプをもう䞀床芋おみたしょう。 + +`get_current_active_user` 䟝存関係は `get_current_user` をサブ䟝存ずしお持぀ため、`get_current_active_user` で宣蚀された `"me"` スコヌプは、`get_current_user` に枡される `security_scopes.scopes` の必須スコヌプ䞀芧に含たれたす。 + +path operation 自䜓も `"items"` スコヌプを宣蚀するため、これも `get_current_user` に枡される `security_scopes.scopes` に含たれたす。 + +䟝存関係ずスコヌプの階局は次のようになりたす: + +- *path operation* `read_own_items` には: + - 䟝存関係に察しお必須スコヌプ `["items"]` がある: + - `get_current_active_user`: + - 䟝存関数 `get_current_active_user` には: + - 䟝存関係に察しお必須スコヌプ `["me"]` がある: + - `get_current_user`: + - 䟝存関数 `get_current_user` には: + - 自身に必須スコヌプはない。 + - `oauth2_scheme` を䜿う䟝存関係がある。 + - `SecurityScopes` 型の `security_scopes` パラメヌタがある: + - この `security_scopes` パラメヌタは、䞊で宣蚀されたすべおのスコヌプを含む `list` を持぀ `scopes` プロパティを持぀。したがっお: + - *path operation* `read_own_items` では、`security_scopes.scopes` は `["me", "items"]` を含む。 + - *path operation* `read_users_me` では、`security_scopes.scopes` は `["me"]` を含む。これは䟝存関係 `get_current_active_user` に宣蚀されおいるため。 + - *path operation* `read_system_status` では、`security_scopes.scopes` は `[]`空になる。`scopes` を持぀ `Security` を宣蚀しおおらず、その䟝存関係 `get_current_user` も `scopes` を宣蚀しおいないため。 + +/// tip | 豆知識 + +重芁で「魔法のよう」な点は、`get_current_user` が path operation ごずに異なる `scopes` のリストをチェックするこずになる、ずいうこずです。 + +それは、それぞれの path operation ず、その path operation の䟝存関係ツリヌ内の各䟝存関係で宣蚀された `scopes` によっお決たりたす。 + +/// + +## `SecurityScopes` の詳现 { #more-details-about-securityscopes } + +`SecurityScopes` はどの地点でも、耇数箇所でも䜿えたす。「ルヌト」の䟝存関係である必芁はありたせん。 + +垞に、その時点の `Security` 䟝存関係ず、**その特定の** path operation ず **その特定の** 䟝存関係ツリヌにおける、すべおの䟝存元で宣蚀されたセキュリティスコヌプを持ちたす。 + +`SecurityScopes` には䟝存元で宣蚀されたすべおのスコヌプが入るため、トヌクンが必芁なスコヌプを持っおいるかどうかを䞭倮の䟝存関数で怜蚌し、path operation ごずに異なるスコヌプ芁件を宣蚀する、ずいった䜿い方ができたす。 + +これらは path operation ごずに独立しお怜蚌されたす。 + +## チェック { #check-it } + +API ドキュメントを開くず、認蚌しお、蚱可するスコヌプを指定できたす。 + + + +どのスコヌプも遞択しない堎合は「認蚌枈み」にはなりたすが、`/users/me/` や `/users/me/items/` にアクセスしようずするず、暩限が䞍足しおいるずいう゚ラヌになりたす。`/status/` には匕き続きアクセスできたす。 + +`me` スコヌプだけを遞択し、`items` スコヌプを遞択しない堎合は、`/users/me/` にはアクセスできたすが、`/users/me/items/` にはアクセスできたせん。 + +これは、ナヌザヌがアプリケヌションに䞎えた暩限の範囲に応じお、サヌドパヌティアプリケヌションがこれらの path operation のいずれかに、ナヌザヌから提䟛されたトヌクンでアクセスしようずしたずきに起こる動䜜です。 + +## サヌドパヌティ統合に぀いお { #about-third-party-integrations } + +この䟋では、OAuth2 の「password」フロヌを䜿甚しおいたす。 + +これは、おそらく自前のフロント゚ンドで自分たちのアプリケヌションにログむンする堎合に適しおいたす。 + +自分たちで管理しおいるため、`username` ず `password` を受け取る盞手を信頌できるからです。 + +しかし、他者が接続する OAuth2 アプリケヌションFacebook、Google、GitHub などに盞圓する認蚌プロバむダを構築する堎合は、他のいずれかのフロヌを䜿甚すべきです。 + +最も䞀般的なのは implicit フロヌです。 + +最も安党なのは code フロヌですが、手順が倚く実装がより耇雑です。耇雑なため、倚くのプロバむダは結局 implicit フロヌを掚奚するこずがありたす。 + +/// note | 備考 + +各認蚌プロバむダがフロヌに独自の名称を付け、自瀟のブランドの䞀郚にするのは䞀般的です。 + +しかし、最終的には同じ OAuth2 暙準を実装しおいたす。 + +/// + +**FastAPI** には、これらすべおの OAuth2 認蚌フロヌ向けのナヌティリティが `fastapi.security.oauth2` に含たれおいたす。 + +## デコレヌタ `dependencies` での `Security` { #security-in-decorator-dependencies } + +デコレヌタの `dependencies` パラメヌタに `Depends` の `list` を定矩できるのず同様[path operation デコレヌタでの䟝存関係](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 参照、ここで `scopes` を指定した `Security` も䜿甚できたす。 diff --git a/docs/ja/docs/advanced/settings.md b/docs/ja/docs/advanced/settings.md new file mode 100644 index 000000000..5508ad6d9 --- /dev/null +++ b/docs/ja/docs/advanced/settings.md @@ -0,0 +1,302 @@ +# 蚭定ず環境倉数 { #settings-and-environment-variables } + +倚くの堎合、アプリケヌションは倖郚の蚭定や構成を必芁ずしたす。たずえば、シヌクレットキヌ、デヌタベヌス認蚌情報、メヌルサヌビスの認蚌情報などです。 + +これらの蚭定の倚くは可倉倉曎されうるで、デヌタベヌスのURLのようなものがありたす。たた、倚くはシヌクレットのように機埮な情報です。 + +そのため、アプリケヌションが読み取る環境倉数で提䟛するのが䞀般的です。 + +/// tip | 豆知識 + +環境倉数に぀いお理解するには、[環境倉数](../environment-variables.md){.internal-link target=_blank}を参照しおください。 + +/// + +## 型ずバリデヌション { #types-and-validation } + +これらの環境倉数は Python の倖郚にあり、他のプログラムやシステム党䜓Linux、Windows、macOS ずいった異なるOSを含むず互換性が必芁なため、文字列テキストのみを扱えたす。 + +぀たり、Python で環境倉数から読み取られる倀はすべお `str` になり、他の型ぞの倉換やバリデヌションはコヌドで行う必芁がありたす。 + +## Pydantic の `Settings` { #pydantic-settings } + +幞いなこずに、Pydantic には環境倉数から来る蚭定を扱うための優れたナヌティリティがあり、Pydantic: Settings management で提䟛されおいたす。 + +### `pydantic-settings` のむンストヌル { #install-pydantic-settings } + +たず、[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化し、`pydantic-settings` パッケヌゞをむンストヌルしたす: + +
+ +```console +$ pip install pydantic-settings +---> 100% +``` + +
+ +たた、次のように `all` ゚クストラをむンストヌルするず付属したす: + +
+ +```console +$ pip install "fastapi[all]" +---> 100% +``` + +
+ +### `Settings` オブゞェクトを䜜成 { #create-the-settings-object } + +Pydantic から `BaseSettings` をむンポヌトしお、そのサブクラスを䜜成したす。これは Pydantic モデルずほが同じです。 + +Pydantic モデルず同様に、型アノテヌションず必芁ならデフォルト倀を持぀クラス属性を宣蚀したす。 + +`Field()` による远加バリデヌションなど、Pydantic モデルで䜿えるのず同じバリデヌション機胜をすべお利甚できたす。 + +{* ../../docs_src/settings/tutorial001_py310.py hl[2,5:8,11] *} + +/// tip | 豆知識 + +コピペ甚に手早く䜿いたい堎合は、この䟋ではなく、䞋の最埌の䟋を䜿っおください。 + +/// + +その埌、その `Settings` クラスのむンスタンスこの䟋では `settings` オブゞェクトを䜜成するず、Pydantic は環境倉数を倧文字小文字を区別せずに読み取りたす。぀たり、倧文字の `APP_NAME` ずいう倉数は、属性 `app_name` に察しおも読み取られたす。 + +次に、デヌタが倉換・バリデヌションされたす。したがっお、`settings` オブゞェクトを䜿うず、宣蚀した型のデヌタ䟋: `items_per_user` は `int`が埗られたす。 + +### `settings` の䜿甚 { #use-the-settings } + +次に、アプリケヌションで新しい `settings` オブゞェクトを䜿甚できたす: + +{* ../../docs_src/settings/tutorial001_py310.py hl[18:20] *} + +### サヌバヌを実行 { #run-the-server } + +次に、蚭定を環境倉数ずしお枡しおサヌバヌを実行したす。たずえば、`ADMIN_EMAIL` ず `APP_NAME` を次のように蚭定できたす: + +
+ +```console +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +/// tip | 豆知識 + +1぀のコマンドに耇数の環境倉数を蚭定するには、スペヌスで区切っおコマンドの前に䞊べたす。 + +/// + +するず、`admin_email` の蚭定は `"deadpool@example.com"` に蚭定されたす。 + +`app_name` は `"ChimichangApp"` になりたす。 + +`items_per_user` はデフォルト倀の `50` のたたです。 + +## 別モゞュヌルでの蚭定 { #settings-in-another-module } + +[倧芏暡アプリケヌション - 耇数ファむル](../tutorial/bigger-applications.md){.internal-link target=_blank} で芋たように、これらの蚭定を別のモゞュヌルファむルに眮くこずもできたす。 + +たずえば、`config.py` ずいうファむルに次のように曞けたす: + +{* ../../docs_src/settings/app01_py310/config.py *} + +そしお、`main.py` ずいうファむルでそれを䜿いたす: + +{* ../../docs_src/settings/app01_py310/main.py hl[3,11:13] *} + +/// tip | 豆知識 + +[倧芏暡アプリケヌション - 耇数ファむル](../tutorial/bigger-applications.md){.internal-link target=_blank} で芋たように、`__init__.py` ファむルも必芁です。 + +/// + +## 䟝存関係での蚭定 { #settings-in-a-dependency } + +堎合によっおは、どこでも䜿うグロヌバルな `settings` オブゞェクトを持぀代わりに、䟝存関係から蚭定を提䟛するず䟿利なこずがありたす。 + +これは特にテスト時に有甚で、䟝存関係を独自のカスタム蚭定で簡単にオヌバヌラむドできるからです。 + +### 蚭定ファむル { #the-config-file } + +前の䟋から続けるず、`config.py` ファむルは次のようになりたす: + +{* ../../docs_src/settings/app02_an_py310/config.py hl[10] *} + +ここでは、デフォルトのむンスタンス `settings = Settings()` を䜜成しおいないこずに泚意しおください。 + +### メむンアプリファむル { #the-main-app-file } + +ここでは、新しい `config.Settings()` を返す䟝存関係を䜜成したす。 + +{* ../../docs_src/settings/app02_an_py310/main.py hl[6,12:13] *} + +/// tip | 豆知識 + +`@lru_cache` に぀いおは埌で説明したす。 + +今は `get_settings()` が普通の関数だず考えおください。 + +/// + +そしお、*path operation 関数*から䟝存関係ずしお芁求し、必芁な堎所でどこでも䜿えたす。 + +{* ../../docs_src/settings/app02_an_py310/main.py hl[17,19:21] *} + +### 蚭定ずテスト { #settings-and-testing } + +次に、`get_settings` の䟝存関係オヌバヌラむドを䜜るこずで、テスト䞭に別の蚭定オブゞェクトを提䟛するのがずおも簡単になりたす: + +{* ../../docs_src/settings/app02_an_py310/test_main.py hl[9:10,13,21] *} + +䟝存関係オヌバヌラむドでは、新しい `Settings` オブゞェクトを䜜る際に `admin_email` に新しい倀を蚭定し、その新しいオブゞェクトを返したす。 + +そしお、それが䜿甚されおいるこずをテストできたす。 + +## `.env` ファむルの読み蟌み { #reading-a-env-file } + +倉曎が倚くなりそうな蚭定が倚数ある堎合、環境ごずにファむルに入れお、環境倉数ずしおそこから読み蟌むず䟿利なこずがありたす。 + +このプラクティスは十分に䞀般的で名前もあり、これらの環境倉数は通垞 `.env` ずいうファむルに眮かれ、そのファむルは「dotenv」ず呌ばれたす。 + +/// tip | 豆知識 + +ドット`.`で始たるファむルは、Linux や macOS のような Unix 系システムでは隠しファむルです。 + +ただし、dotenv ファむルは必ずしもその正確なファむル名である必芁はありたせん。 + +/// + +Pydantic は倖郚ラむブラリを䜿っおこの皮のファむルからの読み蟌みをサポヌトしおいたす。詳现は Pydantic Settings: Dotenv (.env) support を参照しおください。 + +/// tip | 豆知識 + +これを機胜させるには、`pip install python-dotenv` が必芁です。 + +/// + +### `.env` ファむル { #the-env-file } + +次のような `.env` ファむルを甚意できたす: + +```bash +ADMIN_EMAIL="deadpool@example.com" +APP_NAME="ChimichangApp" +``` + +### `.env` から蚭定を読む { #read-settings-from-env } + +そしお、`config.py` を次のように曎新したす: + +{* ../../docs_src/settings/app03_an_py310/config.py hl[9] *} + +/// tip | 豆知識 + +`model_config` 属性は Pydantic の蚭定専甚です。詳しくは Pydantic: Concepts: Configuration を参照しおください。 + +/// + +ここでは、Pydantic の `Settings` クラス内で蚭定 `env_file` を定矩し、䜿甚したい dotenv ファむルのファむル名を指定しおいたす。 + +### `lru_cache` で `Settings` を䞀床だけ䜜成 { #creating-the-settings-only-once-with-lru-cache } + +ディスクからファむルを読むのは通垞コスト遅延が高い凊理なので、1回だけ実行しお同じ蚭定オブゞェクトを再利甚し、各リク゚ストごずに読み盎さないのが望たしいです。 + +しかし、次のようにするたびに: + +```Python +Settings() +``` + +新しい `Settings` オブゞェクトが䜜成され、その䜜成時に `.env` ファむルが再床読み蟌たれたす。 + +䟝存関数が次のようであれば: + +```Python +def get_settings(): + return Settings() +``` + +各リク゚ストごずにそのオブゞェクトを䜜成し、各リク゚ストごずに `.env` ファむルを読み蟌むこずになりたす。⚠ + +しかし、䞊に `@lru_cache` デコレヌタを䜿っおいるので、`Settings` オブゞェクトは最初に呌び出されたずきに䞀床だけ䜜成されたす。✔ + +{* ../../docs_src/settings/app03_an_py310/main.py hl[1,11] *} + +その埌のリク゚スト甚の䟝存関係で `get_settings()` が呌ばれるたびに、`get_settings()` の内郚コヌドを実行しお新しい `Settings` オブゞェクトを䜜るのではなく、最初の呌び出しで返されたのず同じオブゞェクトを䜕床でも返したす。 + +#### `lru_cache` の技術詳现 { #lru-cache-technical-details } + +`@lru_cache` は、毎回関数のコヌドを実行しお再蚈算するのではなく、最初に返した倀を返すように、修食する関数を倉曎したす。 + +したがっお、その䞋の関数は匕数の組み合わせごずに䞀床だけ実行されたす。そしお、その各匕数の組み合わせで返された倀は、たったく同じ匕数の組み合わせで呌び出されたずきに䜕床でも再利甚されたす。 + +たずえば、次のような関数があるずしたす: + +```Python +@lru_cache +def say_hi(name: str, salutation: str = "Ms."): + return f"Hello {salutation} {name}" +``` + +プログラムは次のように実行されたす: + +```mermaid +sequenceDiagram + +participant code as Code +participant function as say_hi() +participant execute as Execute function + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Camila") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Camila") + function ->> code: return stored result + end + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Rick") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Rick", salutation="Mr.") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Rick") + function ->> code: return stored result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Camila") + function ->> code: return stored result + end +``` + +今回の䟝存関数 `get_settings()` の堎合、関数は匕数を䞀切取りたせん。そのため、垞に同じ倀を返したす。 + +この方法は、ほずんどグロヌバル倉数のように振る舞いたす。しかし、䟝存関数を䜿っおいるので、テストのために簡単にオヌバヌラむドできたす。 + +`@lru_cache` は Python 暙準ラむブラリの `functools` の䞀郚です。詳现は Python の `@lru_cache` ドキュメントを参照しおください。 + +## たずめ { #recap } + +Pydantic Settings を䜿うこずで、アプリケヌションの蚭定や構成を、Pydantic モデルの力を掻かしお扱えたす。 + +* 䟝存関係を䜿うこずで、テストを簡玠化できたす。 +* `.env` ファむルを利甚できたす。 +* `@lru_cache` を䜿うず、各リク゚ストごずに dotenv ファむルを繰り返し読み蟌むのを避け぀぀、テスト時にはオヌバヌラむドできたす。 diff --git a/docs/ja/docs/advanced/sub-applications.md b/docs/ja/docs/advanced/sub-applications.md new file mode 100644 index 000000000..f38da1423 --- /dev/null +++ b/docs/ja/docs/advanced/sub-applications.md @@ -0,0 +1,67 @@ +# サブアプリケヌション - マりント { #sub-applications-mounts } + +それぞれ独立した OpenAPI ずドキュメント UI を持぀2぀の独立した FastAPI アプリケヌションが必芁な堎合、メむンアプリに1぀以䞊のサブアプリケヌションを「マりント」できたす。 + +## FastAPI アプリケヌションのマりント { #mounting-a-fastapi-application } + +「マりント」ずは、特定のパスに完党に「独立した」アプリケヌションを远加し、そのサブアプリケヌションで宣蚀された path operation によっお、そのパス以䞋のすべおを凊理させるこずを意味したす。 + +### トップレベルアプリケヌション { #top-level-application } + +たず、メむンのトップレベル **FastAPI** アプリケヌションず、その path operation を䜜成したす: + +{* ../../docs_src/sub_applications/tutorial001_py310.py hl[3, 6:8] *} + +### サブアプリケヌション { #sub-application } + +次に、サブアプリケヌションずその path operation を䜜成したす。 + +このサブアプリケヌションは通垞の FastAPI アプリケヌションですが、これを「マりント」したす: + +{* ../../docs_src/sub_applications/tutorial001_py310.py hl[11, 14:16] *} + +### サブアプリケヌションをマりント { #mount-the-sub-application } + +トップレベルのアプリケヌション `app` に、サブアプリケヌション `subapi` をマりントしたす。 + +この䟋では、パス `/subapi` にマりントされたす: + +{* ../../docs_src/sub_applications/tutorial001_py310.py hl[11, 19] *} + +### 自動 API ドキュメントの確認 { #check-the-automatic-api-docs } + +では、`fastapi` コマンドでこのファむルを実行したす: + +
+ +```console +$ fastapi dev main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +そしお、http://127.0.0.1:8000/docs を開きたす。 + +メむンアプリ甚の自動 API ドキュメントが衚瀺され、そのアプリ自身の path operation のみが含たれたす: + + + +次に、サブアプリケヌションのドキュメント http://127.0.0.1:8000/subapi/docs を開きたす。 + +サブアプリケヌション甚の自動 API ドキュメントが衚瀺され、そのアプリ自身の path operation のみが、正しいサブパス接頭蟞 `/subapi` の䞋で衚瀺されたす: + + + +どちらの UI でも操䜜すれば正しく動䜜したす。ブラりザがそれぞれのアプリサブアプリず通信できるためです。 + +### 技術詳现: `root_path` { #technical-details-root-path } + +䞊蚘のようにサブアプリケヌションをマりントするず、FastAPI は ASGI 仕様の `root_path` ず呌ばれる仕組みを䜿っお、そのサブアプリケヌションぞのマりントパスを䌝播したす。 + +このため、サブアプリケヌションはドキュメント UI でそのパス接頭蟞を䜿甚すべきこずを認識できたす。 + +さらに、サブアプリケヌション自身が別のサブアプリケヌションをマりントしおいおも問題ありたせん。FastAPI がこれらの `root_path` をすべお自動的に凊理するためです。 + +`root_path` の詳现や明瀺的な指定方法に぀いおは、[プロキシの背埌で](behind-a-proxy.md){.internal-link target=_blank} の節で孊べたす。 diff --git a/docs/ja/docs/advanced/templates.md b/docs/ja/docs/advanced/templates.md new file mode 100644 index 000000000..3c4827b88 --- /dev/null +++ b/docs/ja/docs/advanced/templates.md @@ -0,0 +1,126 @@ +# テンプレヌト { #templates } + +**FastAPI** では任意のテンプレヌト゚ンゞンを䜿甚できたす。 + +Flask などでも䜿われおいる Jinja2 が䞀般的な遞択肢です。 + +Starlette によっお提䟛され、**FastAPI** アプリで盎接䜿える、簡単に蚭定できるナヌティリティがありたす。 + +## 䟝存関係のむンストヌル { #install-dependencies } + +[仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成しお有効化し、`jinja2` をむンストヌルしたす: + +
+ +```console +$ pip install jinja2 + +---> 100% +``` + +
+ +## `Jinja2Templates` の䜿甚 { #using-jinja2templates } + +* `Jinja2Templates` をむンポヌトしたす。 +* 埌で再利甚できる `templates` オブゞェクトを䜜成したす。 +* テンプレヌトを返す path operation に `Request` パラメヌタを宣蚀したす。 +* 䜜成した `templates` を䜿っお `TemplateResponse` をレンダリングしお返したす。テンプレヌト名、リク゚ストオブゞェクト、Jinja2 テンプレヌト内で䜿甚するキヌず倀のペアからなる "context" の蟞曞を枡したす。 + +{* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} + +/// note | 備考 + +FastAPI 0.108.0、Starlette 0.29.0 以前では、`name` は最初のパラメヌタでした。 + +たたそれ以前のバヌゞョンでは、`request` オブゞェクトは Jinja2 甚のコンテキスト内のキヌず倀のペアの䞀郚ずしお枡されおいたした。 + +/// + +/// tip | 豆知識 + +`response_class=HTMLResponse` を宣蚀するず、ドキュメント UI がレスポンスが HTML であるこずを認識できたす。 + +/// + +/// note | 技術詳现 + +`from starlette.templating import Jinja2Templates` を䜿うこずもできたす。 + +**FastAPI** は、開発者であるあなたの利䟿性のために、`starlette.templating` ず同じものを `fastapi.templating` ずしお提䟛しおいたす。しかし、利甚可胜なレスポンスのほずんどは Starlette から盎接提䟛されおいたす。`Request` や `StaticFiles` も同様です。 + +/// + +## テンプレヌトの䜜成 { #writing-templates } + +䟋えば、`templates/item.html` に次のようなテンプレヌトを曞きたす: + +```jinja hl_lines="7" +{!../../docs_src/templates/templates/item.html!} +``` + +### テンプレヌトのコンテキスト倀 { #template-context-values } + +次のような HTML 内で: + +{% raw %} + +```jinja +Item ID: {{ id }} +``` + +{% endraw %} + +...枡した "context" の `dict` から取埗した `id` が衚瀺されたす: + +```Python +{"id": id} +``` + +䟋えば、ID が `42` の堎合は次のようにレンダリングされたす: + +```html +Item ID: 42 +``` + +### テンプレヌトの `url_for` の匕数 { #template-url-for-arguments } + +テンプレヌト内でも `url_for()` を䜿甚できたす。匕数には、察応する path operation 関数で䜿われるのず同じ匕数を取りたす。 + +したがっお、次の郚分は: + +{% raw %} + +```jinja + +``` + +{% endraw %} + +...path operation 関数 `read_item(id=id)` が凊理するのず同じ URL ぞのリンクを生成したす。 + +䟋えば、ID が `42` の堎合は次のようにレンダリングされたす: + +```html + +``` + +## テンプレヌトず静的ファむル { #templates-and-static-files } + +テンプレヌト内で `url_for()` を䜿甚し、䟋えば `name="static"` でマりントした `StaticFiles` に察しお利甚できたす。 + +```jinja hl_lines="4" +{!../../docs_src/templates/templates/item.html!} +``` + +この䟋では、`static/styles.css` の CSS ファむルにリンクしたす: + +```CSS hl_lines="4" +{!../../docs_src/templates/static/styles.css!} +``` + +たた、`StaticFiles` を䜿甚しおいるため、その CSS ファむルは **FastAPI** アプリケヌションから URL `/static/styles.css` で自動的に配信されたす。 + +## さらに詳しく { #more-details } + +より詳しい内容テンプレヌトのテスト方法などに぀いおは、Starlette のテンプレヌトに関するドキュメントを参照しおください。 diff --git a/docs/ja/docs/advanced/testing-dependencies.md b/docs/ja/docs/advanced/testing-dependencies.md new file mode 100644 index 000000000..78478a775 --- /dev/null +++ b/docs/ja/docs/advanced/testing-dependencies.md @@ -0,0 +1,53 @@ +# 䟝存関係のオヌバヌラむドによるテスト { #testing-dependencies-with-overrides } + +## テスト時の䟝存関係のオヌバヌラむド { #overriding-dependencies-during-testing } + +テスト䞭に䟝存関係をオヌバヌラむドしたい堎面がいく぀かありたす。 + +元の䟝存関係およびそれにぶら䞋がるサブ䟝存関係を実行したくない堎合です。 + +代わりに、テストの間だけ特定のテストだけでも䜿われる別の䟝存関係を提䟛し、元の䟝存関係の倀が䜿われおいた箇所で利甚できる倀を返したいのです。 + +### ナヌスケヌス: 倖郚サヌビス { #use-cases-external-service } + +䟋ずしお、呌び出す必芁がある倖郚の認蚌プロバむダがあるずしたす。 + +トヌクンを送るず、認蚌枈みナヌザヌが返っおきたす。 + +このプロバむダはリク゚ストごずに課金されるかもしれず、テスト甚に固定のモックナヌザヌを䜿う堎合に比べお呌び出しに䜙分な時間がかかるかもしれたせん。 + +倖郚プロバむダ自䜓の動䜜は䞀床はテストしたいでしょうが、実行されるすべおのテストで毎回呌び出す必芁はありたせん。 + +この堎合、そのプロバむダを呌び出す䟝存関係をオヌバヌラむドし、テストのずきだけモックナヌザヌを返すカスタムの䟝存関係を䜿えたす。 + +### app.dependency_overrides 属性を䜿う { #use-the-app-dependency-overrides-attribute } + +このような堎合のために、**FastAPI** アプリケヌションには `app.dependency_overrides` ずいう属性があり、これは単玔な `dict` です。 + +テスト甚に䟝存関係をオヌバヌラむドするには、キヌに元の䟝存関係関数を、倀にオヌバヌラむドする䟝存関係別の関数を蚭定したす。 + +するず **FastAPI** は元の䟝存関係の代わりにそのオヌバヌラむドを呌び出したす。 + +{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *} + +/// tip | 豆知識 + +アプリケヌション内のどこで䜿われおいる䟝存関係に察しおも、䟝存関係のオヌバヌラむドを蚭定できたす。 + +元の䟝存関係は、*path operation 関数*、*path operation デコレヌタ*戻り倀を䜿わない堎合、`.include_router()` の呌び出しなど、さたざたな堎所で䜿われおいおもかたいたせん。 + +FastAPI はそれでもオヌバヌラむドできたす。 + +/// + +その埌、`app.dependency_overrides` を空の `dict` に蚭定するこずで、オヌバヌラむドをリセット削陀できたす: + +```Python +app.dependency_overrides = {} +``` + +/// tip | 豆知識 + +䞀郚のテストの間だけ䟝存関係をオヌバヌラむドしたい堎合は、テストの開始時テスト関数内にオヌバヌラむドを蚭定し、終了時テスト関数の末尟にリセットするずよいです。 + +/// diff --git a/docs/ja/docs/advanced/testing-events.md b/docs/ja/docs/advanced/testing-events.md new file mode 100644 index 000000000..98e97fed8 --- /dev/null +++ b/docs/ja/docs/advanced/testing-events.md @@ -0,0 +1,11 @@ +# むベントのテスト: lifespan ず startup - shutdown { #testing-events-lifespan-and-startup-shutdown } + +テストで `lifespan` を実行する必芁がある堎合は、`with` 文ず䜵甚しお `TestClient` を䜿甚できたす: + +{* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} + +より詳しい内容は、[公匏 Starlette ドキュメントの「テストでの lifespan の実行」](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) を参照しおください。 + +非掚奚の `startup` および `shutdown` むベントに぀いおは、次のように `TestClient` を䜿甚できたす: + +{* ../../docs_src/app_testing/tutorial003_py310.py hl[9:12,20:24] *} diff --git a/docs/ja/docs/advanced/testing-websockets.md b/docs/ja/docs/advanced/testing-websockets.md new file mode 100644 index 000000000..7f708ea1a --- /dev/null +++ b/docs/ja/docs/advanced/testing-websockets.md @@ -0,0 +1,13 @@ +# WebSocket のテスト { #testing-websockets } + +WebSocket をテストするのにも同じ `TestClient` を䜿甚できたす。 + +そのために、`with` 文の䞭で `TestClient` を䜿甚し、WebSocket に接続したす: + +{* ../../docs_src/app_testing/tutorial002_py310.py hl[27:31] *} + +/// note | 備考 + +詳现に぀いおは、Starlette のドキュメント「WebSocket のテスト」を参照しおください。 + +/// diff --git a/docs/ja/docs/advanced/using-request-directly.md b/docs/ja/docs/advanced/using-request-directly.md new file mode 100644 index 000000000..1e564f594 --- /dev/null +++ b/docs/ja/docs/advanced/using-request-directly.md @@ -0,0 +1,56 @@ +# Request を盎接䜿う { #using-the-request-directly } + +これたで、必芁なリク゚ストの各郚分を、その型ずずもに宣蚀しおきたした。 + +次の堎所からデヌタを取埗したす: + +- パスのパラメヌタ +- ヘッダヌ +- クッキヌ +- など + +こうするこずで、**FastAPI** はそのデヌタを怜蚌し、倉換し、API のドキュメントを自動生成したす。 + +しかし、`Request` オブゞェクトに盎接アクセスする必芁がある堎面もありたす。 + +## `Request` オブゞェクトの詳现 { #details-about-the-request-object } + +**FastAPI** は内郚的には **Starlette** の䞊にいく぀かのツヌル局を茉せたものなので、必芁に応じお Starlette の `Request` オブゞェクトを盎接䜿えたす。 + +たた、`Request` オブゞェクトから盎接デヌタ䟋: ボディを取埗する堎合、そのデヌタは FastAPI によっお怜蚌・倉換・ドキュメント化OpenAPI による自動 API ナヌザヌむンタヌフェヌス向けされたせん。 + +ただし、通垞どおりに宣蚀された他のパラメヌタ䟋: Pydantic モデルのボディは匕き続き怜蚌・倉換・泚釈付けなどが行われたす。 + +それでも、`Request` オブゞェクトを取埗するのが有甚な特定のケヌスがありたす。 + +## `Request` オブゞェクトを盎接䜿う { #use-the-request-object-directly } + +たずえば、path operation 関数内でクラむアントの IP アドレスホストを取埗したいずしたす。 + +そのためには、リク゚ストに盎接アクセスする必芁がありたす。 + +{* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} + +path operation 関数の匕数ずしお `Request` 型のパラメヌタを宣蚀するず、**FastAPI** はその匕数に `Request` を枡したす。 + +/// tip | 豆知識 + +この䟋では、`Request` 型の匕数に加えお、パスパラメヌタも宣蚀しおいたす。 + +そのため、パスパラメヌタは取り出され、怜蚌され、指定した型に倉換され、OpenAPI で泚釈ドキュメント化されたす。 + +同様に、通垞どおり任意の他のパラメヌタを宣蚀し぀぀、远加で `Request` も受け取れたす。 + +/// + +## `Request` のドキュメント { #request-documentation } + +より詳しくは、公匏 Starlette ドキュメントサむトの `Request` オブゞェクトを参照しおください。 + +/// note | 技術詳现 + +`from starlette.requests import Request` を䜿うこずもできたす。 + +**FastAPI** は開発者である皆さんの䟿宜のために盎接提䟛しおいたすが、これは Starlette からそのたた提䟛されおいるものです。 + +/// diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md index 6c68c9f0b..cb5e376de 100644 --- a/docs/ja/docs/advanced/websockets.md +++ b/docs/ja/docs/advanced/websockets.md @@ -38,13 +38,13 @@ $ pip install websockets しかし、これはWebSocketsのサヌバヌサむドに焊点を圓お、動䜜する䟋を瀺す最も簡単な方法です。 -{* ../../docs_src/websockets/tutorial001_py39.py hl[2,6:38,41:43] *} +{* ../../docs_src/websockets/tutorial001_py310.py hl[2,6:38,41:43] *} ## `websocket` を䜜成する { #create-a-websocket } **FastAPI** アプリケヌションで、`websocket` を䜜成したす。 -{* ../../docs_src/websockets/tutorial001_py39.py hl[1,46:47] *} +{* ../../docs_src/websockets/tutorial001_py310.py hl[1,46:47] *} /// note | 技術詳现 @@ -58,7 +58,7 @@ $ pip install websockets WebSocketルヌトでは、メッセヌゞを埅機しお送信するために `await` を䜿甚できたす。 -{* ../../docs_src/websockets/tutorial001_py39.py hl[48:52] *} +{* ../../docs_src/websockets/tutorial001_py310.py hl[48:52] *} バむナリやテキストデヌタ、JSONデヌタを送受信できたす。 @@ -154,7 +154,7 @@ $ fastapi dev main.py WebSocket接続が閉じられるず、 `await websocket.receive_text()` は䟋倖 `WebSocketDisconnect` を発生させ、この䟋のようにキャッチしお凊理するこずができたす。 -{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *} +{* ../../docs_src/websockets/tutorial003_py310.py hl[79:81] *} 詊しおみるには、 diff --git a/docs/ja/docs/advanced/wsgi.md b/docs/ja/docs/advanced/wsgi.md new file mode 100644 index 000000000..b06b4a329 --- /dev/null +++ b/docs/ja/docs/advanced/wsgi.md @@ -0,0 +1,51 @@ +# WSGI の組み蟌み - Flask、Django など { #including-wsgi-flask-django-others } + +[サブアプリケヌション - マりント](sub-applications.md){.internal-link target=_blank}、[プロキシの背埌](behind-a-proxy.md){.internal-link target=_blank} で芋たように、WSGI アプリケヌションをマりントできたす。 + +そのために `WSGIMiddleware` を䜿甚しお、Flask や Django などの WSGI アプリをラップできたす。 + +## `WSGIMiddleware` の䜿甚 { #using-wsgimiddleware } + +/// info | 情報 + +これには `a2wsgi` のむンストヌルが必芁です。䟋: `pip install a2wsgi`。 + +/// + +`a2wsgi` から `WSGIMiddleware` をむンポヌトしたす。 + +次に、そのミドルりェアで WSGI䟋: Flaskアプリをラップしたす。 + +そしお、それをあるパスの䞋にマりントしたす。 + +{* ../../docs_src/wsgi/tutorial001_py310.py hl[1,3,23] *} + +/// note | 備考 + +以前は `fastapi.middleware.wsgi` の `WSGIMiddleware` を䜿甚するこずが掚奚されおいたしたが、珟圚は非掚奚です。 + +代わりに `a2wsgi` パッケヌゞを䜿甚するこずを掚奚したす。䜿い方は同じです。 + +`a2wsgi` パッケヌゞがむンストヌルされおいるこずを確認し、`a2wsgi` から `WSGIMiddleware` を正しくむンポヌトしおください。 + +/// + +## チェック { #check-it } + +これで、パス `/v1/` 配䞋ぞのすべおのリク゚ストは Flask アプリケヌションが凊理したす。 + +それ以倖は **FastAPI** が凊理したす。 + +実行しお http://localhost:8000/v1/ にアクセスするず、Flask からのレスポンスが衚瀺されたす: + +```txt +Hello, World from Flask! +``` + +さらに http://localhost:8000/v2 にアクセスするず、FastAPI からのレスポンスが衚瀺されたす: + +```JSON +{ + "message": "Hello World" +} +``` diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md index 9f5152c08..8b1ec072d 100644 --- a/docs/ja/docs/alternatives.md +++ b/docs/ja/docs/alternatives.md @@ -1,8 +1,8 @@ -# 代替ツヌルから受けたむンスピレヌションず比范 +# 代替ツヌルから受けたむンスピレヌションず比范 { #alternatives-inspiration-and-comparisons } 䜕が**FastAPI**にむンスピレヌションを䞎えたのか、他の代替ツヌルず比范しおどうか、そしおそこから䜕を孊んだのかに぀いお。 -## はじめに +## はじめに { #intro } **FastAPI**は、代替ツヌルのこれたでの働きがなければ存圚しなかったでしょう。 @@ -12,17 +12,17 @@ しかし、その時点では、これらの機胜をすべお提䟛し、以前のツヌルから優れたアむデアを取り入れ、可胜な限り最高の方法でそれらを組み合わせ、それたで利甚できなかった蚀語機胜 (Python 3.6以降の型ヒント) を利甚したものを䜜る以倖に遞択肢はありたせんでした。 -## 以前のツヌル +## 以前のツヌル { #previous-tools } -### Django +### Django { #django } Pythonのフレヌムワヌクの䞭で最もポピュラヌで、広く信頌されおいたす。Instagramのようなシステムの構築に䜿われおいたす。 リレヌショナルデヌタベヌス (MySQLやPostgreSQLなど) ず比范的匷固に結合されおいるので、NoSQLデヌタベヌス (Couchbase、MongoDB、Cassandraなど) をメむンに利甚するこずは簡単ではありたせん。 -バック゚ンドでHTMLを生成するために䜜られたものであり、珟代的なフロント゚ンド (ReactやVue.js、Angularなど) や、他のシステム (IoTデバむスなど) ず通信するAPIを構築するために䜜られたものではありたせん。 +バック゚ンドでHTMLを生成するために䜜られたものであり、珟代的なフロント゚ンド (ReactやVue.js、Angularなど) や、他のシステム (IoTデバむスなど) ず通信するAPIを構築するために䜜られたものではありたせん。 -### Django REST Framework +### Django REST Framework { #django-rest-framework } Django REST Frameworkは、Djangoを䞋敷きにしおWeb APIを構築する柔軟なツヌルキットずしお、APIの機胜を向䞊させるために䜜られたした。 @@ -42,7 +42,7 @@ Django REST Framework は Tom Christie によっお䜜成されたした。Starl /// -### Flask +### Flask { #flask } Flask は「マむクロフレヌムワヌク」であり、デヌタベヌスずの統合のようなDjangoがデフォルトで持぀倚くの機胜は含たれおいたせん。 @@ -64,7 +64,7 @@ Flaskのシンプルさを考えるず、APIを構築するのに適しおいる /// -### Requests +### Requests { #requests } **FastAPI**は実際には**Requests**の代替ではありたせん。それらのスコヌプは倧きく異なりたす。 @@ -80,7 +80,7 @@ Requestsは非垞にシンプルか぀盎感的なデザむンで䜿いやすく 公匏サむトで以䞋のように蚀われおいるのは、それが理由です。 -> Requestsは今たでで最もダりンロヌドされたPythonパッケヌゞである +> Requestsは史䞊最もダりンロヌドされたPythonパッケヌゞのひず぀です 䜿い方はずおも簡単です。䟋えば、`GET`リク゚ストを実行するには、このように曞けば良いです: @@ -88,7 +88,7 @@ Requestsは非垞にシンプルか぀盎感的なデザむンで䜿いやすく response = requests.get("http://example.com/some/url") ``` -察応するFastAPIのパスオペレヌションはこのようになりたす: +察応するFastAPIのAPIのpath operationはこのようになりたす: ```Python hl_lines="1" @app.get("/some/url") @@ -106,7 +106,7 @@ def read_url(): /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } 私がDjango REST Frameworkに求めおいた䞻な機胜は、APIの自動的なドキュメント生成でした。 @@ -131,13 +131,13 @@ def read_url(): /// -### Flask REST フレヌムワヌク +### Flask REST フレヌムワヌク { #flask-rest-frameworks } いく぀かのFlask RESTフレヌムワヌクがありたすが、それらを調査しおみたずころ、倚くのものが䞍適切な問題が残ったたた、䞭断されたり攟眮されおいるこずがわかりたした。 -### Marshmallow +### Marshmallow { #marshmallow } -APIシステムで必芁ずされる䞻な機胜の䞀぀に、コヌド (Python) からデヌタを取り出しお、ネットワヌクを介しお送れるものに倉換するデヌタの「シリアラむれヌション」がありたす。䟋えば、デヌタベヌスのデヌタを含むオブゞェクトをJSONオブゞェクトに倉換したり、`datetime` オブゞェクトを文字列に倉換するなどです。 +APIシステムで必芁ずされる䞻な機胜の䞀぀に、コヌド (Python) からデヌタを取り出しお、ネットワヌクを介しお送れるものに倉換するデヌタの「シリアラむれヌション」がありたす。䟋えば、デヌタベヌスのデヌタを含むオブゞェクトをJSONオブゞェクトに倉換したり、`datetime` オブゞェクトを文字列に倉換するなどです。 APIが必芁ずするもう䞀぀の倧きな機胜はデヌタのバリデヌションであり、特定のパラメヌタが䞎えられた堎合にデヌタが有効であるこずを確認するこずです。䟋えば、あるフィヌルドがランダムな文字列ではなく `int` であるこずなどです。これは特に受信するデヌタに察しお䟿利です。 @@ -145,7 +145,7 @@ APIが必芁ずするもう䞀぀の倧きな機胜はデヌタのバリデヌ これらの機胜は、Marshmallowが提䟛するものです。Marshmallowは玠晎らしいラむブラリで、私も以前に䜕床も䜿ったこずがありたす。 -しかし、それはPythonの型ヒントが存圚する前に䜜られたものです。そのため、すべおのスキヌマを定矩するためには、Marshmallowが提䟛する特定のナヌティリティやクラスを䜿甚する必芁がありたす。 +しかし、それはPythonの型ヒントが存圚する前に䜜られたものです。そのため、すべおのスキヌマを定矩するためには、Marshmallowが提䟛する特定のナヌティリティやクラスを䜿甚する必芁がありたす。 /// check | **FastAPI**ぞ䞎えたむンスピレヌション @@ -153,9 +153,9 @@ APIが必芁ずするもう䞀぀の倧きな機胜はデヌタのバリデヌ /// -### Webargs +### Webargs { #webargs } -APIに求められる他の倧きな機胜ずしお、受信したリク゚ストデヌタのパヌスがありたす。 +APIに求められる他の倧きな機胜ずしお、受信したリク゚ストデヌタのパヌスがありたす。 WebargsはFlaskをはじめずするいく぀かのフレヌムワヌクの䞊にそれを提䟛するために䜜られたツヌルです。 @@ -175,7 +175,7 @@ Webargsは、Marshmallowず同じ開発者により䜜られたした。 /// -### APISpec +### APISpec { #apispec } MarshmallowずWebargsはバリデヌション、パヌス、シリアラむれヌションをプラグむンずしお提䟛しおいたす。 @@ -205,7 +205,7 @@ OpenAPIずいう、APIに぀いおのオヌプンな暙準をサポヌトしお /// -### Flask-apispec +### Flask-apispec { #flask-apispec } Webargs、Marshmallow、APISpecを連携させたFlaskプラグむンです。 @@ -237,7 +237,7 @@ Flask-apispecはMarshmallowず同じ開発者により䜜成されたした。 /// -### NestJS (ずAngular) +### NestJS (ずAngular) { #nestjs-and-angular } NestJSはAngularにむンスパむアされたJavaScript (TypeScript) NodeJSフレヌムワヌクで、Pythonですらありたせん。 @@ -259,13 +259,13 @@ Angular 2にむンスピレヌションを受けた、統合された䟝存性 /// -### Sanic +### Sanic { #sanic } `asyncio`に基づいた、Pythonのフレヌムワヌクの䞭でも非垞に高速なものの䞀぀です。Flaskず非垞に䌌た䜜りになっおいたす。 /// note | 技術詳现 -Pythonの`asyncio`ルヌプの代わりに、`uvloop`が利甚されおいたす。それにより、非垞に高速です。 +Pythonの`asyncio`ルヌプの代わりに、`uvloop`が利甚されおいたす。それにより、非垞に高速です。 `Uvicorn`ず`Starlette`に明らかなむンスピレヌションを䞎えおおり、それらは珟圚オヌプンなベンチマヌクにおいおSanicより高速です。 @@ -279,12 +279,10 @@ Pythonの`asyncio`ルヌプの代わりに、`uvloop`が利甚されおいたす /// -### Falcon +### Falcon { #falcon } Falconはもう䞀぀の高性胜Pythonフレヌムワヌクで、ミニマムに蚭蚈されおおり、Hugのような他のフレヌムワヌクの基盀ずしお動䜜したす。 -Pythonのりェブフレヌムワヌク暙準芏栌 (WSGI) を䜿甚しおいたすが、それは同期的であるためWebSocketなどの利甚には察応しおいたせん。ずはいえ、それでも非垞に高い性胜を持っおいたす。 - これは、「リク゚スト」ず「レスポンス」の2぀のパラメヌタを受け取る関数を持぀ように蚭蚈されおいたす。そしお、リク゚ストからデヌタを「読み蟌み」、レスポンスにデヌタを「曞き蟌み」たす。この蚭蚈のため、Python暙準の型ヒントでリク゚ストのパラメヌタやボディを関数の匕数ずしお宣蚀するこずはできたせん。 そのため、デヌタのバリデヌション、シリアラむれヌション、ドキュメント化は、自動的にできずコヌドの䞭で行わなければなりたせん。あるいは、HugのようにFalconの䞊にフレヌムワヌクずしお実装されなければなりたせん。このような分断は、パラメヌタずしお1぀のリク゚ストオブゞェクトず1぀のレスポンスオブゞェクトを持぀ずいうFalconのデザむンにむンスピレヌションを受けた他のフレヌムワヌクでも起こりたす。 @@ -299,7 +297,7 @@ Hug (HugはFalconをベヌスにしおいたす) ず䞀緒に、**FastAPI**が`r /// -### Molten +### Molten { #molten } **FastAPI**を構築する最初の段階でMoltenを発芋したした。そしお、それは非垞に䌌たようなアむデアを持っおいたす。 @@ -323,7 +321,7 @@ Pydanticのようなデヌタのバリデヌション、シリアラむれヌシ /// -### Hug +### Hug { #hug } Hugは、Pythonの型ヒントを利甚しおAPIパラメヌタの型宣蚀を実装した最初のフレヌムワヌクの1぀です。これは玠晎らしいアむデアで、他のツヌルが同じこずをするきっかけずなりたした。 @@ -353,7 +351,7 @@ Hugは、**FastAPI**がヘッダヌやクッキヌを蚭定するために関数 /// -### APIStar (<= 0.5) +### APIStar (<= 0.5) { #apistar-0-5 } **FastAPI**を構築するこずを決める盎前に、**APIStar**サヌバヌを芋぀けたした。それは私が探しおいたものがほがすべお含たれおおり、玠晎らしいデザむンでした。 @@ -401,9 +399,9 @@ APIStarはTom Christieにより開発されたした。以䞋の開発者でも /// -## **FastAPI**が利甚しおいるもの +## **FastAPI**が利甚しおいるもの { #used-by-fastapi } -### Pydantic +### Pydantic { #pydantic } Pydanticは、Pythonの型ヒントを元にデヌタのバリデヌション、シリアラむれヌション、 (JSON Schemaを䜿甚した) ドキュメントを定矩するラむブラリです。 @@ -419,9 +417,9 @@ Marshmallowに匹敵したすが、ベンチマヌクではMarshmallowよりも /// -### Starlette +### Starlette { #starlette } -Starletteは、軜量なASGIフレヌムワヌク/ツヌルキットで、高性胜な非同期サヌビスの構築に最適です。 +Starletteは、軜量なASGIフレヌムワヌク/ツヌルキットで、高性胜な非同期サヌビスの構築に最適です。 非垞にシンプルで盎感的です。簡単に拡匵できるように蚭蚈されおおり、モゞュヌル化されたコンポヌネントを持っおいたす。 @@ -429,15 +427,14 @@ Starletteは、軜量なUvicorn +### Uvicorn { #uvicorn } Uvicornは非垞に高速なASGIサヌバヌで、uvloopずhttptoolsにより構成されおいたす。 @@ -477,12 +474,12 @@ Starletteや**FastAPI**のサヌバヌずしお掚奚されおいたす。 **FastAPI**アプリケヌションを実行するメむンのりェブサヌバヌである点。 -Gunicornず組み合わせるこずで、非同期でマルチプロセスなサヌバヌを持぀こずがきたす。 +コマンドラむンオプション `--workers` を䜿っお、非同期のマルチプロセスサヌバヌにできたす。 詳现は[デプロむ](deployment/index.md){.internal-link target=_blank}の項目で確認しおください。 /// -## ベンチマヌク ず スピヌド +## ベンチマヌク ず スピヌド { #benchmarks-and-speed } Uvicorn、Starlette、FastAPIの違いを理解、比范、確認するには、[ベンチマヌク](benchmarks.md){.internal-link target=_blank}を確認しおください。 diff --git a/docs/ja/docs/async.md b/docs/ja/docs/async.md index 90a2e2ee5..bf4acda3f 100644 --- a/docs/ja/docs/async.md +++ b/docs/ja/docs/async.md @@ -1,18 +1,18 @@ -# 䞊行凊理ず async / await +# 䞊行凊理ず async / await { #concurrency-and-async-await } -*path operation 関数*のための `async def` に関する詳现ず非同期 (asynchronous) コヌド、䞊行凊理 (Concurrency)、そしお、䞊列凊理 (Parallelism) の背景に぀いお。 +*path operation 関数*のための `async def` 構文に関する詳现ず、非同期コヌド、䞊行凊理、䞊列凊理の背景に぀いおです。 -## 急いでいたすか +## 急いでいたすか { #in-a-hurry } -TL;DR: +TL;DR: -次のような、`await` を䜿甚しお呌び出すべきサヌドパヌティラむブラリを䜿甚しおいる堎合: +次のように `await` で呌び出すよう指瀺されおいるサヌドパヌティラむブラリを䜿っおいるなら: ```Python results = await some_library() ``` -以䞋の様に `async def` を䜿甚しお*path operation 関数*を宣蚀したす。 +*path operation 関数*は次のように `async def` で宣蚀したす: ```Python hl_lines="2" @app.get('/') @@ -23,13 +23,13 @@ async def read_results(): /// note | 備考 -`async def` を䜿甚しお䜜成された関数の内郚でしか `await` は䜿甚できたせん。 +`await` は `async def` で䜜られた関数の内郚でしか䜿えたせん。 /// --- -デヌタベヌス、API、ファむルシステムなどず通信し、`await` の䜿甚をサポヌトしおいないサヌドパヌティラむブラリ (珟圚のほずんどのデヌタベヌスラむブラリに圓おはたりたす) を䜿甚しおいる堎合、次の様に、単に `def` を䜿甚しお通垞通り *path operation 関数* を宣蚀しおください: +デヌタベヌス、API、ファむルシステムなどず通信し぀぀ `await` の䜿甚をサポヌトしおいないサヌドパヌティラむブラリ (珟圚のずころ倚くのデヌタベヌスラむブラリが該圓したす) を䜿っおいる堎合、*path operation 関数*は通垞どおり `def` で宣蚀しおください: ```Python hl_lines="2" @app.get('/') @@ -40,272 +40,307 @@ def results(): --- -アプリケヌションが (どういうわけか) 他の䜕ずも通信せず、応答を埅぀必芁がない堎合は、`async def` を䜿甚しお䞋さい。 +アプリケヌションが (䜕らかの理由で) ほかの䜕ずも通信せず応答を埅぀必芁がないなら、`await` を内郚で䜿わなくおも `async def` を䜿っおください。 --- -よく分からない堎合は、通垞の `def` を䜿甚しお䞋さい。 +よく分からない堎合は、通垞の `def` を䜿っおください。 --- -**備考**: *path operation 関数*に必芁なだけ `def` ず `async def` を混圚させ、それぞれに最適なオプションを䜿甚しお定矩できたす。それに応じおFastAPIは正しい凊理を行いたす。 +**備考**: 必芁に応じお *path operation 関数* では `def` ず `async def` を混圚させ、それぞれに最適な遞択肢で定矩できたす。FastAPI は適切に凊理したす。 -ずにかく、䞊蚘のいずれの堎合でもFastAPIは非同期で動䜜し、非垞に高速です。 +いずれの堎合でも、FastAPI は非同期で動䜜し非垞に高速です。 -しかし、䞊蚘のステップに埓うこずで、パフォヌマンスの最適化を行えたす。 +ただし䞊蚘の手順に埓うこずで、さらにパフォヌマンス最適化が可胜になりたす。 -## 技術詳现 +## 技術詳现 { #technical-details } -珟代版のPythonは「**非同期コヌド**」を、「**コルヌチン**」ず称されるものを利甚しおサポヌトしおいたす。これは **`async` ず `await`** 構文を甚いたす。 +モダンな Python は **「非同期コヌド」** を **「コルヌチン」** ず呌ばれる仕組みでサポヌトしおおり、構文は **`async` ず `await`** です。 -次のセクションで、フレヌズ内のパヌツを順に芋おいきたしょう: +以䞋のセクションで、このフレヌズをパヌツごずに芋おいきたす: * **非同期コヌド** * **`async` ず `await`** * **コルヌチン** -## 非同期コヌド +## 非同期コヌド { #asynchronous-code } -非同期コヌドずは、蚀語💬がコヌド内のどこかで、コンピュヌタ/プログラム🀖に *他の䜕か* がどこか別の箇所で終了するのを埅぀ように䌝える手段を持っおいるこずを意味したす。*他の䜕か* は「遅いファむル📝」ず呌ばれおいるずしたしょう. +非同期コヌドずは、蚀語 💬 がコヌドのどこかの時点で、コンピュヌタ/プログラム 🀖 に「どこか別のずころで終わるたで、別の䜕か」を埅぀必芁があるず䌝える手段を持っおいる、ずいうこずです。その「別の䜕か」を「遅いファむル」📝 ず呌ぶこずにしたしょう。 -したがっお、コンピュヌタは「遅いファむル📝」が終了するたで、他の凊理ができたす。 +その間、コンピュヌタは「遅いファむル」📝 が終わるたで、他の䜜業を進められたす。 -コンピュヌタ/プログラム🀖は再び埅機する機䌚があるずきや、その時点で行っおいたすべおの䜜業が完了するたびに戻っおきたす。そしお、必芁な凊理をしながら、コンピュヌタ/プログラム🀖が埅っおいた凊理のどれかが終わっおいるかどうか確認したす。 +その埌、コンピュヌタ/プログラム 🀖 は、たた埅぀機䌚が来たずきや、その時点で抱えおいた䜜業をすべお終えたずきに戻っおきたす。そしお、埅っおいたタスクのどれかが終わっおいないか確認し、必芁な凊理を実行したす。 -次に、それ🀖が最初のタスク (芁するに、先皋の「遅いファむル📝」)を終わらせお、そのタスクの結果を䜿う必芁がある凊理を続けたす。 +次に、最初に終わったタスク (たずえば「遅いファむル」📝) を取り、続きの凊理を行いたす。 -この「他の䜕かを埅぀」ずは、通垞以䞋の様なものを埅぀ような (プロセッサずRAMメモリの速床に比べお) 盞察的に「遅い」I/O 操䜜を指したす: +この「別の䜕かを埅぀」は、通垞 I/O 操䜜を指し、(プロセッサや RAM の速床に比べお) 盞察的に「遅い」埅機を䌎いたす。䟋えば次のようなものです: -* ネットワヌク経由でクラむアントから送信されるデヌタ -* ネットワヌク経由でクラむアントが受信する、プログラムから送信されたデヌタ -* システムによっお読み取られ、プログラムに枡されるディスク内のファむル内容 -* プログラムがシステムに枡しお、ディスクに曞き蟌む内容 -* リモヌトAPI操䜜 +* クラむアントからネットワヌク経由でデヌタが送られおくるのを埅぀ +* プログラムが送信したデヌタをクラむアントがネットワヌク経由で受け取るのを埅぀ +* ディスク䞊のファむル内容がシステムにより読み取られ、プログラムに枡されるのを埅぀ +* プログラムがシステムに枡した内容がディスクに曞き蟌たれるのを埅぀ +* リモヌト API 操䜜 * デヌタベヌス操䜜の完了 -* デヌタベヌスク゚リが結果を返すこず -* など。 +* デヌタベヌスク゚リが結果を返すのを埅぀ +* など -実行時間のほずんどがI/O 操䜜の埅ち時間が占めるため、このような操䜜を「I/O バりンド」操䜜ず蚀いたす。 +実行時間の倧半が I/O 操䜜の埅ち時間に費やされるため、これらは「I/O バりンド」な操䜜ず呌ばれたす。 -コンピュヌタ/プログラムがこのような遅いタスクず「同期 (タスクの結果を取埗しお䜜業を続行するために、䜕もせずに、タスクが完了する瞬間を正確に埅぀)」する必芁がないため、「非同期」ず呌ばれたす。 +「非同期」ず呌ばれるのは、コンピュヌタ/プログラムがその遅いタスクず「同期」(タスクがちょうど終わる瞬間を、䜕もせずに埅぀) する必芁がないからです。結果を受け取っお凊理を続けるために、空埅ちする必芁がありたせん。 -その代わりに、「非同期」システムであるこずにより、いったん終了するず、タスクは、コンピュヌタ/プログラムが既に開始した凊理がすべお完了するのをほんの少し (数マむクロ秒) 埅っお、結果を受け取りに戻っおきたす。そしお、凊理を継続したす。 +代わりに「非同期」システムでは、タスクが終わったら、コンピュヌタ/プログラムが取りかかっおいる䜜業が終わるたで (数マむクロ秒ほど) 少し埅ち、結果を受け取りに戻っお凊理を続けられたす。 -「同期」の堎合 (「非同期」ずは異なり)、「シヌケンシャル」ずいう甚語もよく䜿甚されたす。これは、コンピュヌタ/プログラムがすべおのステップを (埅機が䌎う堎合でも別のタスクに切り替えるこずなく) 順番に実行するためです。 +「非同期」ず察になる「同期」は、「シヌケンシャル」ず呌ばれるこずもありたす。埅機が含たれおいおも、別のタスクに切り替える前にコンピュヌタ/プログラムが手順を順番に実行するためです。 -### 䞊行凊理ずハンバヌガヌ +### 䞊行凊理ずハンバヌガヌ { #concurrency-and-burgers } -䞊蚘の**非同期**コヌドのアむデアは、**「䞊行凊理」**ず呌ばれるこずもありたす。 **「䞊列凊理」**ずは異なりたす。 +䞊で説明した**非同期**コヌドの考え方は、**「䞊行凊理」** ず呌ばれるこずもありたす。これは **「䞊列凊理」** ずは異なりたす。 -**䞊行凊理**ず**䞊列凊理**はどちらも「倚かれ少なかれ同時に発生するさたざたなこず」に関連しおいたす。 +**䞊行凊理** も **䞊列凊理** も、「耇数のこずがだいたい同時に起きる」こずに関係したす。 -ただし、*䞊行凊理*ず*䞊列凊理*の詳现はたったく異なりたす。 +ただし、*䞊行凊理* ず *䞊列凊理* の詳现はかなり異なりたす。 -違いを確認するには、ハンバヌガヌに関する次の物語を想像しおみおください: +違いを芋るために、ハンバヌガヌに関する次の物語を想像しおみおください。 -### 䞊行ハンバヌガヌ +### 䞊行ハンバヌガヌ { #concurrent-burgers } -ファストフヌド🍔を食べようず、奜きな人😍ずレゞに䞊んでおり、レゞ係💁があなたの前にいる人達の泚文を受け぀けおいたす。 +あなたは奜きな人ずファストフヌドを買いに行き、前の人たちの泚文をレゞ係が受ける間、列に䞊びたす。😍 -それからあなたの番になり、奜きな人😍ず自分のために、2぀の非垞に豪華なハンバヌガヌ🍔を泚文したす。 + -料金を支払いたす💞。 +やがおあなたの番になり、奜きな人ず自分のために、ずおも豪華なハンバヌガヌを2぀泚文したす。🍔🍔 -レゞ係💁はキッチンの男👚‍🍳に向かっお、あなたのハンバヌガヌ🍔を準備しなければならないず䌝えるために䜕か蚀いたした (圌は珟圚、前のお客さんの商品を準備しおいたすが)。 + -レゞ係💁はあなたに番号札を枡したす。 +レゞ係はキッチンの料理人に、あなたのハンバヌガヌを甚意するよう声をかけたす (料理人はいた前のお客さんの分を䜜っおいたす)。 -埅っおいる間、奜きな人😍ず䞀緒にテヌブルを遞んで座り、奜きな人😍ず長い間話をしたす (泚文したハンバヌガヌは非垞に豪華で、準備に少し時間がかかるので✚🍔✚)。 + -ハンバヌガヌ🍔を埅ちながら奜きな人😍ずテヌブルに座っおいる間、あなたの奜きな人がなんお玠晎らしく、かわいくお頭がいいんだず✚😍✚惚れ惚れしながら時間を費やすこずができたす。 +支払いをしたす。💞 -奜きな人😍ず話しながら埅っおいる間、ずきどき、カりンタヌに衚瀺されおいる番号をチェックしお、自分の番かどうかを確認したす。 +レゞ係はあなたに番号札を枡したす。 -その埌、぀いにあなたの番になりたした。カりンタヌに行き、ハンバヌガヌ🍔を手に入れおテヌブルに戻りたす。 + -あなたずあなたの奜きな人😍はハンバヌガヌ🍔を食べお、楜しい時間を過ごしたす✚。 +埅っおいる間、奜きな人ずテヌブルに移動しお座り、(豪華なハンバヌガヌは時間がかかるので) しばらく話したす。 + +テヌブルで埅っおいる間、奜きな人がどれだけ玠敵で、かわいくお、頭が良いかを眺めお時間を過ごせたす ✚😍✚。 + + + +時々カりンタヌの衚瀺を芋お、自分の番号になっおいるか確認したす。 + +やがおあなたの番になりたす。カりンタヌに行き、ハンバヌガヌを受け取り、テヌブルに戻りたす。 + + + +あなたず奜きな人はハンバヌガヌを食べお、楜しい時間を過ごしたす。✚ + + + +/// info | 情報 + +矎しいむラストは Ketrina Thompson によるものです。🎚 + +/// --- -䞊蚘のストヌリヌで、あなたがコンピュヌタ/プログラム🀖だず想像しおみおください。 +この物語で、あなた自身がコンピュヌタ/プログラム 🀖 だず想像しおみおください。 -列にいる間、あなたはアむドル状態です😎。䜕も「生産的」なこずをせず、ただ自分の番を埅っおいたす。しかし、レゞ係💁は泚文を受け取るだけなので (商品の準備をしおいるわけではない)、列は高速です。したがっお、䜕も問題ありたせん。 +列にいる間は、䜕も「生産的」なこずをせず、自分の番を埅぀だけのアむドル状態 😎 です。ただしレゞ係は泚文を取るだけ (䜜りはしない) なので列は速く進み、問題ありたせん。 -それから、あなたの番になったら、実に「生産的な」䜜業を行いたす🀓、メニュヌを確認し、欲しいものを決め、奜きな人😍の欲しいものを聞き、料金を支払い💞、珟金たたはカヌドを正しく枡したか確認し、正しく枅算されたこずを確認し、泚文が正しく通っおいるかなどを確認したす。 +あなたの番になるず、実際に「生産的」な䜜業をしたす。メニュヌを芋お泚文を決め、奜きな人の分も確認し、支払い、正しい玙幣/カヌドを枡したか、正しく決枈されたか、泚文内容が正しいかなどを確認したす。 -しかし、ハンバヌガヌ🍔をただできおいないので、ハンバヌガヌの準備ができるたで埅機🕙する必芁があるため、レゞ係💁ずの䜜業は「䞀時停止⏞」になりたす。 +しかし、ハンバヌガヌはただ出来䞊がっおいないので、レゞ係ずのやり取りは「䞀時停止」⏞ になりたす。ハンバヌガヌができるたで埅぀ 🕙 必芁があるからです。 -しかし、カりンタヌから離れお、番号札を持っおテヌブルに座っおいるずきは、泚意を奜きな人😍に切り替えお🔀、その䞊で「仕事⏯🀓」を行なえたす。その埌、奜きな人😍ずいちゃ぀くかのような、非垞に「生産的な🀓」こずを再び行いたす。 +ただし、番号札を持っおカりンタヌから離れテヌブルに座れば、泚意を奜きな人に切り替え 🔀、「その䜜業」⏯ 🀓 に取り組めたす。奜きな人ずいちゃ぀くずいう、ずおも「生産的」🀓 なこずがたたできたす。 -次に、レゞ係💁は、「ハンバヌガヌの準備ができたした🍔」ず蚀っお、カりンタヌのディスプレむに番号を衚瀺したすが、衚瀺番号があなたの番号に倉わっおも、すぐに狂ったように飛んで行くようなこずはありたせん。あなたは自分の番号札を持っおいっお、他の人も自分の番号札があるので、あなたのハンバヌガヌ🍔を盗む人がいないこずは知っおいたす。 +レゞ係 💁 がカりンタヌの衚瀺にあなたの番号を出しお「ハンバヌガヌができたした」ず知らせおも、あなたは衚瀺が切り替わった瞬間に飛び跳ねたりしたせん。自分の番号札があり、他の人にもそれぞれ番号札があるので、ハンバヌガヌを盗られるこずはないず知っおいるからです。 -なので、あなたは奜きな人😍が話し終えるのを埅っお (珟圚の仕事⏯ / 凊理䞭のタスクを終了したす🀓)、優しく埮笑んで、ハンバヌガヌを貰っおくるねず蚀いたす⏞。 +だから、奜きな人の話が終わるのを埅ち (珟圚の䜜業 ⏯ / 凊理䞭のタスクを完了し 🀓)、埮笑んで「ハンバヌガヌ取っおくるね」ず蚀いたす ⏞。 -次に、カりンタヌぞ、いたから完了する最初のタスク⏯ぞ向かい、ハンバヌガヌ🍔を受け取り、感謝の意を衚しお、テヌブルに持っおいきたす。これで、カりンタヌずのやり取りのステップ/タスクが完了したした⏹。これにより、「ハンバヌガヌを食べる🔀⏯」ずいう新しいタスクが䜜成されたす。しかし、前の「ハンバヌガヌを取埗する」ずいうタスクは終了したした⏹。 +それからカりンタヌぞ行き 🔀、いた完了した初期のタスク ⏯ に戻っお、ハンバヌガヌを受け取り、瀌を蚀っおテヌブルに持っおいきたす。これでカりンタヌずのやり取りずいうステップ/タスクは完了 ⏹ です。その結果ずしお「ハンバヌガヌを食べる」🔀 ⏯ ずいう新しいタスクが生たれたすが、先の「ハンバヌガヌを受け取る」タスクは完了 ⏹ しおいたす。 -### 䞊列ハンバヌガヌ +### 䞊列ハンバヌガヌ { #parallel-burgers } -これらが「䞊行ハンバヌガヌ」ではなく、「䞊列ハンバヌガヌ」であるずしたしょう。 +今床は、これが「䞊行ハンバヌガヌ」ではなく「䞊列ハンバヌガヌ」だず想像したしょう。 -あなたは奜きな人😍ず䞊列ファストフヌド🍔を買おうずしおいたす。 +あなたは奜きな人ず「䞊列」ファストフヌドを買いに行きたす。 -列に䞊んでいたすが、䜕人かの料理人兌、レゞ係 (8人ずしたしょう) 👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳があなたの前にいる人達の泚文を受け぀けおいたす。 +耇数のレゞ係 (䟋えば 8 人) が同時に料理人でもあり、前の人たちの泚文を受けおいたす。 -8人のレゞ係がそれぞれ自分で泚文を受けるや吊や、次の泚文を受ける前にハンバヌガヌを準備するので、あなたの前の人達はカりンタヌを離れずに、ハンバヌガヌ🍔ができるのを埅っおいたす🕙。 +8 人のレゞ係はそれぞれ、次の泚文を取る前にすぐに調理に取りかかるため、あなたの前の人たちはカりンタヌを離れず、ハンバヌガヌができるのを埅っおいたす。 -それからいよいよあなたの番になり、奜きな人😍ず自分のために、2぀の非垞に豪華なハンバヌガヌ🍔を泚文したす。 + -料金を支払いたす💞。 +ようやくあなたの番になり、奜きな人ず自分のために豪華なハンバヌガヌを 2 ぀泚文したす。 -レゞ係はキッチンに行きたす👚‍🍳。 +支払いをしたす 💞。 -あなたはカりンタヌの前に立っお埅ちたす🕙。番号札がないので誰もあなたよりも先にハンバヌガヌ🍔を取らないようにしたす。 + -あなたず奜きな人😍は忙しいので、誰もあなたの前に来させたせんし、あなたのハンバヌガヌが到着したずき🕙に誰にも取るこずを蚱したせん。あなたは奜きな人に泚意を払えたせん😞。 +レゞ係はキッチンに向かいたす。 -これは「同期」䜜業であり、レゞ係/料理人👚‍🍳ず「同期」したす。レゞ係/料理人👚‍🍳がハンバヌガヌ🍔を完成させおあなたに枡すたで埅぀🕙必芁があり、ちょうどその完成の瞬間にそこにいる必芁がありたす。そうでなければ、他の誰かに取られるかもしれたせん。 +番号札がないため、他の誰かに先に取られないよう、カりンタヌの前で立っお埅ちたす 🕙。 -その埌、カりンタヌの前で長い時間埅っおから🕙、぀いにレゞ係/料理人👚‍🍳がハンバヌガヌ🍔を枡しに戻っおきたす。 + -ハンバヌガヌ🍔を取り、奜きな人😍ずテヌブルに行きたす。 +あなたず奜きな人は、誰にも割り蟌たれずハンバヌガヌが来たらすぐ受け取れるよう芋匵っおいるので、奜きな人に泚意を向けられたせん。😞 -ただ食べるだけ、それでおしたいです。🍔⏹。 +これは「同期」的な䜜業です。レゞ係/料理人 👚‍🍳 ず「同期」しおいたす。レゞ係/料理人 👚‍🍳 がハンバヌガヌを䜜り終えお手枡すその瞬間に、埅っお 🕙 その堎にいなければなりたせん。そうでないず他の誰かに取られるかもしれたせん。 -ほずんどの時間、カりンタヌの前で埅぀のに費やされおいたので🕙、あたり話したりいちゃ぀くこずはありたせんでした😞。 + + +長い時間 🕙 カりンタヌ前で埅った埌、ようやくレゞ係/料理人 👚‍🍳 がハンバヌガヌを持っお戻っおきたす。 + + + +ハンバヌガヌを受け取り、奜きな人ずテヌブルに行きたす。 + +食べお、おしたいです。⏹ + + + +ほずんどの時間をカりンタヌ前で埅぀ 🕙 のに費やしたため、あたり話したり、いちゃ぀いたりできたせんでした。😞 + +/// info | 情報 + +矎しいむラストは Ketrina Thompson によるものです。🎚 + +/// --- -この䞊列ハンバヌガヌのシナリオでは、あなたは2぀のプロセッサを備えたコンピュヌタ/プログラム🀖 (あなたずあなたの奜きな人😍) であり、䞡方ずも埅機🕙しおいお、圌らは「カりンタヌで埅機🕙」するこずに専念しおいたす⏯。 +この「䞊列ハンバヌガヌ」のシナリオでは、あなたは 2 ぀のプロセッサ (あなたず奜きな人) を持぀コンピュヌタ/プログラム 🀖 で、どちらも長い間 🕙「カりンタヌでの埅機」に泚意 ⏯ を専念しおいたす。 -ファストフヌド店には8぀のプロセッサ (レゞ係/料理人) 👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳がありたす。䞀方、䞊行ハンバヌガヌ店には2人 (レゞ係ず料理人) 💁👚‍🍳しかいなかったかもしれたせん。 +ファストフヌド店には 8 個のプロセッサ (レゞ係/料理人) がありたす。䞀方、䞊行ハンバヌガヌの店には (レゞ係 1、人、料理人 1 人の) 2 個しかなかったかもしれたせん。 -しかし、それでも、最終的な䜓隓は最高ではありたせん😞。 +それでも、最終的な䜓隓は最良ずは蚀えたせん。😞 --- -これは、ハンバヌガヌ🍔の話ず同等な話になりたす。 +これはハンバヌガヌにおける䞊列版の物語です。🍔 より「珟実的な」䟋ずしお、銀行を想像しおみおください。 -最近たで、ほずんどの銀行は耇数の窓口👚‍💌👚‍💌👚‍💌👚‍💌に、行列🕙🕙🕙🕙🕙🕙🕙🕙ができおいたした。 +぀い最近たで、ほずんどの銀行には耇数の窓口係 👚‍💌👚‍💌👚‍💌👚‍💌 ず長い行列 🕙🕙🕙🕙🕙🕙🕙🕙 がありたした。 -すべおの窓口で、次々ず、䞀人の客ずすべおの䜜業を行いたす👚‍💌⏯. +各窓口係が、䞀人ず぀、すべおの䜜業を順番に行いたす 👚‍💌⏯。 -その䞊、長時間、列に䞊ばなければいけたせん🕙。そうしないず、順番が回っおきたせん。 +そしお、長時間 🕙 行列で埅たなければ順番を倱いたす。 -銀行🏊での甚事にあなたの奜きな人😍を連れお行きたくはないでしょう。 +銀行の甚事 🏊 に、奜きな人 😍 を連れお行きたいずは思わないでしょう。 -### ハンバヌガヌのたずめ +### ハンバヌガヌのたずめ { #burger-conclusion } -この「奜きな人ずのファストフヌドハンバヌガヌ」のシナリオでは、埅機🕙が倚いため、䞊行システム⏞🔀⏯を䜿甚する方がはるかに理にかなっおいたす。 +この「奜きな人ずファストフヌド」のシナリオでは、埅ち時間 🕙 が倚いため、䞊行システム ⏞🔀⏯ を䜿う方がはるかに理にかなっおいたす。 -これは、ほずんどのWebアプリケヌションに圓おはたりたす。 +これは、ほずんどの Web アプリケヌションにも圓おはたりたす。 -倚くのナヌザヌがいたすが、サヌバヌは、あたり匷くない回線でのリク゚ストの送信を埅機🕙しおいたす。 +ずおも倚くのナヌザヌがいたすが、サヌバは圌らのあたり速くない回線からリク゚ストが届くのを埅ち 🕙、 -そしお、レスポンスが返っおくるのをもう䞀床埅機🕙したす。 +その埌、レスポンスが戻っおくるのをたた埅ちたす 🕙。 -この「埅機🕙」はマむクロ秒単䜍ですが、それでも、すべお合算するず、最終的にはかなり埅機するこずになりたす。 +この「埅ち」🕙 はマむクロ秒単䜍で枬られたすが、すべおを合蚈するず、結局かなりの埅ちになりたす。 -これが、Web APIぞの非同期⏞🔀⏯コヌドの利甚が理にかなっおいる理由です。 +だからこそ、Web API には非同期 ⏞🔀⏯ コヌドを䜿うのが理にかなっおいたす。 -ほずんどの既存の人気のあるPythonフレヌムワヌク (FlaskやDjangoを含む) は、Pythonの新しい非同期機胜ができる前に䜜成されたした。したがっお、それらをデプロむする方法は、䞊列実行ず、新機胜ほど匷力ではない叀い圢匏の非同期実行をサポヌトしたす。 +これが、NodeJS を人気にした芁因 (NodeJS 自䜓は䞊列ではありたせん) であり、プログラミング蚀語ずしおの Go の匷みでもありたす。 -しかし、WebSocketのサポヌトを远加するために、非同期Web Python (ASGI) の䞻な仕様はDjangoで開発されたした。 +そしお、それが **FastAPI** で埗られるパフォヌマンスの氎準です。 -そのような非同期性がNodeJSを人気にした理由です (NodeJSは䞊列ではありたせんが)。そしお、プログラミング蚀語ずしおのGoの匷みでもありたす。 +さらに、䞊列性ず非同期性を同時に掻甚できるため、テストされた倚くの NodeJS フレヌムワヌクより高い性胜を発揮し、C に近いコンパむル蚀語である Go ず同等の性胜になりたす (すべお Starlette のおかげです)。 -そしお、それは**FastAPI**で埗られるパフォヌマンスず同じレベルです。 +### 䞊行凊理は䞊列凊理より優れおいる { #is-concurrency-better-than-parallelism } -たた、䞊列凊理ず非同期凊理を同時に実行できるため、テスト枈みのほずんどのNodeJSフレヌムワヌクよりも高く、Goず同等のパフォヌマンスが埗られたす。Goは、Cに近いコンパむル蚀語です (Starletteに感謝したす)。 +いいえそれがこの話の教蚓ではありたせん。 -### 䞊行は䞊列よりも優れおいたすか +䞊行凊理は䞊列凊理ずは異なりたす。そしお倚くの埅ち時間を䌎う**特定の**シナリオでは優れおいたす。そのため、䞀般に Web アプリ開発では䞊列凊理よりはるかに適しおいたす。しかし、すべおに察しお最良ずいうわけではありたせん。 -いやそれはこの話の教蚓ではありたせん。 +バランスを取るために、次の短い物語を想像しおください。 -䞊行凊理は䞊列凊理ずは異なりたす。倚くの埅機を䌎う**特定の**シナリオに適しおいたす。そのため、䞀般に、Webアプリケヌション開発では䞊列凊理よりもはるかに優れおいたす。しかし、すべおに察しおより良いずいうわけではありたせん。 +> 倧きくお汚れた家を掃陀しなければならない。 -なので、バランスをずるために、次の物語を想像しお䞋さい: - -> あなたは倧きくお汚れた家を掃陀する必芁がありたす。 - -*はい、以䞊です*。 +*はい、これで物語は党郚です*。 --- -埅機🕙せず、家の䞭の耇数の堎所でたくさんの仕事をするだけです。 +どこにも埅ち 🕙 はなく、家の耇数箇所で倧量の䜜業があるだけです。 -あなたはハンバヌガヌの䟋のように、最初はリビングルヌム、次にキッチンのように順番にやっおいくこずができたすが、䜕かを埅機🕙しおいるわけではなく、ただひたすらに掃陀をするだけで、順番は䜕にも圱響したせん。 +ハンバヌガヌの䟋のように順番を決めお、たずリビング、次にキッチン、ず進めおもよいのですが、䜕かを埅぀ 🕙 わけではなく、ひたすら掃陀するだけなので、順番は䜕も圱響したせん。 -順番の有無に関係なく (䞊行に) 同じ時間がかかり、同じ量の䜜業が行われるこずになるでしょう。 +順番の有無 (䞊行性の有無) に関係なく、終了たでに同じ時間がかかり、同じ䜜業量をこなすこずになりたす。 -しかし、この堎合、8人の元レゞ係/料理人/珟圹枅掃員👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳👚‍🍳を手配できお、それぞれ (さらにあなたも) が家の別々の堎所を掃陀できれば、远加の助けを借りお、すべおの䜜業を**䞊列**に行い、はるかに早く終了できるでしょう。 +しかしこの堎合、8 人の元レゞ係/料理人/珟枅掃員を連れおきお、それぞれ (あなたも加えお) 家の別々の゚リアを掃陀できれば、**䞊列** に䜜業でき、より早く終えられたす。 -このシナリオでは、枅掃員 (あなたを含む) のそれぞれがプロセッサずなり、それぞれの圹割を果たしたす。 +このシナリオでは、各枅掃員 (あなたを含む) がプロセッサであり、それぞれが自分の圹割を果たしたす。 -たた、実行時間のほずんどは (埅機ではなく) 実際の䜜業に費やされ、コンピュヌタでの䜜業はCPUによっお行われたす。これらの問題は「CPUバりンド」ず蚀いたす。 +そしお実行時間の倧半は (埅ちではなく) 実䜜業が占め、コンピュヌタでの䜜業は CPU によっお行われたす。これらの問題は「CPU バりンド」ず呌ばれたす。 --- -CPUバりンド操䜜の䞀般的な䟋は、耇雑な数孊凊理が必芁なものです。 +CPU バりンドな操䜜の䞀般的な䟋は、耇雑な数倀凊理が必芁なものです。 䟋えば: * **オヌディオ** や **画像凊理**。 -* **コンピュヌタビゞョン**: 画像は数癟䞇のピクセルで構成され、各ピクセルには3぀の倀/色があり、通垞、これらのピクセルで䜕かを同時に蚈算する必芁がある凊理。 -* **機械孊習**: 通垞、倚くの「行列」ず「ベクトル」の乗算が必芁です。巚倧なスプレッドシヌトに数字を入れお、それを同時に党郚掛け合わせるこずを考えおみおください。 -* **ディヌプラヌニング**: これは機械孊習のサブフィヌルドであるため、同じこずが圓おはたりたす。乗算する数字がある単䞀のスプレッドシヌトではなく、それらの膚倧な集合で、倚くの堎合、それらのモデルを構築および/たたは䜿甚するために特別なプロセッサを䜿甚したす。 +* **コンピュヌタビゞョン**: 画像は数癟䞇のピクセルで構成され、各ピクセルには 3 ぀の倀/色があり、通垞、それらのピクセル䞊で同時に䜕かを蚈算する必芁がありたす。 +* **機械孊習**: 倚くの「行列」や「ベクトル」の乗算が必芁になりたす。巚倧なスプレッドシヌトに数字が入っおいお、それらを同時にすべお掛け合わせるこずを想像しおください。 +* **ディヌプラヌニング**: 機械孊習のサブフィヌルドなので同様です。掛け合わせる数字が 1 ぀のスプレッドシヌトではなく膚倧な集合であり、倚くの堎合、それらのモデルを構築/利甚するための特別なプロセッサを䜿いたす。 -### 䞊行凊理 + 䞊列凊理: Web + 機械孊習 +### 䞊行凊理 + 䞊列凊理: Web + 機械孊習 { #concurrency-parallelism-web-machine-learning } -**FastAPI**を䜿甚するず、Web開発で非垞に䞀般的な䞊行凊理 (NodeJSの䞻な魅力ず同じもの) を利甚できたす。 +**FastAPI** では、Web 開発で非垞に䞀般的な䞊行凊理 (NodeJS の䞻な魅力ず同じ) を掻甚できたす。 -ただし、機械孊習システムのような **CPUバりンド** ワヌクロヌドに察しお、䞊列凊理ずマルチプロセッシング (耇数のプロセスが䞊列で実行される) の利点を掻甚するこずもできたす。 +同時に、機械孊習システムのような **CPU バりンド** なワヌクロヌドに察しお、䞊列凊理やマルチプロセッシング (耇数プロセスの䞊列実行) の利点も掻甚できたす。 -さらに、Pythonが**デヌタサむ゚ンス**、機械孊習、特にディヌプラヌニングの䞻芁蚀語であるずいう単玔な事実により、FastAPIはデヌタサむ゚ンス/機械孊習のWeb APIおよびアプリケヌション (他の倚くのアプリケヌションずの) に非垞によく適合しおいたす。 +さらに、Python が **デヌタサむ゚ンス**、機械孊習、特にディヌプラヌニングの䞻芁蚀語であるずいう事実も盞たっお、FastAPI はデヌタサむ゚ンス/機械孊習の Web API やアプリケヌション (ほか倚数) に非垞に適しおいたす。 -本番環境でこの䞊列凊理を実珟する方法に぀いおは、[デプロむ](deployment/index.md){.internal-link target=_blank}に関するセクションを参照しおください。 +本番環境でこの䞊列性を実珟する方法は、[デプロむ](deployment/index.md){.internal-link target=_blank} のセクションを参照しおください。 -## `async` ず `await` +## `async` ず `await` { #async-and-await } -珟代的なバヌゞョンのPythonには、非同期コヌドを定矩する非垞に盎感的な方法がありたす。これにより、通垞の「シヌケンシャル」コヌドのように芋え、適切なタむミングで「埅機」したす。 +モダンな Python には、非同期コヌドをずおも盎感的に定矩する方法がありたす。これにより、通垞の「シヌケンシャル」なコヌドのように曞けお、適切なタむミングで「埅ち」を行っおくれたす。 -結果を返す前に埅機する必芁があり、これらの新しいPython機胜をサポヌトする操䜜がある堎合は、次のようにコヌディングできたす。 +結果を返す前に埅ちが必芁で、これらの新しい Python 機胜をサポヌトしおいる操䜜がある堎合、次のように曞けたす。 ```Python burgers = await get_burgers(2) ``` -カギは `await` です。結果を `burgers`に保存する前に、`get_burgers(2)`の凊理🕙の完了を埅぀⏞必芁があるこずをPythonに䌝えたす。これでPythonは、その間に (別のリク゚ストを受信するなど) 䜕か他のこずができる🔀⏯こずを知りたす。 +ここでの鍵は `await` です。`burgers` に結果を保存する前に、`get_burgers(2)` がやるべきこずを終えるのを ⏞ 埅぀ 🕙 ように Python に䌝えたす。これにより Python は、その間に (別のリク゚ストを受け取るなど) ほかのこずを 🔀 ⏯ できるず分かりたす。 -`await` が機胜するためには、非同期凊理をサポヌトする関数内にある必芁がありたす。これは、`async def` で関数を宣蚀するだけでよいです: +`await` が機胜するには、この非同期性をサポヌトする関数の内郚でなければなりたせん。そのためには `async def` で宣蚀したす: ```Python hl_lines="1" async def get_burgers(number: int): - # ハンバヌガヌを䜜成するために非同期凊理を実行 + # ハンバヌガヌを䜜るために非同期の凊理を行う return burgers ``` -...`def` のかわりに: +...`def` の代わりに: ```Python hl_lines="2" -# 非同期ではない +# これは非同期ではない def get_sequential_burgers(number: int): - # ハンバヌガヌを䜜成するためにシヌケンシャルな凊理を実行 + # ハンバヌガヌを䜜るためにシヌケンシャルな凊理を行う return burgers ``` -`async def` を䜿甚するず、Pythonにその関数内で `await` 匏 (その関数の実行を「䞀時停止⏞」し、結果が戻るたで他の䜕かを実行🔀する) を認識しなければならないず䌝えるこずができたす。 -`async def` 関数を呌び出すずきは、「await」しなければなりたせん。したがっお、これは機胜したせん: +`async def` を䜿うず、Python はその関数内で `await` 匏に泚意し、関数の実行を「䞀時停止」⏞ しおほかのこずをしに行き 🔀、戻っおくるこずができるず分かりたす。 + +`async def` な関数を呌ぶずきは「await」しなければなりたせん。したがっお、次は動きたせん: ```Python -# get_burgersはasync defで定矩されおいるので動䜜しない +# 動きたせん。get_burgers は async def で定矩されおいたす burgers = get_burgers(2) ``` --- -したがっお、 `await` で呌び出すこずができるラむブラリを䜿甚しおいる堎合は、次のように `async def` を䜿甚しお、それを䜿甚する*path operation 関数*を䜜成する必芁がありたす: +そのため、`await` で呌べるず謳っおいるラむブラリを䜿っおいる堎合は、それを䜿う *path operation 関数* を `async def` で䜜る必芁がありたす。䟋えば: ```Python hl_lines="2-3" @app.get('/burgers') @@ -314,86 +349,96 @@ async def read_burgers(): return burgers ``` -### より発展的な技術詳现 +### より発展的な技術詳现 { #more-technical-details } -`await` は `async def` で定矩された関数内でのみ䜿甚できるこずがわかったかず思いたす。 +`await` は `async def` で定矩された関数の内郚でしか䜿えないこずに気づいたかもしれたせん。 -しかし同時に、`async def` で定矩された関数は「awaitされる」必芁がありたす。なので、`async def` を持぀関数は、`async def` で定矩された関数内でのみ呌び出せたす。 +同時に、`async def` で定矩された関数は「await」される必芁がありたす。぀たり、`async def` を持぀関数は、やはり `async def` で定矩された関数の内郚からしか呌べたせん。 -では、このニワトリず卵の問題に぀いお、最初の `async` 関数をどのように呌び出すのでしょうか +では、ニワトリず卵の話のように、最初の `async` 関数はどう呌ぶのでしょうか -**FastAPI**を䜿甚しおいる堎合、その「最初の」関数が*path operation 関数*であり、FastAPIが正しく実行する方法を知っおいるので、心配する必芁はありたせん。 +**FastAPI** を䜿っおいる堎合は心配ありたせん。その「最初の」関数は *path operation 関数* で、FastAPI が適切に実行しおくれたす。 -しかし、FastAPI以倖で `async` / `await` を䜿甚したい堎合は、公匏Pythonドキュメントを参照しお䞋さい。 +しかし、FastAPI を䜿わずに `async` / `await` を䜿いたい堎合もありたす。 -### 非同期コヌドの他の圢匏 +### 自分で async コヌドを曞く { #write-your-own-async-code } -`async` ず `await` を䜿甚するスタむルは、この蚀語では比范的新しいものです。 +Starlette (**FastAPI** も) は AnyIO の䞊に構築されおおり、暙準ラむブラリの asyncio ず Trio の䞡方に察応しおいたす。 -非同期コヌドの操䜜がはるかに簡単になりたす。 +特に、あなた自身のコヌド内で、より高床なパタヌンを必芁ずする発展的な䞊行凊理のナヌスケヌスに察しお、AnyIO を盎接䜿えたす。 -等䟡な (たたはほずんど同䞀の) 構文が、最近のバヌゞョンのJavaScript (ブラりザおよびNodeJS) にも最近組み蟌たれたした。 +仮に FastAPI を䜿っおいなくおも、AnyIO で独自の async アプリケヌションを曞けば、高い互換性ず利点 (䟋: 構造化䞊行性) を埗られたす。 -しかし、その前は、非同期コヌドの凊理はかなり耇雑で難解でした。 +私は AnyIO の䞊に薄い局ずしお、型泚釈を少し改善し、より良い**補完**や**むンラむン゚ラヌ**などを埗るための別ラむブラリも䜜りたした。たた、**理解**しお**自分で async コヌドを曞く**のに圹立぀フレンドリヌなむントロ/チュヌトリアルもありたす: Asyncer。特に、**async コヌドず通垞の** (ブロッキング/同期) **コヌドを組み合わせる**必芁がある堎合に有甚です。 -以前のバヌゞョンのPythonでは、スレッドやGeventが利甚できたした。しかし、コヌドは理解、デバック、そしお、考察がはるかに耇雑です。 +### 非同期コヌドの他の圢匏 { #other-forms-of-asynchronous-code } -以前のバヌゞョンのNodeJS / ブラりザJavaScriptでは、「コヌルバック」を䜿甚しおいたした。これは、「コヌルバック地獄」に぀ながりたす。 +`async` ず `await` を䜿うこのスタむルは、蚀語ずしおは比范的新しいものです。 -## コルヌチン +しかし、これにより非同期コヌドの取り扱いは倧幅に簡単になりたす。 -**コルヌチン**は、`async def` 関数によっお返されるものを指す非垞に排萜た甚語です。これは、開始できお、い぀か終了する関数のようなものであるが、内郚に `await` があるずきは内郚的に䞀時停止⏞されるこずもあるものだずPythonは認識しおいたす。 +同等 (ほが同䞀) の構文が最近の JavaScript (ブラりザず NodeJS) にも導入されたした。 -`async` ず `await` を甚いた非同期コヌドを䜿甚するすべおの機胜は、「コルヌチン」を䜿甚するものずしお䜕床もたずめられおいたす。Goの䞻芁機胜である「ゎルヌチン」に盞圓したす。 +それ以前は、非同期コヌドの扱いはかなり耇雑で難解でした。 -## たずめ +以前の Python ではスレッドや Gevent を䜿えたしたが、コヌドの理解・デバッグ・思考がはるかに難しくなりたす。 -䞊述したフレヌズを芋おみたしょう: +以前の NodeJS / ブラりザ JavaScript では「コヌルバック」を䜿っおおり、「コヌルバック地獄」を招きたした。 -> 珟代版のPythonは「**非同期コヌド**」を、「**コルヌチン**」ず称されるものを利甚しおサポヌトしおいたす。これは **`async` ず `await`** 構文を甚いたす。 +## コルヌチン { #coroutines } -今では、この意味がより理解できるはずです。✚ +**コルヌチン**は、`async def` 関数が返すものを指す、ちょっず排萜た甚語です。Python はそれを、開始できおい぀か終了する関数のようなものずしお扱いたすが、内郚に `await` があるたびに内郚的に䞀時停止 ⏞ するかもしれないものずしお認識したす。 -(Starletteを介しお) FastAPIに力を䞎えお、印象的なパフォヌマンスを実珟しおいるものはこれがすべおです。 +`async` ず `await` を甚いた非同期コヌドの機胜党䜓は、しばしば「コルヌチンを䜿う」ず芁玄されたす。これは Go の䞻芁機胜「Goroutines」に盞圓したす。 -## 非垞に発展的な技術的詳现 +## たずめ { #conclusion } + +䞊のフレヌズをもう䞀床芋おみたしょう: + +> モダンな Python は **「非同期コヌド」** を **「コルヌチン」** ず呌ばれる仕組みでサポヌトしおおり、構文は **`async` ず `await`** です。 + +今なら、より意味が分かるはずです。✚ + +これらすべおが (Starlette を通じお) FastAPI を支え、印象的なパフォヌマンスを実珟しおいたす。 + +## 非垞に発展的な技術的詳现 { #very-technical-details } /// warning | 泚意 -恐らくスキップしおも良いでしょう。 +おそらく読み飛ばしおも倧䞈倫です。 -この郚分は**FastAPI**の仕組みに関する非垞に技術的な詳现です。 +これは **FastAPI** の内郚動䜜に関する、ずおも技術的な詳现です。 -かなりの技術知識 (コルヌチン、スレッド、ブロッキングなど) があり、FastAPIが `async def` ず通垞の `def` をどのように凊理するか知りたい堎合は、先に進んでください。 +(コルヌチン、スレッド、ブロッキング等の) 技術知識があり、FastAPI が `async def` ず通垞の `def` をどう扱うかに興味がある堎合は、読み進めおください。 /// -### Path operation 関数 +### Path operation 関数 { #path-operation-functions } -*path operation 関数*を `async def` の代わりに通垞の `def` で宣蚀するず、(サヌバヌをブロックするので) 盎接呌び出す代わりに倖郚スレッドプヌル (awaitされる) で実行されたす。 +*path operation 関数* を `async def` ではなく通垞の `def` で宣蚀した堎合、(サヌバをブロックしおしたうため) 盎接呌び出されるのではなく、倖郚のスレッドプヌルで実行され、それを埅機したす。 -䞊蚘の方法ず違った方法の別の非同期フレヌムワヌクから来おおり、小さなパフォヌマンス向䞊 (箄100ナノ秒) のために通垞の `def` を䜿甚しお些现な挔算のみ行う *path operation 関数* を定矩するのに慣れおいる堎合は、**FastAPI**ではたったく逆の効果になるこずに泚意しおください。このような堎合、*path operation 関数* がブロッキングI/Oを実行しないのであれば、`async def` の䜿甚をお勧めしたす。 +䞊蚘ずは異なる動䜜の別の非同期フレヌムワヌクから来おおり、ほんのわずかなパフォヌマンス向䞊 (箄 100 ナノ秒) を狙っお、蚈算のみの些现な *path operation 関数* を玠の `def` で定矩するこずに慣れおいる堎合、**FastAPI** では効果がたったく逆になる点に泚意しおください。これらの堎合、*path operation 関数* がブロッキングな I/O を行うコヌドを䜿っおいない限り、`async def` を䜿った方が良いです。 -それでも、どちらの状況でも、**FastAPI**が過去のフレヌムワヌクよりも (たたはそれに匹敵するほど) [高速になる](index.md#_10){.internal-link target=_blank}可胜性がありたす。 +それでも、どちらの状況でも、**FastAPI** はあなたが以前䜿っおいたフレヌムワヌクよりも (少なくずも同等に) [高速である](index.md#performance){.internal-link target=_blank} 可胜性が高いです。 -### 䟝存関係 +### 䟝存関係 { #dependencies } -䟝存関係に぀いおも同様です。䟝存関係が `async def` ではなく暙準の `def` 関数である堎合、倖郚スレッドプヌルで実行されたす。 +[䟝存関係](tutorial/dependencies/index.md){.internal-link target=_blank} に぀いおも同様です。䟝存関係が `async def` ではなく暙準の `def` 関数である堎合、倖郚のスレッドプヌルで実行されたす。 -### サブ䟝存関係 +### サブ䟝存関係 { #sub-dependencies } -(関数定矩のパラメヌタヌずしお) 盞互に必芁な耇数の䟝存関係ずサブ䟝存関係を蚭定できたす。䞀郚は `async def` で䜜成され、他の䞀郚は通垞の `def` で䜜成されたす。それでも動䜜し、通垞の `def`で䜜成されたものは、「awaitされる」代わりに (スレッドプヌルから) 倖郚スレッドで呌び出されたす。 +耇数の䟝存関係や [サブ䟝存関係](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} を (関数定矩のパラメヌタずしお) 盞互に芁求させられたす。その䞀郚は `async def`、他は通垞の `def` で䜜られおいおも動䜜したす。通垞の `def` で䜜られたものは「await」される代わりに、倖郚スレッドプヌルからスレッド䞊で呌び出されたす。 -### その他のナヌティリティ関数 +### その他のナヌティリティ関数 { #other-utility-functions } -あなたが盎接呌び出すナヌティリティ関数は通垞の `def` たたは `async def` で䜜成でき、FastAPIは呌び出す方法に圱響を䞎えたせん。 +あなたが盎接呌び出すナヌティリティ関数は、通垞の `def` でも `async def` でも構いたせん。FastAPI はその呌び出し方に圱響を䞎えたせん。 -これは、FastAPIが呌び出す関数ず察照的です: *path operation 関数*ず䟝存関係。 +これは、FastAPI があなたの代わりに呌び出す関数 (すなわち *path operation 関数* ず䟝存関係) ずは察照的です。 -ナヌティリティ関数が `def` を䜿甚した通垞の関数である堎合、スレッドプヌルではなく盎接 (コヌドで蚘述したずおりに) 呌び出されたす。関数が `async def` を䜿甚しお䜜成されおいる堎合は、呌び出す際に `await` する必芁がありたす。 +ナヌティリティ関数が `def` の通垞関数であれば、(あなたのコヌドに曞いたずおりに) 盎接呌び出され、スレッドプヌルでは実行されたせん。関数が `async def` で䜜られおいる堎合は、その関数を呌ぶずきに `await` すべきです。 --- -繰り返しになりたすが、これらは非垞に技術的な詳现であり、怜玢しお蟿り着いた堎合は圹立぀でしょう。 +繰り返しになりたすが、これらは非垞に技術的な詳现で、該圓事項を怜玢しおここにたどり着いた堎合には圹立぀でしょう。 -それ以倖の堎合は、䞊蚘のセクションのガむドラむンで問題ないはずです: 急いでいたすか。 +それ以倖の堎合は、䞊のセクションのガむドラむンに埓えば十分です: 急いでいたすか。 diff --git a/docs/ja/docs/deployment/cloud.md b/docs/ja/docs/deployment/cloud.md new file mode 100644 index 000000000..17699cdca --- /dev/null +++ b/docs/ja/docs/deployment/cloud.md @@ -0,0 +1,24 @@ +# クラりドプロバむダぞの FastAPI デプロむ { #deploy-fastapi-on-cloud-providers } + +FastAPI アプリケヌションは、実質的にどのようなクラりドプロバむダでもデプロむできたす。 + +倚くの堎合、䞻芁なクラりドプロバむダは FastAPI をデプロむするためのガむドを提䟛しおいたす。 + +## FastAPI Cloud { #fastapi-cloud } + +**FastAPI Cloud** は、**FastAPI** の䜜者ず同じチヌムによっお䜜られおいたす。 + +API の**構築**、**デプロむ**、**アクセス**たでのプロセスを、最小限の手間で効率化したす。 + +FastAPI でアプリを開発するずきず同じ**開発者䜓隓**を、クラりドぞの**デプロむ**にももたらしたす。🎉 + +FastAPI Cloud は、*FastAPI and friends* オヌプン゜ヌスプロゞェクトの䞻芁なスポンサヌか぀資金提䟛元です。✚ + +## クラりドプロバむダ - スポンサヌ { #cloud-providers-sponsors } + +他にもいく぀かのクラりドプロバむダが ✹ [**FastAPI をスポンサヌしおいたす**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✚。🙇 + +それらのガむドを参考にし、サヌビスを詊しおみるのもよいでしょう: + +* Render +* Railway diff --git a/docs/ja/docs/deployment/concepts.md b/docs/ja/docs/deployment/concepts.md index 787eb2e73..501a90bc9 100644 --- a/docs/ja/docs/deployment/concepts.md +++ b/docs/ja/docs/deployment/concepts.md @@ -29,7 +29,6 @@ ## セキュリティ - HTTPS { #security-https } - [前チャプタヌのHTTPSに぀いお](https.md){.internal-link target=_blank}では、HTTPSがどのようにAPIを暗号化するのかに぀いお孊びたした。 通垞、アプリケヌションサヌバにずっお**倖郚の**コンポヌネントである**TLS Termination Proxy**によっお提䟛されるこずが䞀般的です。このプロキシは通信の暗号化を担圓したす。 @@ -193,7 +192,6 @@ FastAPI アプリケヌションでは、Uvicorn を実行する `fastapi` コ 同じAPIプログラムの**耇数のプロセス**を実行する堎合、それらは䞀般的に**Workerワヌカヌ**ず呌ばれたす。 ### ワヌカヌ・プロセス ず ポヌト { #worker-processes-and-ports } - [HTTPSに぀いお](https.md){.internal-link target=_blank}のドキュメントで、1぀のサヌバヌで1぀のポヌトずIPアドレスの組み合わせでリッスンできるのは1぀のプロセスだけであるこずを芚えおいたすでしょうか diff --git a/docs/ja/docs/deployment/docker.md b/docs/ja/docs/deployment/docker.md index 6c182448c..883f98c98 100644 --- a/docs/ja/docs/deployment/docker.md +++ b/docs/ja/docs/deployment/docker.md @@ -14,7 +14,7 @@ Linuxコンテナの䜿甚には、**セキュリティ**、**反埩可胜性 Dockerfile Preview 👀 ```Dockerfile -FROM python:3.9 +FROM python:3.14 WORKDIR /code @@ -166,7 +166,7 @@ def read_item(item_id: int, q: str | None = None): ```{ .dockerfile .annotate } # (1)! -FROM python:3.9 +FROM python:3.14 # (2)! WORKDIR /code @@ -392,7 +392,7 @@ FastAPI が単䞀のファむル、䟋えば `./app` ディレクトリのない そうすれば、`Dockerfile`の䞭にファむルをコピヌするために、察応するパスを倉曎するだけでよいです ```{ .dockerfile .annotate hl_lines="10 13" } -FROM python:3.9 +FROM python:3.14 WORKDIR /code @@ -456,7 +456,7 @@ TraefikはDockerやKubernetesなどず統合されおいるので、コンテナ ## レプリケヌション - プロセス数 { #replication-number-of-processes } -**Kubernetes** や Docker Swarm モヌド、Nomad、あるいは耇数のマシン䞊で分散コンテナを管理するための同様の耇雑なシステムを䜿っおマシンのclusterを構成しおいる堎合、 各コンテナでWorkerを持぀Uvicornのような**プロセスマネヌゞャ**を䜿甚する代わりに、**クラスタヌ・レベル**で**レプリケヌション**を凊理したいず思うでしょう。 +**Kubernetes** や Docker Swarm モヌド、Nomad、あるいは耇数のマシン䞊で分散コンテナを管理するための同様の耇雑なシステムを䜿っおマシンのクラスタを構成しおいる堎合、 各コンテナでWorkerを持぀Uvicornのような**プロセスマネヌゞャ**を䜿甚する代わりに、**クラスタヌ・レベル**で**レプリケヌション**を凊理したいず思うでしょう。 Kubernetesのような分散コンテナ管理システムの1぀は通垞、入っおくるリク゚ストの**ロヌドバランシング**をサポヌトしながら、**コンテナのレプリケヌション**を凊理する統合された方法を持っおいたす。このこずはすべお**クラスタレベル**におです。 @@ -501,7 +501,7 @@ HTTPSに䜿われるものず同じ**TLS Termination Proxy**コンポヌネン そのような堎合、`--workers` コマンドラむンオプションを䜿っお、実行したいワヌカヌ数を蚭定できたす ```{ .dockerfile .annotate } -FROM python:3.9 +FROM python:3.14 WORKDIR /code diff --git a/docs/ja/docs/deployment/fastapicloud.md b/docs/ja/docs/deployment/fastapicloud.md new file mode 100644 index 000000000..43d9ce0d0 --- /dev/null +++ b/docs/ja/docs/deployment/fastapicloud.md @@ -0,0 +1,65 @@ +# FastAPI Cloud { #fastapi-cloud } + +FastAPI Cloud に **コマンド1぀** でデプロむできたす。ただならりェむティングリストにご登録ください。🚀 + +## ログむン { #login } + +すでに **FastAPI Cloud** アカりントをお持ちであるこずを確認しおくださいりェむティングリストからご招埅しおいたす 😉。 + +次にログむンしたす: + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +## デプロむ { #deploy } + +では、**コマンド1぀** でアプリをデプロむしたす: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +以䞊ですその URL からアプリにアクセスできたす。✚ + +## FastAPI Cloud に぀いお { #about-fastapi-cloud } + +**FastAPI Cloud** は、**FastAPI** の䜜者ずチヌムによっお開発されおいたす。 + +最小限の手間で API を**構築**・**デプロむ**・**利甚**できるように工皋を簡玠化したす。 + +FastAPI での開発ず同じ**開発者䜓隓**を、クラりドぞの**デプロむ**にももたらしたす。🎉 + +さらに、アプリのデプロむ時に必芁ずなる倚くの事項も任せられたす。䟋えば: + +* HTTPS +* レプリケヌションリク゚ストに基づくオヌトスケヌリング付き +* など + +FastAPI Cloud は、*FastAPI and friends* のオヌプン゜ヌスプロゞェクトに察する䞻芁スポンサヌか぀資金提䟛元です。✚ + +## 他のクラりドプロバむダヌぞのデプロむ { #deploy-to-other-cloud-providers } + +FastAPI はオヌプン゜ヌスで暙準に基づいおいたす。お奜みの任意のクラりドプロバむダヌに FastAPI アプリをデプロむできたす。 + +各クラりドプロバむダヌのガむドに埓っお FastAPI アプリをデプロむしおください。🀓 + +## 自分のサヌバヌぞのデプロむ { #deploy-your-own-server } + +この**デプロむ**ガむドの埌半では詳现も解説したす。䜕が起きおいるのか、䜕が必芁なのか、そしお自分のサヌバヌを含めお FastAPI アプリを自力でデプロむする方法が分かるようになりたす。🀓 diff --git a/docs/ja/docs/deployment/https.md b/docs/ja/docs/deployment/https.md index d5a6daf0c..8e588aadc 100644 --- a/docs/ja/docs/deployment/https.md +++ b/docs/ja/docs/deployment/https.md @@ -28,7 +28,7 @@ HTTPSは単に「有効」か「無効」かで決たるものだず思いがち * **デフォルトでは**、**IPアドレスごずに1぀のHTTPS蚌明曞**しか持おないこずになりたす。 * これは、サヌバヌの芏暡やアプリケヌションの芏暡に寄りたせん。 * しかし、これには**解決策**がありたす。 -* **TLS**プロトコル(HTTPの前に、TCPレベルで暗号化を凊理するもの)には、**SNI**ず呌ばれる**拡匵**がありたす。 +* **TLS**プロトコル(HTTPの前に、TCPレベルで暗号化を凊理するもの)には、**SNI**ず呌ばれる**拡匵**がありたす。 * このSNI拡匵機胜により、1぀のサヌバヌ**単䞀のIPアドレス**を持぀が**耇数のHTTPS蚌明曞**を持ち、**耇数のHTTPSドメむン/アプリケヌション**にサヌビスを提䟛できるようになりたす。 * これが機胜するためには、**パブリックIPアドレス**でリッスンしおいる、サヌバヌ䞊で動䜜しおいる**単䞀の**コンポヌネント(プログラム)が、サヌバヌ内の**すべおのHTTPS蚌明曞**を持っおいる必芁がありたす。 * セキュアな接続を取埗した**埌**でも、通信プロトコルは**HTTPのたた**です。 @@ -66,7 +66,7 @@ Let's Encrypt以前は、これらの**HTTPS蚌明曞**は信頌できる第䞉 ステップの初めは、**ドメむン名**を**取埗するこず**から始たるでしょう。その埌、DNSサヌバヌおそらく同じクラりドプロバむダヌに蚭定したす。 -おそらくクラりドサヌバヌ仮想マシンかそれに類するものを手に入れ、fixed **パブリックIPアドレス**を持぀こずになるでしょう。 +おそらくクラりドサヌバヌ仮想マシンかそれに類するものを手に入れ、固定の **パブリックIPアドレス**を持぀こずになるでしょう。 DNSサヌバヌでは、**取埗したドメむン**をあなたのサヌバヌのパプリック**IPアドレス**に向けるレコヌド「`A record`」を蚭定したす。 diff --git a/docs/ja/docs/deployment/manually.md b/docs/ja/docs/deployment/manually.md index da382a9c5..1931cd87e 100644 --- a/docs/ja/docs/deployment/manually.md +++ b/docs/ja/docs/deployment/manually.md @@ -1,12 +1,82 @@ -# 手動デプロむ +# サヌバヌを手動で実行する { #run-a-server-manually } -**FastAPI** を手動でデプロむするこずもできたす。 +## fastapi run コマンドを䜿う { #use-the-fastapi-run-command } -以䞋の様なASGI察応のサヌバをむンストヌルする必芁がありたす: +結論ずしお、FastAPI アプリケヌションを提䟛するには `fastapi run` を䜿いたす: -//// tab | Uvicorn +
-* Uvicorn, uvloopずhttptoolsを基にした高速なASGIサヌバ。 +```console +$ fastapi run main.py + + FastAPI Starting production server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://0.0.0.0:8000 + server Documentation at http://0.0.0.0:8000/docs + + Logs: + + INFO Started server process [2306215] + INFO Waiting for application startup. + INFO Application startup complete. + INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C + to quit) +``` + +
+ +これでほずんどのケヌスは動䜜したす。😎 + +このコマンドは、たずえばコンテナやサヌバヌ内で **FastAPI** アプリを起動するのに䜿えたす。 + +## ASGIサヌバヌ { #asgi-servers } + +少し詳しく芋おいきたす。 + +FastAPI は、Python の Web フレヌムワヌクずサヌバヌのための暙準である ASGI を䜿いたす。FastAPI は ASGI Web フレヌムワヌクです。 + +リモヌトのサヌバヌマシンで **FastAPI** アプリケヌションや他の ASGI アプリケヌションを実行するのに䞻に必芁なのは **Uvicorn** のような ASGI サヌバヌプログラムです。これは `fastapi` コマンドにデフォルトで含たれおいたす。 + +他にもいく぀かの遞択肢がありたす: + +* Uvicorn: 高性胜な ASGI サヌバヌ。 +* Hypercorn: HTTP/2 や Trio に察応する ASGI サヌバヌなど。 +* Daphne: Django Channels のために䜜られた ASGI サヌバヌ。 +* Granian: Python アプリケヌション向けの Rust 補 HTTP サヌバヌ。 +* NGINX Unit: 軜量で倚甚途な Web アプリケヌションランタむム。 + +## サヌバヌマシンずサヌバヌプログラム { #server-machine-and-server-program } + +名称に関する小さな泚意点がありたす。💡 + +「サヌバヌ」ずいう蚀葉は、リモヌト/クラりド䞊のコンピュヌタ物理/仮想マシンず、そのマシン䞊で動䜜しおいるプログラム䟋: Uvicornの䞡方を指すのに䞀般的に䜿われたす。 + +䞀般に「サヌバヌ」ず曞かれおいるずきは、そのどちらかを指しおいる可胜性があるこずを芚えおおいおください。 + +リモヌトマシンを指す堎合、「サヌバヌ」のほか「マシン」「VM仮想マシン」「ノヌド」などずも呌ばれたす。いずれも通垞 Linux を実行し、そこでプログラムを動かすリモヌトマシンを指したす。 + +## サヌバヌプログラムをむンストヌル { #install-the-server-program } + +FastAPI をむンストヌルするず、本番サヌバヌの Uvicorn が同梱されおおり、`fastapi run` コマンドで起動できたす。 + +ただし、ASGI サヌバヌを手動でむンストヌルするこずもできたす。 + +[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化し、サヌバヌアプリケヌションをむンストヌルしおください。 + +䟋ずしお、Uvicorn をむンストヌルするには:
@@ -18,37 +88,21 @@ $ pip install "uvicorn[standard]"
-//// +他の ASGI サヌバヌプログラムでも同様の手順です。 /// tip | 豆知識 -`standard` を加えるこずで、Uvicornがむンストヌルされ、いく぀かの掚奚される䟝存関係を利甚するようになりたす。 +`standard` を付けるず、Uvicorn は掚奚の远加䟝存関係もむンストヌルしお䜿甚したす。 -これには、`asyncio` の高性胜な完党互換品である `uvloop` が含たれ、䞊行凊理のパフォヌマンスが倧幅に向䞊したす。 +その䞭には、`asyncio` の高性胜なドロップむン代替であり、倧きな䞊行実行性胜の向䞊をもたらす `uvloop` も含たれたす。 + +`pip install "fastapi[standard]"` のように FastAPI をむンストヌルした堎合は、すでに `uvicorn[standard]` も含たれたす。 /// -//// tab | Hypercorn +## サヌバヌプログラムを起動 { #run-the-server-program } -* Hypercorn, HTTP/2にも察応しおいるASGIサヌバ。 - -
- -```console -$ pip install hypercorn - ----> 100% -``` - -
- -...たたは、これら以倖のASGIサヌバ。 - -//// - -そしお、チュヌトリアルず同様な方法でアプリケヌションを起動しお䞋さい。ただし、以䞋の様に`--reload` オプションは䜿甚しないで䞋さい: - -//// tab | Uvicorn +ASGI サヌバヌを手動でむンストヌルした堎合、通垞は FastAPI アプリケヌションをむンポヌトさせるために、特別な圢匏のむンポヌト文字列を枡す必芁がありたす:
@@ -60,26 +114,44 @@ $ uvicorn main:app --host 0.0.0.0 --port 80
-//// +/// note | 備考 -//// tab | Hypercorn +`uvicorn main:app` ずいうコマンドは次を指したす: -
+* `main`: ファむル `main.py`Python の「モゞュヌル」。 +* `app`: `main.py` 内で `app = FastAPI()` により䜜成されたオブゞェクト。 -```console -$ hypercorn main:app --bind 0.0.0.0:80 +これは次ず等䟡です: -Running on 0.0.0.0:8080 over http (CTRL + C to quit) +```Python +from main import app ``` -
+/// -//// +他の ASGI サヌバヌプログラムでも同様のコマンドがあり、詳现はそれぞれのドキュメントを参照しおください。 -停止した堎合に自動的に再起動させるツヌルを蚭定したいかもしれたせん。 +/// warning | 泚意 -さらに、GunicornをむンストヌルしおUvicornのマネヌゞャヌずしお䜿甚したり、耇数のワヌカヌでHypercornを䜿甚したいかもしれたせん。 +Uvicorn などのサヌバヌは、開発時に䟿利な `--reload` オプションをサポヌトしおいたす。 -ワヌカヌ数などの埮調敎も行いたいかもしれたせん。 +しかし `--reload` は倚くのリ゜ヌスを消費し、䞍安定になるなどの性質がありたす。 -しかしこれら党おをやろうずするず、自動的にこれらを行うDockerむメヌゞを䜿う方が楜かもしれたせん。 +開発䞭には非垞に圹立ちたすが、 本番環境では䜿甚すべきではありたせん。 + +/// + +## デプロむの抂念 { #deployment-concepts } + +これらの䟋は、サヌバヌプログラム䟋: Uvicornを実行し、事前に決めたポヌト䟋: `80`で、すべおの IP`0.0.0.0`をリッスンする「単䞀プロセス」を起動したす。 + +これが基本的な考え方です。ただし、次のような远加事項にも察応したくなるでしょう: + +* セキュリティ - HTTPS +* 起動時に実行 +* 再起動 +* レプリケヌション実行プロセス数 +* メモリ +* 起動前の事前ステップ + +これらの各抂念に぀いおの考え方や、察凊するための具䜓䟋・戊略を次の章で説明したす。🚀 diff --git a/docs/ja/docs/environment-variables.md b/docs/ja/docs/environment-variables.md index 45dbfc71f..4deae7044 100644 --- a/docs/ja/docs/environment-variables.md +++ b/docs/ja/docs/environment-variables.md @@ -153,7 +153,7 @@ Hello World from Python /// tip | 豆知識 -詳しくは The Twelve-Factor App: Config を参照しおください。 +詳しくは The Twelve-Factor App: 蚭定 を参照しおください。 /// @@ -291,7 +291,7 @@ $ C:\opt\custompython\bin\python これで、**環境倉数**ずは䜕か、Pythonでどのように䜿甚するかに぀いお、基本的な理解が埗られたはずです。 -環境倉数に぀いおの詳现は、Wikipedia for Environment Variable も参照しおください。 +環境倉数に぀いおの詳现は、Wikipedia の環境倉数 も参照しおください。 倚くの堎合、環境倉数がどのように圹立ち、すぐに適甚できるのかはあたり明確ではありたせん。しかし、開発䞭のさたざたなシナリオで䜕床も登堎するため、知っおおくずよいでしょう。 diff --git a/docs/ja/docs/fastapi-cli.md b/docs/ja/docs/fastapi-cli.md new file mode 100644 index 000000000..20cc9c2fb --- /dev/null +++ b/docs/ja/docs/fastapi-cli.md @@ -0,0 +1,75 @@ +# FastAPI CLI { #fastapi-cli } + +**FastAPI CLI** は、FastAPI アプリの提䟛、FastAPI プロゞェクトの管理などに䜿甚できるコマンドラむンプログラムです。 + +FastAPI をむンストヌルするず䟋: `pip install "fastapi[standard]"`、`fastapi-cli` ずいうパッケヌゞが含たれたす。このパッケヌゞがタヌミナルで䜿甚する `fastapi` コマンドを提䟛したす。 + +開発甚に FastAPI アプリを起動するには、`fastapi dev` コマンドを䜿甚できたす: + +
+ +```console +$ fastapi dev main.py + + FastAPI Starting development server 🚀 + + Searching for package file structure from directories with + __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with the + following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to + quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. +``` + +
+ +`fastapi` ずいうコマンドラむンプログラムが **FastAPI CLI** です。 + +FastAPI CLI は、Python プログラムぞのパス䟋: `main.py`を受け取り、`FastAPI` むンスタンス通垞は `app`を自動怜出し、適切な import 方法を刀断しお提䟛したす。 + +本番環境では代わりに `fastapi run` を䜿甚したす。🚀 + +内郚的には、**FastAPI CLI** は Uvicorn高性胜で本番運甚向けの ASGI サヌバヌを䜿甚したす。😎 + +## `fastapi dev` { #fastapi-dev } + +`fastapi dev` を実行するず、開発モヌドが有効になりたす。 + +デフォルトでは、**auto-reload** が有効です。コヌドを倉曎するずサヌバヌが自動で再読み蟌みされたす。これはリ゜ヌスを倚く消費し、無効時より安定性が䜎くなる可胜性がありたす。開発時のみに䜿甚しおください。たた、IP アドレス `127.0.0.1`マシン自身のみず通信するための IP、`localhost`で埅ち受けたす。 + +## `fastapi run` { #fastapi-run } + +`fastapi run` を実行するず、デフォルトで本番モヌドで起動したす。 + +デフォルトでは、**auto-reload** は無効です。たた、IP アドレス `0.0.0.0`利甚可胜なすべおの IP アドレスを意味したすで埅ち受けるため、そのマシンず通信できる任意のクラむアントから公開アクセスが可胜になりたす。これは、たずえばコンテナ内など、本番環境で䞀般的な実行方法です。 + +倚くの堎合そしお掚奚されるのは、䞊䜍に HTTPS を終端する「termination proxy」を眮きたす。これはアプリのデプロむ方法に䟝存し、プロバむダが代行する堎合もあれば、自分で蚭定する必芁がある堎合もありたす。 + +/// tip | 豆知識 + +詳しくは、[デプロむのドキュメント](deployment/index.md){.internal-link target=_blank}を参照しおください。 + +/// diff --git a/docs/ja/docs/features.md b/docs/ja/docs/features.md index f78eab430..40a1d2e60 100644 --- a/docs/ja/docs/features.md +++ b/docs/ja/docs/features.md @@ -1,54 +1,55 @@ -# 機胜 +# 機胜 { #features } -## FastAPIの機胜 +## FastAPIの機胜 { #fastapi-features } -**FastAPI** は以䞋の機胜をもちたす: +**FastAPI** は次のものを提䟛したす: -### オヌプンスタンダヌド準拠 +### オヌプンスタンダヌド準拠 { #based-on-open-standards } -* API䜜成のためのOpenAPI。これは、path operationsの宣蚀、パラメヌタ、ボディリク゚スト、セキュリティなどを含んでいたす。 -* JSONスキヌマを䜿甚したデヌタモデルのドキュメント自動生成OpenAPIはJSONスキヌマに基づいおいる。 -* 綿密な調査の結果、䞊局に埌付けするのではなく、これらの基準に基づいお蚭蚈されたした。 +* API 䜜成のための OpenAPI。path operations、パラメヌタ、リク゚ストボディ、セキュリティなどの宣蚀を含みたす。 +* JSON Schema によるデヌタモデルの自動ドキュメント化OpenAPI 自䜓が JSON Schema に基づいおいたす。 +* 入念な調査のうえ、これらの暙準を䞭心に蚭蚈されおいたす。埌付けのレむダヌではありたせん。 * これにより、倚くの蚀語で自動 **クラむアントコヌド生成** が可胜です。 -### 自動ドキュメント生成 -察話的なAPIドキュメントず探玢的なwebナヌザヌむンタヌフェヌスを提䟛したす。フレヌムワヌクはOpenAPIを基にしおいるため、いく぀かのオプションがあり、デフォルトで2぀含たれおいたす。 +### 自動ドキュメント { #automatic-docs } -* Swagger UIで、むンタラクティブな探玢をしながら、ブラりザから盎接APIを呌び出しおテストが行えたす。 +察話的な API ドキュメントず探玢的な Web ナヌザヌむンタヌフェヌス。フレヌムワヌクは OpenAPI に基づいおいるため、耇数のオプションがあり、デフォルトで 2 ぀含たれたす。 + +* Swagger UI。むンタラクティブに探玢し぀぀、ブラりザから盎接 API を呌び出しおテストできたす。 ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* ReDocを䜿甚したもう䞀぀のAPIドキュメント生成。 +* ReDoc による代替の API ドキュメント。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### 珟代的なPython +### 珟代的なPythonのみ { #just-modern-python } -FastAPIの機胜はすべお、暙準のPython 3.8型宣蚀に基づいおいたすPydanticの功瞟。新しい構文はありたせん。ただの珟代的な暙準のPythonです。 +すべお暙準の **Python の型** 宣蚀Pydantic に感謝に基づいおいたす。新しい構文を孊ぶ必芁はありたせん。暙準的でモダンな Python だけです。 -FastAPIを䜿甚しない堎合でもPythonの型の䜿甚方法に぀いお簡単な埩習が必芁な堎合は、短いチュヌトリアル[Python Types](python-types.md){.internal-link target=_blank}を参照しおください。 +FastAPI を䜿わない堎合でもPython の型の䜿い方を 2 分で埩習したい堎合は、短いチュヌトリアル [Python Types](python-types.md){.internal-link target=_blank} を参照しおください。 -型を䜿甚した暙準的なPythonを蚘述したす: +型を䜿った暙準的な Python を蚘述したす: ```Python from datetime import date from pydantic import BaseModel -# Declare a variable as a str -# and get editor support inside the function +# 倉数を str ずしお宣蚀 +# そしお関数内で゚ディタ支揎を受ける def main(user_id: str): return user_id -# A Pydantic model +# Pydantic モデル class User(BaseModel): id: int name: str joined: date ``` -これは以䞋のように甚いられたす: +これは次のように䜿えたす: ```Python my_user: User = User(id=3, name="John Doe", joined="2018-07-19") @@ -62,143 +63,139 @@ second_user_data = { my_second_user: User = User(**second_user_data) ``` -/// info | 情報 +/// info -`**second_user_data` は以䞋を意味したす +`**second_user_data` は次の意味です: -`second_user_data`蟞曞のキヌず倀を盎接、キヌず倀の匕数ずしお枡したす。これは、`User(id=4, name="Mary", joined="2018-11-30")`ず同等です。 +`second_user_data` 蟞曞のキヌず倀を、そのたたキヌバリュヌ匕数ずしお枡したす。これは `User(id=4, name="Mary", joined="2018-11-30")` ず同等です。 /// -### ゚ディタのサポヌト +### ゚ディタのサポヌト { #editor-support } -すべおのフレヌムワヌクは䜿いやすく盎感的に䜿甚できるように蚭蚈されおおり、すべおの決定は開発を開始する前でも耇数の゚ディタヌでテストされ、最高の開発䜓隓が保蚌されたす。 +フレヌムワヌク党䜓が䜿いやすく盎感的になるよう蚭蚈されおおり、最高の開発䜓隓を確保するため、開発開始前から耇数の゚ディタであらゆる刀断が怜蚌されおいたす。 -前回のPython開発者調査では、最も䜿甚されおいる機胜が「オヌトコンプリヌト」であるこずが明らかになりたした。 +Python 開発者調査では、最もよく䜿われる機胜の 1 ぀が「オヌトコンプリヌト」であるこずが明らかです。 -**FastAPI** フレヌムワヌクは、この芁求を満たすこずを基本ずしおいたす。オヌトコンプリヌトはどこでも機胜したす。 +**FastAPI** はその芁求を満たすこずを基盀にしおいたす。オヌトコンプリヌトはどこでも機胜したす。 ドキュメントに戻る必芁はほずんどありたせん。 -゚ディタヌがどのように圹立぀かを以䞋に瀺したす: +゚ディタがどのように圹立぀かの䟋です: -* Visual Studio Codeの堎合: +* Visual Studio Code の堎合: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -* PyCharmの堎合: +* PyCharm の堎合: ![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) -以前は䞍可胜だず考えおいたコヌドでさえ補完されたす。䟋えば、リク゚ストからのJSONボディネストされおいる可胜性がある内の `price`キヌです。 +以前は䞍可胜だず思っおいたコヌドでも補完が埗られたす。䟋えば、リク゚ストから届くネストされおいる可胜性のあるJSON ボディ内の `price` キヌなどです。 -間違ったキヌ名を入力したり、ドキュメント間を行き来したり、䞊䞋にスクロヌルしお`username`ず`user_name`のどちらを䜿甚したか調べたりする必芁はもうありたせん。 +もう間違ったキヌ名を入力したり、ドキュメントを行き来したり、䞊䞋にスクロヌルしお最終的に `username` ず `user_name` のどちらを䜿ったのか探す必芁はありたせん。 -### 簡朔 +### 簡朔 { #short } -すべおに適切な**デフォルト**があり、オプションの構成ができたす。必芁なこずを実行し、必芁なAPIを定矩するためにすべおのパラメヌタヌを調敎できたす。 +すべおに劥圓な **デフォルト** があり、どこでもオプションで構成できたす。必芁に応じおすべおのパラメヌタを埮調敎しお、求める API を定矩できたす。 -ただし、デフォルトでもすべお **うたくいきたす**。 +しかしデフォルトのたたでも、すべお **うたく動きたす**。 -### 怜蚌 +### 怜蚌 { #validation } -* 以䞋の様な、ほずんどのすべおのPython **デヌタ型**の怜蚌: - * JSONオブゞェクト`dict` - * 項目の型を定矩するJSON配列`list` - * 最小長ず最倧長のある文字列`str`フィヌルド - * 最小倀ず最倧倀のある数倀`int`、` float` +* ほずんどあるいはすべおの Python の **デヌタ型** に察する怜蚌: + * JSON オブゞェクト`dict`。 + * 項目の型を定矩する JSON 配列`list`。 + * 文字列`str`フィヌルドの最小/最倧長。 + * 数倀`int`、`float`の最小/最倧倀、など。 -* より゚キゟチックな型の怜蚌 - * URL - * Eメヌル - * UUID - * ...その他 +* より゚キゟチックな型の怜蚌: + * URL。 + * Email。 + * UUID。 + * ...その他。 -すべおの怜蚌は、確立された堅牢な **Pydantic** によっお凊理されたす。 +すべおの怜蚌は、確立され堅牢な **Pydantic** によっお凊理されたす。 -### セキュリティず認蚌 +### セキュリティず認蚌 { #security-and-authentication } -セキュリティず認蚌が統合されおいたす。 デヌタベヌスたたはデヌタモデルに぀いおも劥協しおいたせん。 +セキュリティず認蚌が統合されおいたす。デヌタベヌスやデヌタモデルずの劥協はありたせん。 -以䞋のOpenAPIで定矩されおいるすべおのセキュリティスキヌムを含む: +OpenAPI で定矩されたすべおのセキュリティスキヌムをサポヌトしたす: -* HTTPベヌシック -* **OAuth2****JWTトヌクン**も䜿甚。 JWTを䜿甚したOAuth2のチュヌトリアル[OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}を確認しおください。 -* APIキヌ - * ヘッダヌ - * ク゚リパラメヌタ - * クッキヌ、等 +* HTTP Basic。 +* **OAuth2****JWT トヌクン** も可。チュヌトリアル [JWT を甚いた OAuth2](tutorial/security/oauth2-jwt.md){.internal-link target=_blank} を確認しおください。 +* API キヌ以䞋の堎所: + * ヘッダヌ。 + * ク゚リパラメヌタ。 + * クッキヌ、など。 -さらに、Starletteのすべおのセキュリティ機胜も含みたす**セッションCookie**を含む。 +さらに、Starlette のすべおのセキュリティ機胜**セッション Cookie** を含むも利甚できたす。 -これらは、システム、デヌタストア、リレヌショナルデヌタベヌス、NoSQLデヌタベヌスなどず簡単に統合できる再利甚可胜なツヌルずコンポヌネントずしお構築されおいたす。 +これらはすべお再利甚可胜なツヌルやコンポヌネントずしお構築されおおり、システム、デヌタストア、リレヌショナル/NoSQL デヌタベヌス等ず容易に統合できたす。 -### 䟝存性の泚入Dependency Injection +### 䟝存性の泚入 { #dependency-injection } -FastAPIには非垞に䜿いやすく、非垞に匷力な䟝存性の泚入システムを備えおいたす。 +FastAPI には、非垞に䜿いやすく、か぀非垞に匷力な 䟝存性の泚入 システムがありたす。 -* 䟝存関係でさえも䟝存関係を持぀こずができ、階局たたは **䟝存関係の"グラフ"** を䜜成するこずができたす。 +* 䟝存関係は䟝存関係を持぀こずもでき、階局たたは **䟝存関係の「グラフ」** を䜜成できたす。 +* すべおフレヌムワヌクによっお**自動的に凊理**されたす。 +* すべおの䟝存関係はリク゚ストからデヌタを芁求でき、*path operation* の制玄ず自動ドキュメントを**拡匵**できたす。 +* 䟝存関係で定矩された *path operation* のパラメヌタに぀いおも**自動怜蚌**されたす。 +* 耇雑なナヌザヌ認蚌システム、**デヌタベヌス接続** などのサポヌト。 +* **デヌタベヌスやフロント゚ンド等ずの劥協は䞍芁**。すべおず簡単に統合できたす。 -* フレヌムワヌクによっおすべお**自動的に凊理**されたす。 -* すべおの䟝存関係はリク゚ストからのデヌタを芁請できお、**path operationsの制玄ず自動ドキュメンテヌションを拡匵できたす**。 -* 䟝存関係で定矩された *path operation* パラメヌタも**自動怜蚌**が可胜です。 -* 耇雑なナヌザヌ認蚌システム、**デヌタベヌス接続**などのサポヌト -* **デヌタベヌス、フロント゚ンドなどに察する劥協はありたせん**。それらすべおず簡単に統合できたす。 +### 無制限の「プラグむン」 { #unlimited-plug-ins } -### 無制限の「プラグむン」 +別の蚀い方をすれば、プラグむンは䞍芁で、必芁なコヌドをむンポヌトしお䜿うだけです。 -他の方法では、それらを必芁ずせず、必芁なコヌドをむンポヌトしお䜿甚したす。 +あらゆる統合は䟝存関係を甚いお非垞に簡単に䜿えるよう蚭蚈されおおり、*path operation* で䜿うのず同じ構造ず構文で、2 行のコヌドでアプリケヌション甚の「プラグむン」を䜜れたす。 -統合は非垞に簡単に䜿甚できるように蚭蚈されおおり䟝存関係を甚いお、*path operations* で䜿甚されおいるのず同じ構造ず構文を䜿甚しお、2行のコヌドでアプリケヌションの「プラグむン」を䜜成できたす。 +### テスト枈み { #tested } +* 100% の テストカバレッゞ。 +* 100% 型アノテヌション付きのコヌドベヌス。 +* 本番アプリケヌションで䜿甚されおいたす。 -### テスト +## Starletteの機胜 { #starlette-features } -* テストカバレッゞ 100% -* 型アノテヌション100%のコヌドベヌス -* 本番アプリケヌションで䜿甚されたす +**FastAPI** は Starlette ず完党に互換性がありか぀それに基づいおいたす。そのため、手元の Starlette の远加コヌドも動䜜したす。 -## Starletteの機胜 +`FastAPI` は実際には `Starlette` のサブクラスです。すでに Starlette を知っおいる、あるいは䜿っおいるなら、ほずんどの機胜は同じように動䜜したす。 -**FastAPI**は、Starlette ず完党に互換性がありたすそしおベヌスになっおいたす。したがっお、远加のStarletteコヌドがあれば、それも機胜したす。 +**FastAPI** では **Starlette** のすべおの機胜が利甚できたすFastAPI は匷化された Starlette にすぎたせん: -`FastAPI`は実際には`Starlette`のサブクラスです。したがっお、Starletteをすでに知っおいるか䜿甚しおいる堎合は、ほずんどの機胜が同じように機胜したす。 - -**FastAPI**を䜿甚するず、以䞋のような、**Starlette**のすべおの機胜を利甚できたすFastAPIはStarletteを匷化したものにすぎないため: - -* 芋事なパフォヌマンス。 **NodeJS**および**Go**に匹敵する、最速のPythonフレヌムワヌクの1぀です。 - -* **WebSocket**のサポヌト -* **GraphQL**のサポヌト -* プロセス内バックグラりンドタスク -* 起動およびシャットダりンむベント -* `httpx`に基づいお構築されたテストクラむアント -* **CORS**、GZip、静的ファむル、ストリヌミング応答 -* **セッションずCookie**のサポヌト -* テストカバレッゞ100% -* 型アノテヌション100%のコヌドベヌス - -## Pydanticの特城 - -**FastAPI**はPydantic ず完党に互換性がありたすそしおベヌスになっおいたす。したがっお、远加のPydanticコヌドがあれば、それも機胜したす。 - -デヌタベヌスのためにORMsや、ODMsなどの、Pydanticに基づく倖郚ラむブラリを備えおいたす。 - -これは、すべおが自動的に怜蚌されるため、倚くの堎合、リク゚ストから取埗したオブゞェクトを**デヌタベヌスに盎接**枡すこずができるずいうこずを意味しおいたす。 - -同じこずがその逆にも圓おはたり、倚くの堎合、デヌタベヌスから取埗したオブゞェクトを**クラむアントに盎接**枡すこずができたす。 - -**FastAPI**を䜿甚するず、**Pydantic**のすべおの機胜を利甚できたすFastAPIがPydanticに基づいおすべおのデヌタ凊理を行っおいるため。 - -* **brainfuckなし** - * スキヌマ定矩のためのマむクロ蚀語を新たに孊習する必芁はありたせん。 - * Pythonの型を知っおいる堎合は、既にPydanticの䜿甚方法を知っおいるに等しいです。 -* ナヌザヌの **IDE/リンタヌ/思考 ずうたく連携したす** - * Pydanticのデヌタ構造は、ナヌザヌが定矩するクラスの単なるむンスタンスであるため、オヌトコンプリヌト、リンティング、mypy、およびナヌザヌの盎感はすべお、怜蚌枈みのデヌタで適切に機胜するはずです。 -* **耇雑な構造**を怜蚌 - * 階局的なPydanticモデルや、Pythonの「`typing`」の「`list`」ず「`dict`」などの利甚。 - * バリデヌタヌにより、耇雑なデヌタスキヌマを明確か぀簡単に定矩、チェックし、JSONスキヌマずしお文曞化できたす。 - * 深く**ネストされたJSON**オブゞェクトを䜜成し、それらすべおを怜蚌しおアノテヌションを付けるこずができたす。 -* **拡匵可胜** - * Pydanticでは、カスタムデヌタ型を定矩できたす。たたは、バリデヌタヌデコレヌタヌで装食されたモデルのメ゜ッドを䜿甚しお怜蚌を拡匵できたす。 +* 圧倒的なパフォヌマンス。利甚可胜な最速クラスの Python フレヌムワヌクの 1 ぀で、**NodeJS** や **Go** ず同等です。 +* **WebSocket** のサポヌト。 +* プロセス内バックグラりンドタスク。 +* 起動およびシャットダりンむベント。 +* HTTPX に基づくテストクラむアント。 +* **CORS**、GZip、静的ファむル、ストリヌミングレスポンス。 +* **セッションず Cookie** のサポヌト。 +* テストカバレッゞ 100%。 +* 型アノテヌション 100% のコヌドベヌス。 + +## Pydanticの機胜 { #pydantic-features } + +**FastAPI** は Pydantic ず完党に互換性がありか぀それに基づいおいたす。そのため、手元の Pydantic の远加コヌドも動䜜したす。 + +Pydantic に基づく倖郚ラむブラリデヌタベヌス甚の ORM、ODM なども含たれたす。 + +これは、すべおが自動的に怜蚌されるため、倚くの堎合、リク゚ストから取埗したオブゞェクトを **そのたたデヌタベヌスに** 枡せるこずを意味したす。 + +逆方向も同様で、倚くの堎合、デヌタベヌスから取埗したオブゞェクトを **そのたたクラむアントに** 枡せたす。 + +**FastAPI** では **Pydantic** のすべおの機胜が利甚できたすFastAPI はデヌタ凊理のすべおで Pydantic に基づいおいたす: + +* **brainfuck なし** + * スキヌマ定矩のための新しいマむクロ蚀語を孊ぶ必芁はありたせん。 + * Python の型を知っおいれば、Pydantic の䜿い方もわかりたす。 +* **IDE/リンタヌ/思考** ず気持ちよく連携したす + * Pydantic のデヌタ構造は、あなたが定矩するクラスの単なるむンスタンスなので、オヌトコンプリヌト、リンティング、mypy、そしおあなたの盎感が、怜蚌枈みデヌタに察しお適切に機胜したす。 +* **耇雑な構造** を怜蚌 + * 階局的な Pydantic モデルや、Python の `typing` にある `List` や `Dict` などを利甚できたす。 + * さらにバリデヌタにより、耇雑なデヌタスキヌマを明確か぀容易に定矩・怜査でき、JSON Schema ずしお文曞化できたす。 + * 深く **ネストされた JSON** オブゞェクトを扱え、それらすべおを怜蚌しおアノテヌションを付䞎できたす。 +* **拡匵可胜** + * Pydantic ではカスタムデヌタ型を定矩できたすし、バリデヌタデコレヌタヌで装食したモデルメ゜ッドで怜蚌を拡匵できたす。 * テストカバレッゞ 100%。 diff --git a/docs/ja/docs/help-fastapi.md b/docs/ja/docs/help-fastapi.md index 8cf0c2163..ed91bb19f 100644 --- a/docs/ja/docs/help-fastapi.md +++ b/docs/ja/docs/help-fastapi.md @@ -1,101 +1,255 @@ -# FastAPIを応揎 - ヘルプの入手 +# FastAPIを応揎 - ヘルプの入手 { #help-fastapi-get-help } **FastAPI** は気に入りたしたか -FastAPIやナヌザヌや開発者を応揎したいですか +FastAPIや他のナヌザヌ、䜜者を応揎したいですか -もしくは、 **FastAPI** に぀いおヘルプが必芁ですか +それずも **FastAPI** に぀いおヘルプが必芁ですか -ずおも簡単に応揎できたす (ただ1、2回クリックするだけのものもありたす)。 +ずおも簡単に応揎できる方法がありたす1、2回クリックするだけのものもありたす。 -たた、ヘルプを入手する手段がいく぀かありたす。 +ヘルプを埗る方法もいく぀かありたす。 -## GitHubで **FastAPI** にStar +## ニュヌスレタヌを賌読 { #subscribe-to-the-newsletter } -GitHubでFastAPIに「Star」を぀けるこずができたす (右䞊郚のStarボタンをクリック): https://github.com/fastapi/fastapi. ⭐ +[**FastAPI and friends** ニュヌスレタヌ](newsletter.md){.internal-link target=_blank}配信はたれですを賌読するず、次の情報をキャッチアップできたす: -スタヌを増やすこずで、他のナヌザヌの目に぀きやすくなり、倚くの人にずっお䟿利なものであるこずを瀺せたす。 +* FastAPI ず関連プロゞェクトのニュヌス 🚀 +* ガむド 📝 +* 機胜 ✹ +* 互換性に圱響する倉曎 🚚 +* ヒントやコツ ✅ -## GitHubレポゞトリのリリヌスをWatch +## X (Twitter) で FastAPI をフォロヌ { #follow-fastapi-on-x-twitter } -GitHubでFastAPIを「Watch」できたす (右䞊郚のWatchボタンをクリック): https://github.com/fastapi/fastapi. 👀 +**X (Twitter)** で @fastapi をフォロヌしお、**FastAPI** の最新情報を受け取りたしょう。🐊 + +## GitHubで **FastAPI** にStar { #star-fastapi-in-github } + +GitHubでFastAPIに「Star」を぀けるこずができたす右䞊郚のStarボタンをクリック: https://github.com/fastapi/fastapi。⭐ + +スタヌを増やすこずで、他のナヌザヌの目に぀きやすくなり、すでに倚くの人の圹に立っおいるこずが䌝わりたす。 + +## GitHubレポゞトリのリリヌスをWatch { #watch-the-github-repository-for-releases } + +GitHubでFastAPIを「Watch」できたす右䞊郚の「Watch」ボタンをクリック: https://github.com/fastapi/fastapi。👀 そこで「Releases only」を遞択できたす。 -これを行うず、**FastAPI** バグ修正や新機胜の実装などの新しいリリヌス (新しいバヌゞョン) があるたびに (メヌルで) 通知を受け取れたす。 +これを行うず、バグ修正や新機胜を含む **FastAPI** の新しいリリヌス新バヌゞョンがあるたびに、メヌルで通知を受け取れたす。 -## 開発者ず぀ながる +## 開発者ず぀ながる { #connect-with-the-author } -以䞋で、開発者 (Sebastián Ramírez / `tiangolo`) ずコンタクトをずれたす: +䜜者である私Sebastián Ramírez / `tiangolo`ず぀ながれたす。 + +できるこず: * **GitHub** でフォロヌ。 - * 他のオヌプン゜ヌスプロゞェクトを確認できたす。䜕かの助けになるものが芋぀かるかもしれたせん。 - * 新たなオヌプン゜ヌスプロゞェクトを䜜成したずきに通知されたす。 -* **X (Twitter)** でフォロヌ。 - * FastAPIの䜿甚甚途を教えおください (聞いおみたいです)。 - * 新たなツヌルの発衚やリリヌスが聞けたす。 -* **Linkedin** で぀ながる。 - * 新たなツヌルの発衚やリリヌスが聞けたす (ただしX (Twitter)の方が利甚頻床が高いですが 🀷‍♂)。 -* **Dev.to** や **Medium** で著䜜物を読む (たたはフォロヌ)。 - * アむデアや䜜成ツヌルに぀いおの蚘事が読めたす。 - * 新芏蚘事の執筆を通知しおくれたす。 + * 圹に立぀かもしれない、私が䜜成した他のオヌプン゜ヌスプロゞェクトを芋られたす。 + * 新しいオヌプン゜ヌスプロゞェクトを䜜成したずきにわかりたす。 +* **X (Twitter)** でフォロヌ たたは Mastodon。 + * あなたがどのようにFastAPIを䜿っおいるか教えおください聞けるず嬉しいです。 + * 新しいツヌルの告知やリリヌスを聞けたす。 + * さらに、X (Twitter) の @fastapi別アカりントもフォロヌできたす。 +* **LinkedIn** でフォロヌ。 + * 新しいツヌルの告知やリリヌスを聞けたすただしX (Twitter) の方をよく䜿っおいたす 🀷‍♂。 +* **Dev.to** や **Medium** で執筆内容を読むたたはフォロヌ。 + * 私のアむデアや、䜜成したツヌルに関する蚘事を読めたす。 + * 新しい蚘事を公開したずきに読めたす。 -## **FastAPI** に関するツむヌト +## **FastAPI** に぀いおツむヌト { #tweet-about-fastapi } -**FastAPI** に぀いおツむヌトし、開発者や他の人にどこが気に入ったのか教えおください。🎉 +**FastAPI** に぀いおツむヌトしお、なぜ気に入っおいるのかを私や他の人に教えおください。🎉 -**FastAPI** がどのように䜿われ、どこが気に入られ、どんなプロゞェクト/䌚瀟で䜿われおいるかなどに぀いお知りたいです。 +**FastAPI** がどのように䜿われおいるか、どこを気に入っおいるか、どのプロゞェクト/䌚瀟で䜿っおいるか等、聞けるず嬉しいです。 -## FastAPIに投祚 +## FastAPIに投祚 { #vote-for-fastapi } -* Slantで **FastAPI** に投祚 -* AlternativeToで **FastAPI** に投祚 -* awesome-restで **FastAPI** に投祚 +* Slantで **FastAPI** に投祚。 +* AlternativeToで **FastAPI** に投祚。 +* StackShare で **FastAPI** を䜿っおいるず宣蚀。 -## GitHub issuesで他の人を助ける +## GitHubで質問に困っおいる人を助ける { #help-others-with-questions-in-github } -既存のissuesを確認しお、他の人を助けおみおください。皆さんが回答を知っおいるかもしれない質問がほずんどです。🀓 +次の堎所で、他の人の質問を手助けできたす: -## GitHubレポゞトリをWatch +* GitHub Discussions +* GitHub Issues -GitHubでFastAPIを「watch」できたす (右䞊郚の「watch」ボタンをクリック): https://github.com/fastapi/fastapi. 👀 +倚くの堎合、その質問の答えをすでに知っおいるかもしれたせん。🀓 -「Releases only」ではなく「Watching」を遞択するず、新たなissueが立おられた際に通知されたす。 +もし倚くの人の質問に答えお助けおくれたなら、あなたは公匏の[FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank}になりたす。🎉 -そしお、issueを解決し他の人を助けるこずができたす。 +最も倧事なポむントは「芪切であるこず」を心がけるこずです。人はフラストレヌションを抱えおやっお来るので、必ずしも最良の聞き方をしおいるずは限りたせんが、できる限り芪切に察応したしょう。🀗 -## issuesを立おる +**FastAPI** コミュニティは芪切で歓迎的であるこずを目指しおいたす。同時に、いじめや他者ぞの無瀌な振る舞いは受け入れないでください。お互いを倧事にしたしょう。 -GitHubレポゞトリで新たなissueを立おられたす。䟋えば: +--- -* 質問、たたは、問題の報告 -* 新機胜の提案 +以䞋はDiscussions や Issues で他の人の質問を手助けする方法です: -**Note**: issueを立おた人は、他の人の手助けもお願いしたす。😉 +### 質問を理解する { #understand-the-question } -## プルリク゚ストをする +* 質問者の「目的」やナヌスケヌスを理解できるか確認したす。 -以䞋の様なプルリク゚ストを䜜成できたす: +* 次に、質問倧半は質問ですが「明確」か確認したす。 -* ドキュメントのタむプミスを修正。 -* 新たなドキュメントセクションを提案。 -* 既存のissue/バグを修正。 -* 新機胜を远加。 +* 倚くの堎合、ナヌザヌが想像した解決策に぀いおの質問になっおいたすが、もっず「良い」方法があるかもしれたせん。問題やナヌスケヌスをよりよく理解できれば、より良い「代替解決策」を提案できるかもしれたせん。 -## 開発者のスポンサヌになる +* 質問が理解できない堎合は、さらに「詳现」を尋ねたす。 -GitHub sponsorsを通しお開発者を経枈的にサポヌトできたす。 +### 問題を再珟する { #reproduce-the-problem } -そこで、感謝の気持ちを䌝えるためにコヌヒヌ☕を買うこずができたす 😄。 +倚くのケヌスや質問は、その人の「元のコヌド」に関係しおいたす。 -## FastAPIを匷化するツヌルのスポンサヌになる +しばしばコヌドの断片だけが共有されたすが、それでは問題を「再珟」するには䞍十分です。 -ドキュメントで芋たように、FastAPIはStarletteずPydanticずいう巚人の肩に乗っおいたす。 +* ロヌカルで同じ゚ラヌや挙動を確認できるように、たたはナヌスケヌスをよりよく理解できるように、**コピヌ&ペヌスト**しお実行できる最小の再珟可胜な䟋の提䟛を䟝頌できたす。 -以䞋のスポンサヌになるこずもできたす: +* ずおも寛倧な気分なら、問題の説明だけをもずに、あなた自身でそのような**䟋を䜜成**しおみるこずもできたす。ただし時間がかかる可胜性が高いので、たずは問題の明確化を䟝頌した方が良い堎合もありたす。 -* Samuel Colvin (Pydantic) -* Encode (Starlette, Uvicorn) +### 解決策を提案する { #suggest-solutions } + +* 質問を理解できたら、可胜な**回答**を提瀺できたす。 + +* 倚くの堎合、盞手の「根本的な問題やナヌスケヌス」を理解するこずが重芁です。盞手が詊しおいる方法より良い解決方法があるかもしれないからです。 + +### クロヌズを䟝頌する { #ask-to-close } + +もし盞手が返信しおきお、あなたが問題を解決できたなら、おめでずう、**あなたはヒヌロヌ**です🊞 + +* その堎合、次のように䟝頌できたす: + + * GitHub Discussions: コメントを**回答**ずしおマヌクしおもらう。 + * GitHub Issues: issue を**クロヌズ**しおもらう。 + +## GitHubレポゞトリをWatch { #watch-the-github-repository } + +GitHubでFastAPIを「Watch」できたす右䞊郚の「Watch」ボタンをクリック: https://github.com/fastapi/fastapi。👀 + +「Releases only」ではなく「Watching」を遞択するず、新しい issue や質問が䜜成されたずきに通知を受け取れたす。新しい issue のみ、Discussions のみ、PR のみ、など通知察象を絞るこずもできたす。 + +その䞊で、そうした質問の解決を手助けできたす。 + +## 質問する { #ask-questions } + +GitHubレポゞトリで新しい質問を䜜成できたす。䟋えば: + +* **質問**をする、たたは**問題**に぀いお尋ねる。 +* 新しい**機胜**を提案する。 + +**Note**: もしそうするなら、他の人の手助けもお願いしたす。😉 + +## プルリク゚ストをレビュヌ { #review-pull-requests } + +他の人からのプルリク゚ストのレビュヌを手䌝っおもらえたす。 + +ここでも、できる限り芪切であるようにしおください。🀗 + +--- + +プルリク゚ストをレビュヌするずきのポむントです: + +### 問題を理解する { #understand-the-problem } + +* たず、そのプルリク゚ストが解決しようずしおいる**問題を理解**しおください。長めの議論が GitHub Discussion や issue にあるかもしれたせん。 + +* その問題は実は**別の方法**で解決でき、プルリク゚スト自䜓が䞍芁な堎合もありたす。その堎合は、その提案や質問をしおも良いでしょう。 + +### スタむルは気にしすぎない { #dont-worry-about-style } + +* コミットメッセヌゞのスタむルなどはあたり気にしなくお倧䞈倫です。私は squash and merge を䜿い、コミットを手動で調敎したす。 + +* スタむルルヌルに぀いおも心配無甚です。自動化ツヌルがすでにチェックしおいたす。 + +ほかにスタむルや䞀貫性の芁件があれば、私から盎接䟝頌したすし、必芁な倉曎を䞊に積む圢でコミットを远加したす。 + +### コヌドを確認 { #check-the-code } + +* コヌドを確認しお読み、劥圓かどうかを芋お、**ロヌカルで実行**し、本圓に問題を解決しおいるか確かめおください。 + +* そのうえで、それを行ったこずを**コメント**で䌝えおください。そうすれば、実際に確認しおくれたずわかりたす。 + +/// info | 情報 + +残念ながら、承認が耇数぀いただけのPRを、そのたた信頌するこずはできたせん。 + +説明が魅力的なためか、3件、5件以䞊の承認が぀いおいおも、実際にPRを確認するず壊れおいたり、バグがあったり、䞻匵する問題を解決しおいなかったりするこずが䜕床もありたした。😅 + +ですので、実際にコヌドを読み、実行しお確認し、それをコメントで知らせおもらえるこずが本圓に重芁です。🀓 + +/// + +* もしPRを簡玠化できそうなら、その䟝頌をしおも構いたせんが、现かい点にこだわり過ぎる必芁はありたせん。䞻芳的な芋方が倚く私にもありたす 🙈、基本的な点に集䞭できるずより良いでしょう。 + +### テスト { #tests } + +* PRに**テスト**があるか確認を手䌝っおください。 + +* PR前はテストが**倱敗**するこずを確認したす。🚚 + +* そしおPR埌にテストが**成功**するこずを確認したす。✅ + +* 倚くのPRにはテストがありたせん。テストの远加を**リマむンド**したり、テストを**提案**したりできたす。これは最も時間を消費する郚分の䞀぀で、倧いに助けになりたす。 + +* 䜕を詊したかもコメントしおください。そうすれば、確認しおくれたこずがわかりたす。🀓 + +## プルリク゚ストを䜜成 { #create-a-pull-request } + +[貢献](contributing.md){.internal-link target=_blank}ずしお、次のようにプルリク゚ストで゜ヌスコヌドに貢献できたす: + +* ドキュメントで芋぀けたタむポの修正。 +* 自分が䜜成/発芋した FastAPI に関する蚘事・動画・ポッドキャストを、このファむルを線集しお共有。 + * 該圓セクションの先頭にリンクを远加しおください。 +* 自分の蚀語ぞの[ドキュメント翻蚳を手䌝う](contributing.md#translations){.internal-link target=_blank}。 + * 他の人が䜜成した翻蚳のレビュヌも手䌝えたす。 +* 新しいドキュメントセクションの提案。 +* 既存のissue/バグの修正。 + * テストを远加しおください。 +* 新機胜の远加。 + * テストを远加しおください。 + * 関連があればドキュメントも远加しおください。 + +## FastAPIのメンテナンスを手䌝う { #help-maintain-fastapi } + +**FastAPI** のメンテナンスを手䌝っおください🀓 + +やるこずはたくさんあり、その倚くは**あなた**にもできたす。 + +今すぐできる䞻なタスクは次のずおりです: + +* [GitHubで質問に困っおいる人を助ける](#help-others-with-questions-in-github){.internal-link target=_blank}䞊のセクションを参照。 +* [プルリク゚ストをレビュヌ](#review-pull-requests){.internal-link target=_blank}䞊のセクションを参照。 + +この2぀が**最も時間を消費**したす。FastAPI のメンテナンス䜜業の䞭心です。 + +これを手䌝っおもらえるず、**FastAPIのメンテナンスに貢献**し、**より速く・より良く前進**できるようになりたす。🚀 + +## チャットに参加 { #join-the-chat } + +👥 Discord チャットサヌバヌ 👥 に参加し、FastAPI コミュニティのみんなず亀流したしょう。 + +/// tip | 豆知識 + +質問は GitHub Discussions に投皿しおください。そこなら[FastAPI Experts](fastapi-people.md#fastapi-experts){.internal-link target=_blank}から助けおもらえる可胜性がずっず高いです。 + +チャットは䞀般的な䌚話のみに䜿いたしょう。 + +/// + +### 質問でチャットを䜿わない { #dont-use-the-chat-for-questions } + +チャットは「自由な䌚話」がしやすいため、䞀般的すぎお答えにくい質問になりがちです。そのため、回答が埗られない可胜性がありたす。 + +GitHub では、テンプレヌトが正しい圢で質問を曞くのを助けおくれるため、良い回答を埗やすくなりたすし、質問する前に自分で問題を解決できるこずもありたす。さらにGitHubなら、時間がかかっおも私が必ずすべおに回答できるようにできたす。チャットでは私個人にはそれができたせん。😅 + +チャットでの䌚話はGitHubほど怜玢しやすくないため、質問ず回答が䌚話に埋もれがちです。そしお、[FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank}になるためにカりントされるのはGitHub䞊の掻動だけです。ですから、GitHubの方が泚目を集めやすいでしょう。 + +䞀方で、チャットには数千人のナヌザヌがいるため、ほが垞に誰かず䌚話できる可胜性が高いです。😄 + +## 䜜者をスポンサヌ { #sponsor-the-author } + +あなたの**補品/䌚瀟**が **FastAPI** に䟝存しおいる、たたは関連しおおり、そのナヌザヌにリヌチしたい堎合は、GitHub sponsors を通じお䜜者私を支揎できたす。プランに応じお、ドキュメントにバッゞが衚瀺されるなどの特兞がある堎合がありたす。🎁 --- diff --git a/docs/ja/docs/history-design-future.md b/docs/ja/docs/history-design-future.md index 6cfd1894d..146555708 100644 --- a/docs/ja/docs/history-design-future.md +++ b/docs/ja/docs/history-design-future.md @@ -1,13 +1,12 @@ -# 歎史、蚭蚈、そしおこれから +# 歎史、蚭蚈、そしおこれから { #history-design-and-future } -少し前に、**FastAPI** -のナヌザヌに以䞋の様に尋ねられたした: +少し前に、**FastAPI**のナヌザヌに以䞋の様に尋ねられたした: > このプロゞェクトの歎史は䜕もないずころから、数週間ですごいものができおいるようです。 [...] これがその歎史のほんの䞀郚です。 -## 代替手段 +## 代替手段 { #alternatives } 数幎前から、私は耇雑な芁件を持぀API (機械孊習、分散システム、非同期ゞョブ、NoSQLデヌタベヌスなど) を䜜成しおおり、いく぀かの開発者チヌムを率いおいたす。 @@ -19,7 +18,7 @@
-**FastAPI**は、代替ツヌルのこれたでの働きがなければ存圚しなかったでしょう。 +**FastAPI**は、他の人々のこれたでの働きがなければ存圚しなかったでしょう。 以前に䜜られた倚くのツヌルが、䜜成における刺激ずしお圹立っおきたした。 @@ -29,7 +28,7 @@
-## 調査 +## 調査 { #investigation } すべお既存の代替手段を䜿うこずで、そのすべおを孊び、アむデアを埗お、自分や䞀緒に仕事をしおきた開発者のチヌムにずっお最良の方法で組み合わせる機䌚を埗たした。 @@ -39,7 +38,7 @@ そこで、**FastAPI**のコヌドを曞き始める前に、OpenAPI、JSON Schema、OAuth2などの仕様を数ヶ月かけお勉匷し、それらの関係、重耇する箇所、盞違点を理解したした。 -## 蚭蚈 +## 蚭蚈 { #design } その埌、 (FastAPIを䜿う開発者ずしお) ナヌザヌが欲しい「API」の蚭蚈に時間を費やしたした。 @@ -53,19 +52,19 @@ すべおの箇所で、すべおの開発者に最高の開発䜓隓を提䟛したした。 -## 芁件 +## 芁件 { #requirements } いく぀かの代替手法を詊したあず、私は**Pydantic**の匷みを利甚するこずを決めたした。 そしお、JSON Schemaに完党に準拠するようにしたり、制玄宣蚀を定矩するさたざたな方法をサポヌトしたり、いく぀かの゚ディタヌでのテストに基づいお゚ディタヌのサポヌト (型チェック、自動補完) を改善するために貢献したした。 -開発䞭、もう1぀の重芁な鍵ずなる**Starlette**、にも貢献したした。 +開発䞭、もう1぀の重芁な鍵ずなる**Starlette**にも貢献したした。 -## 開発 +## 開発 { #development } 私が**FastAPI**自䜓の䜜成を開始した時には、ほずんどの郚分がすでに準備されおおり、蚭蚈が定矩され、必芁な条件ずツヌルの準備ができおいたした。そしお芏栌や仕様に関する知識が、明確になり、曎新されおいたした。 -## これから +## これから { #future } この時点ですでに、これらのアむデアを持った**FastAPI**が倚くの人の圹に立っおいるこずは明らかです。 diff --git a/docs/ja/docs/how-to/authentication-error-status-code.md b/docs/ja/docs/how-to/authentication-error-status-code.md new file mode 100644 index 000000000..9bef47644 --- /dev/null +++ b/docs/ja/docs/how-to/authentication-error-status-code.md @@ -0,0 +1,17 @@ +# 叀い 403 認蚌゚ラヌのステヌタスコヌドを䜿う { #use-old-403-authentication-error-status-codes } + +FastAPI バヌゞョン `0.122.0` より前は、統合されたセキュリティナヌティリティが認蚌に倱敗しおクラむアントぞ゚ラヌを返す際、HTTP ステヌタスコヌド `403 Forbidden` を䜿甚しおいたした。 + +FastAPI バヌゞョン `0.122.0` 以降では、より適切な HTTP ステヌタスコヌド `401 Unauthorized` を䜿甚し、HTTP 仕様に埓っおレスポンスに劥圓な `WWW-Authenticate` ヘッダヌを含めたす。RFC 7235、RFC 9110。 + +しかし、䜕らかの理由でクラむアントが埓来の挙動に䟝存しおいる堎合は、セキュリティクラスでメ゜ッド `make_not_authenticated_error` をオヌバヌラむドするこずで、その挙動に戻せたす。 + +たずえば、既定の `401 Unauthorized` ゚ラヌの代わりに `403 Forbidden` ゚ラヌを返す `HTTPBearer` のサブクラスを䜜成できたす: + +{* ../../docs_src/authentication_error_status_code/tutorial001_an_py310.py hl[9:13] *} + +/// tip | 豆知識 + +この関数は䟋倖むンスタンスを返す点に泚意しおください。ここでは䟋倖を送出したせん。送出は内郚の他のコヌドで行われたす。 + +/// diff --git a/docs/ja/docs/how-to/conditional-openapi.md b/docs/ja/docs/how-to/conditional-openapi.md index 9478f5c03..0febe1ef6 100644 --- a/docs/ja/docs/how-to/conditional-openapi.md +++ b/docs/ja/docs/how-to/conditional-openapi.md @@ -10,7 +10,7 @@ もしセキュリティ䞊の欠陥が゜ヌスコヌドにあるならば、それは存圚したたたです。 -ドキュメンテヌションを非衚瀺にするのは、単にあなたのAPIぞのアクセス方法を難解にするだけでなく、同時にあなた自身の本番環境でのAPIのデバッグを困難にしおしたう可胜性がありたす。単玔に、 Security through obscurity の䞀぀の圢態ずしお考えられるでしょう。 +ドキュメンテヌションを非衚瀺にするのは、単にあなたのAPIぞのアクセス方法を難解にするだけでなく、同時にあなた自身の本番環境でのAPIのデバッグを困難にしおしたう可胜性がありたす。単玔に、 秘匿によるセキュリティ の䞀぀の圢態ずしお考えられるでしょう。 もしあなたのAPIのセキュリティを匷化したいなら、いく぀かのよりよい方法がありたす。䟋を瀺すず、 @@ -29,7 +29,7 @@ 䟋えば、 -{* ../../docs_src/conditional_openapi/tutorial001_py39.py hl[6,11] *} +{* ../../docs_src/conditional_openapi/tutorial001_py310.py hl[6,11] *} ここでは `openapi_url` の蚭定を、デフォルトの `"/openapi.json"` のたた宣蚀しおいたす。 diff --git a/docs/ja/docs/how-to/configure-swagger-ui.md b/docs/ja/docs/how-to/configure-swagger-ui.md new file mode 100644 index 000000000..8be7adc84 --- /dev/null +++ b/docs/ja/docs/how-to/configure-swagger-ui.md @@ -0,0 +1,70 @@ +# Swagger UI の蚭定 { #configure-swagger-ui } + +いく぀かの远加の Swagger UI パラメヌタを蚭定できたす。 + +蚭定するには、`FastAPI()` のアプリオブゞェクトを䜜成するずき、たたは `get_swagger_ui_html()` 関数に `swagger_ui_parameters` 匕数を枡したす。 + +`swagger_ui_parameters` は、Swagger UI に盎接枡される蚭定を含む蟞曞を受け取りたす。 + +FastAPI はそれらの蚭定を **JSON** に倉換し、JavaScript ず互換にしたす。Swagger UI が必芁ずするのはこの圢匏です。 + +## シンタックスハむラむトを無効化 { #disable-syntax-highlighting } + +䟋えば、Swagger UI のシンタックスハむラむトを無効化できたす。 + +蚭定を倉曎しなければ、シンタックスハむラむトはデフォルトで有効です: + + + +しかし、`syntaxHighlight` を `False` に蚭定するず無効化できたす: + +{* ../../docs_src/configure_swagger_ui/tutorial001_py310.py hl[3] *} + +...その堎合、Swagger UI ではシンタックスハむラむトが衚瀺されなくなりたす: + + + +## テヌマの倉曎 { #change-the-theme } + +同様に、キヌ `"syntaxHighlight.theme"`途䞭にドットが含たれおいる点に泚意でシンタックスハむラむトのテヌマを蚭定できたす: + +{* ../../docs_src/configure_swagger_ui/tutorial002_py310.py hl[3] *} + +この蚭定により、シンタックスハむラむトの配色テヌマが倉わりたす: + + + +## 既定の Swagger UI パラメヌタの倉曎 { #change-default-swagger-ui-parameters } + +FastAPI には、倚くのナヌスケヌスに適した既定の蚭定パラメヌタが含たれおいたす。 + +既定では次の蚭定が含たれたす: + +{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *} + +匕数 `swagger_ui_parameters` に別の倀を指定するこずで、これらを䞊曞きできたす。 + +䟋えば、`deepLinking` を無効化するには、次の蚭定を `swagger_ui_parameters` に枡したす: + +{* ../../docs_src/configure_swagger_ui/tutorial003_py310.py hl[3] *} + +## その他の Swagger UI パラメヌタ { #other-swagger-ui-parameters } + +利甚可胜な他のすべおの蚭定に぀いおは、公匏の Swagger UI パラメヌタのドキュメントを参照しおください。 + +## JavaScript 専甚の蚭定 { #javascript-only-settings } + +Swagger UI では、他にも **JavaScript 専甚** のオブゞェクト䟋: JavaScript の関数による蚭定が可胜です。 + +FastAPI には、次の JavaScript 専甚の `presets` 蚭定も含たれおいたす: + +```JavaScript +presets: [ + SwaggerUIBundle.presets.apis, + SwaggerUIBundle.SwaggerUIStandalonePreset +] +``` + +これらは文字列ではなく **JavaScript** のオブゞェクトであるため、Python のコヌドから盎接枡すこずはできたせん。 + +そのような JavaScript 専甚の蚭定を䜿う必芁がある堎合は、䞊蚘のいずれかの方法を䜿甚し、Swagger UI の path operation をオヌバヌラむドしお、必芁な JavaScript を手動で蚘述しおください。 diff --git a/docs/ja/docs/how-to/custom-docs-ui-assets.md b/docs/ja/docs/how-to/custom-docs-ui-assets.md new file mode 100644 index 000000000..c0c9745b2 --- /dev/null +++ b/docs/ja/docs/how-to/custom-docs-ui-assets.md @@ -0,0 +1,185 @@ +# カスタムドキュメント UI の静的アセットセルフホスティング { #custom-docs-ui-static-assets-self-hosting } + +API ドキュメントは **Swagger UI** ず **ReDoc** を䜿甚しおおり、それぞれにいく぀かの JavaScript ず CSS ファむルが必芁です。 + +既定では、これらのファむルは CDN から配信されたす。 + +しかし、カスタマむズするこずも可胜で、特定の CDN を指定したり、自分でファむルを配信したりできたす。 + +## JavaScript ず CSS のカスタム CDN { #custom-cdn-for-javascript-and-css } + +別の CDN を䜿いたいずしたす。䟋えば `https://unpkg.com/` を䜿いたい堎合です。 + +䟋えば、䞀郚の URL が制限されおいる囜に䜏んでいる堎合に圹立ちたす。 + +### 自動ドキュメントの無効化 { #disable-the-automatic-docs } + +最初の手順は自動ドキュメントを無効化するこずです。デフォルトではそれらは既定の CDN を䜿甚したす。 + +無効化するには、`FastAPI` アプリ䜜成時にそれらの URL を `None` に蚭定したす: + +{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[8] *} + +### カスタムドキュメントの远加 { #include-the-custom-docs } + +これで、カスタムドキュメント甚の *path operations* を䜜成できたす。 + +FastAPI の内郚関数を再利甚しおドキュメント甚の HTML ペヌゞを生成し、必芁な匕数を枡せたす: + +- `openapi_url`: ドキュメントの HTML ペヌゞが API の OpenAPI スキヌマを取埗する URL。ここでは属性 `app.openapi_url` を䜿甚できたす。 +- `title`: API のタむトル。 +- `oauth2_redirect_url`: 既定倀を䜿うにはここで `app.swagger_ui_oauth2_redirect_url` を䜿甚できたす。 +- `swagger_js_url`: Swagger UI ドキュメント甚の HTML が取埗する JavaScript ファむルの URL。これはカスタム CDN の URL です。 +- `swagger_css_url`: Swagger UI ドキュメント甚の HTML が取埗する CSS ファむルの URL。これはカスタム CDN の URL です。 + +ReDoc に぀いおも同様です... + +{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[2:6,11:19,22:24,27:33] *} + +/// tip | 豆知識 + +`swagger_ui_redirect` 甚の *path operation* は、OAuth2 を䜿甚する堎合の補助です。 + +API を OAuth2 プロバむダず統合するず、認蚌を実行しお取埗したクレデンシャルを持った状態で API ドキュメントに戻れたす。そしお実際の OAuth2 認蚌を甚いおドキュメント䞊から API ず察話できたす。 + +Swagger UI がこの凊理を裏偎で行いたすが、そのためにこの「redirect」の補助が必芁です。 + +/// + +### テスト甚の *path operation* を䜜成 { #create-a-path-operation-to-test-it } + +すべおが動䜜するかをテストできるように、*path operation* を䜜成したす: + +{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[36:38] *} + +### テスト { #test-it } + +これで、http://127.0.0.1:8000/docs にアクセスしおペヌゞを再読み蟌みするず、新しい CDN からそれらのアセットが読み蟌たれるはずです。 + +## ドキュメント甚 JavaScript ず CSS のセルフホスティング { #self-hosting-javascript-and-css-for-docs } + +オフラむンむンタヌネット非接続でも、あるいはロヌカルネットワヌクで、アプリを動䜜させたい堎合などには、JavaScript ず CSS をセルフホストするのが有甚です。 + +ここでは、同じ FastAPI アプリ内でそれらのファむルを配信し、ドキュメントでそれらを䜿甚するように蚭定する方法を瀺したす。 + +### プロゞェクトのファむル構成 { #project-file-structure } + +プロゞェクトのファむル構成が次のようになっおいるずしたす: + +``` +. +├── app +│ ├── __init__.py +│ ├── main.py +``` + +これらの静的ファむルを保存するためのディレクトリを䜜成したす。 + +新しいファむル構成は次のようになりたす: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +└── static/ +``` + +### ファむルのダりンロヌド { #download-the-files } + +ドキュメントに必芁な静的ファむルをダりンロヌドし、`static/` ディレクトリに配眮したす。 + +各リンクを右クリックしお「リンク先を別名で保存...」のようなオプションを遞べたす。 + +**Swagger UI** では次のファむルを䜿甚したす: + +- `swagger-ui-bundle.js` +- `swagger-ui.css` + +そしお **ReDoc** では次のファむルを䜿甚したす: + +- `redoc.standalone.js` + +その埌、ファむル構成は次のようになりたす: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +└── static + ├── redoc.standalone.js + ├── swagger-ui-bundle.js + └── swagger-ui.css +``` + +### 静的ファむルの配信 { #serve-the-static-files } + +- `StaticFiles` をむンポヌトしたす。 +- 特定のパスに `StaticFiles()` むンスタンスを「マりント」したす。 + +{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[7,11] *} + +### 静的ファむルのテスト { #test-the-static-files } + +アプリケヌションを起動し、http://127.0.0.1:8000/static/redoc.standalone.js にアクセスしたす。 + +**ReDoc** 甚の非垞に長い JavaScript ファむルが衚瀺されるはずです。 + +先頭は次のようになっおいるかもしれたせん: + +```JavaScript +/*! For license information please see redoc.standalone.js.LICENSE.txt */ +!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")): +... +``` + +これで、アプリから静的ファむルを配信できおいるこず、そしおドキュメント甚の静的ファむルを正しい堎所に配眮できおいるこずが確認できたす。 + +次に、ドキュメントでそれらの静的ファむルを䜿甚するようにアプリを蚭定したす。 + +### 静的ファむル甚に自動ドキュメントを無効化 { #disable-the-automatic-docs-for-static-files } + +カスタム CDN を䜿う堎合ず同様、最初の手順は自動ドキュメントを無効化するこずです。既定では CDN を䜿甚したす。 + +無効化するには、`FastAPI` アプリ䜜成時にそれらの URL を `None` に蚭定したす: + +{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[9] *} + +### 静的ファむル甚のカスタムドキュメントを远加 { #include-the-custom-docs-for-static-files } + +カスタム CDN ず同様の方法で、カスタムドキュメント甚の *path operations* を䜜成できたす。 + +再び、FastAPI の内郚関数を再利甚しおドキュメント甚の HTML ペヌゞを生成し、必芁な匕数を枡したす: + +- `openapi_url`: ドキュメントの HTML ペヌゞが API の OpenAPI スキヌマを取埗する URL。ここでは属性 `app.openapi_url` を䜿甚できたす。 +- `title`: API のタむトル。 +- `oauth2_redirect_url`: 既定倀を䜿うにはここで `app.swagger_ui_oauth2_redirect_url` を䜿甚できたす。 +- `swagger_js_url`: Swagger UI ドキュメント甚の HTML が取埗する **JavaScript** ファむルの URL。**これはあなたのアプリ自身がいた配信しおいるものです**。 +- `swagger_css_url`: Swagger UI ドキュメント甚の HTML が取埗する **CSS** ファむルの URL。**これはあなたのアプリ自身がいた配信しおいるものです**。 + +ReDoc に぀いおも同様です... + +{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[2:6,14:22,25:27,30:36] *} + +/// tip | 豆知識 + +`swagger_ui_redirect` 甚の *path operation* は、OAuth2 を䜿甚する堎合の補助です。 + +API を OAuth2 プロバむダず統合するず、認蚌を実行しお取埗したクレデンシャルを持った状態で API ドキュメントに戻れたす。そしお実際の OAuth2 認蚌を甚いおドキュメント䞊から API ず察話できたす。 + +Swagger UI がこの凊理を裏偎で行いたすが、そのためにこの「redirect」の補助が必芁です。 + +/// + +### 静的ファむルをテストするための *path operation* を䜜成 { #create-a-path-operation-to-test-static-files } + +すべおが動䜜するかをテストできるように、*path operation* を䜜成したす: + +{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[39:41] *} + +### 静的ファむル UI のテスト { #test-static-files-ui } + +これで、WiFi を切断しお http://127.0.0.1:8000/docs にアクセスし、ペヌゞを再読み蟌みできるはずです。 + +むンタヌネットに接続しおいなくおも、API のドキュメントを衚瀺し、API ず察話できたす。 diff --git a/docs/ja/docs/how-to/custom-request-and-route.md b/docs/ja/docs/how-to/custom-request-and-route.md new file mode 100644 index 000000000..ae64f3109 --- /dev/null +++ b/docs/ja/docs/how-to/custom-request-and-route.md @@ -0,0 +1,109 @@ +# カスタム Request ず APIRoute クラス { #custom-request-and-apiroute-class } + +堎合によっおは、`Request` や `APIRoute` クラスで䜿われるロゞックを䞊曞きしたいこずがありたす。 + +特に、ミドルりェアでのロゞックの代替ずしお有効な堎合がありたす。 + +たずえば、アプリケヌションで凊理される前にリク゚ストボディを読み取ったり操䜜したりしたい堎合です。 + +/// danger | è­Šå‘Š + +これは「䞊玚」機胜です。 + +FastAPI を始めたばかりの堎合は、このセクションは読み飛ばしおもよいでしょう。 + +/// + +## ナヌスケヌス { #use-cases } + +ナヌスケヌスの䟋: + +* JSON ではないリク゚ストボディを JSON に倉換する䟋: `msgpack`。 +* gzip 圧瞮されたリク゚ストボディの解凍。 +* すべおのリク゚ストボディの自動ロギング。 + +## カスタムリク゚ストボディの゚ンコヌディングの凊理 { #handling-custom-request-body-encodings } + +gzip のリク゚ストを解凍するために、カスタムの `Request` サブクラスを䜿う方法を芋おいきたす。 + +そしお、そのカスタムリク゚ストクラスを䜿うための `APIRoute` サブクラスを甚意したす。 + +### カスタム `GzipRequest` クラスの䜜成 { #create-a-custom-gziprequest-class } + +/// tip | 豆知識 + +これは仕組みを瀺すためのサンプルです。Gzip 察応が必芁な堎合は、甚意されおいる [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} を䜿甚できたす。 + +/// + +たず、`GzipRequest` クラスを䜜成したす。これは適切なヘッダヌがある堎合に本䜓を解凍するよう、`Request.body()` メ゜ッドを䞊曞きしたす。 + +ヘッダヌに `gzip` がなければ、解凍は詊みたせん。 + +この方法により、同じルヌトクラスで gzip 圧瞮枈み未圧瞮のリク゚ストの䞡方を扱えたす。 + +{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *} + +### カスタム `GzipRoute` クラスの䜜成 { #create-a-custom-gziproute-class } + +次に、`GzipRequest` を利甚する `fastapi.routing.APIRoute` のカスタムサブクラスを䜜成したす。 + +ここでは `APIRoute.get_route_handler()` メ゜ッドを䞊曞きしたす。 + +このメ゜ッドは関数を返したす。そしおその関数がリク゚ストを受け取り、レスポンスを返したす。 + +ここでは、元のリク゚ストから `GzipRequest` を䜜成するために利甚したす。 + +{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *} + +/// note | 技術詳现 + +`Request` には `request.scope` 属性があり、これはリク゚ストに関するメタデヌタを含む Python の `dict` です。 + +`Request` には `request.receive` もあり、これはリク゚ストの本䜓を「受信」するための関数です。 + +`scope` の `dict` ず `receive` 関数はいずれも ASGI 仕様の䞀郚です。 + +そしおこの 2 ぀`scope` ず `receive`が、新しい `Request` むンスタンスを䜜成するために必芁なものです。 + +`Request` に぀いお詳しくは、Starlette の Requests に関するドキュメント を参照しおください。 + +/// + +`GzipRequest.get_route_handler` が返す関数が異なるのは、`Request` を `GzipRequest` に倉換する点だけです。 + +これにより、`GzipRequest` は必芁に応じおデヌタを解凍しおから *path operations* に枡したす。 + +それ以降の凊理ロゞックはすべお同じです。 + +ただし、`GzipRequest.body` を倉曎しおいるため、必芁に応じお **FastAPI** によっお読み蟌たれる際にリク゚ストボディが自動的に解凍されたす。 + +## 䟋倖ハンドラでのリク゚ストボディぞのアクセス { #accessing-the-request-body-in-an-exception-handler } + +/// tip | 豆知識 + +同じ問題を解決するには、`RequestValidationError` 甚のカスタムハンドラで `body` を䜿う方がずっず簡単でしょう[゚ラヌ凊理](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}。 + +ただし、この䟋も有効で、内郚コンポヌネントずどのようにやり取りするかを瀺しおいたす。 + +/// + +同じアプロヌチを䜿っお、䟋倖ハンドラ内でリク゚ストボディにアクセスするこずもできたす。 + +やるこずは、`try`/`except` ブロックの䞭でリク゚ストを凊理するだけです + +{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *} + +䟋倖が発生しおも、`Request` むンスタンスはスコヌプ内に残るため、゚ラヌ凊理時にリク゚ストボディを読み取り、掻甚できたす + +{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *} + +## ルヌタヌでのカスタム `APIRoute` クラス { #custom-apiroute-class-in-a-router } + +`APIRouter` の `route_class` パラメヌタを蚭定するこずもできたす + +{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[26] *} + +この䟋では、`router` 配䞋の *path operations* はカスタムの `TimedRoute` クラスを䜿甚し、レスポンスの生成にかかった時間を瀺す远加の `X-Response-Time` ヘッダヌがレスポンスに含たれたす + +{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *} diff --git a/docs/ja/docs/how-to/extending-openapi.md b/docs/ja/docs/how-to/extending-openapi.md new file mode 100644 index 000000000..df5b3cd35 --- /dev/null +++ b/docs/ja/docs/how-to/extending-openapi.md @@ -0,0 +1,80 @@ +# OpenAPI の拡匵 { #extending-openapi } + +生成された OpenAPI スキヌマを倉曎する必芁がある堎合がありたす。 + +このセクションではその方法を説明したす。 + +## 通垞のプロセス { #the-normal-process } + +通垞デフォルトのプロセスは次のずおりです。 + +`FastAPI` アプリケヌションむンスタンスには、OpenAPI スキヌマを返すこずが期埅される `.openapi()` メ゜ッドがありたす。 + +アプリケヌションオブゞェクトの䜜成時に、`/openapi.json`たたは `openapi_url` に蚭定したパスぞの path operation が登録されたす。 + +これは単に、アプリケヌションの `.openapi()` メ゜ッドの結果を含む JSON レスポンスを返したす。 + +デフォルトでは、`.openapi()` メ゜ッドはプロパティ `.openapi_schema` に内容があるかを確認し、あればそれを返したす。 + +なければ、`fastapi.openapi.utils.get_openapi` にあるナヌティリティ関数を䜿っお生成したす。 + +この関数 `get_openapi()` は次の匕数を受け取りたす: + +- `title`: ドキュメントに衚瀺される OpenAPI のタむトル。 +- `version`: API のバヌゞョン。䟋: `2.5.0`。 +- `openapi_version`: 䜿甚する OpenAPI 仕様のバヌゞョン。デフォルトは最新の `3.1.0`。 +- `summary`: API の短い抂芁。 +- `description`: API の説明。Markdown を含めるこずができ、ドキュメントに衚瀺されたす。 +- `routes`: ルヌトのリスト。登録枈みの各 path operation です。`app.routes` から取埗されたす。 + +/// info | 情報 + +パラメヌタ `summary` は OpenAPI 3.1.0 以降で利甚可胜で、FastAPI 0.99.0 以降が察応しおいたす。 + +/// + +## デフォルトの䞊曞き { #overriding-the-defaults } + +䞊蚘の情報を䜿っお、同じナヌティリティ関数で OpenAPI スキヌマを生成し、必芁な郚分を䞊曞きできたす。 + +たずえば、カスタムロゎを含めるための ReDoc の OpenAPI 拡匵を远加しおみたしょう。 + +### 通垞の **FastAPI** { #normal-fastapi } + +たず、通垞どおりに **FastAPI** アプリケヌションを実装したす: + +{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[1,4,7:9] *} + +### OpenAPI スキヌマの生成 { #generate-the-openapi-schema } + +次に、`custom_openapi()` 関数内で同じナヌティリティ関数を䜿っお OpenAPI スキヌマを生成したす: + +{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[2,15:21] *} + +### OpenAPI スキヌマの倉曎 { #modify-the-openapi-schema } + +OpenAPI スキヌマの `info`「オブゞェクト」にカスタムの `x-logo` を远加しお、ReDoc 拡匵を加えたす: + +{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[22:24] *} + +### OpenAPI スキヌマのキャッシュ { #cache-the-openapi-schema } + +生成したスキヌマを保持する「キャッシュ」ずしお `.openapi_schema` プロパティを利甚できたす。 + +こうするこずで、ナヌザヌが API ドキュメントを開くたびにスキヌマを生成する必芁がなくなりたす。 + +最初の1回だけ生成され、その埌は同じキャッシュ枈みスキヌマが以降のリク゚ストで䜿われたす。 + +{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[13:14,25:26] *} + +### メ゜ッドの䞊曞き { #override-the-method } + +これで、`.openapi()` メ゜ッドを新しい関数に眮き換えられたす。 + +{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[29] *} + +### 確認 { #check-it } + +http://127.0.0.1:8000/redoc にアクセスするず、カスタムロゎこの䟋では **FastAPI** のロゎが䜿われおいるこずが確認できたす: + + diff --git a/docs/ja/docs/how-to/general.md b/docs/ja/docs/how-to/general.md new file mode 100644 index 000000000..8879c68eb --- /dev/null +++ b/docs/ja/docs/how-to/general.md @@ -0,0 +1,39 @@ +# 䞀般 - ハりツヌ - レシピ { #general-how-to-recipes } + +ここでは、䞀般的たたはよくある質問に察しお、ドキュメント内の他の箇所ぞの参照をいく぀か瀺したす。 + +## デヌタのフィルタリング - セキュリティ { #filter-data-security } + +返すべき以䞊のデヌタを返さないようにするには、[チュヌトリアル - レスポンスモデル - 戻り倀の型](../tutorial/response-model.md){.internal-link target=_blank} を参照しおください。 + +## ドキュメントのタグ - OpenAPI { #documentation-tags-openapi } + +*path operations* にタグを远加し、ドキュメント UI でグルヌプ化するには、[チュヌトリアル - path operation の蚭定 - タグ](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} を参照しおください。 + +## ドキュメントの抂芁ず説明 - OpenAPI { #documentation-summary-and-description-openapi } + +*path operations* に抂芁ず説明を远加し、ドキュメント UI に衚瀺するには、[チュヌトリアル - path operation の蚭定 - 抂芁ず説明](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} を参照しおください。 + +## ドキュメントのレスポンス説明 - OpenAPI { #documentation-response-description-openapi } + +ドキュメント UI に衚瀺されるレスポンスの説明を定矩するには、[チュヌトリアル - path operation の蚭定 - レスポンスの説明](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} を参照しおください。 + +## *Path Operation* の非掚奚化 - OpenAPI { #documentation-deprecate-a-path-operation-openapi } + +*path operation* を非掚奚にし、ドキュメント UI に衚瀺するには、[チュヌトリアル - path operation の蚭定 - 非掚奚](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} を参照しおください。 + +## 任意のデヌタを JSON 互換に倉換 { #convert-any-data-to-json-compatible } + +任意のデヌタを JSON 互換に倉換するには、[チュヌトリアル - JSON 互換゚ンコヌダ](../tutorial/encoder.md){.internal-link target=_blank} を参照しおください。 + +## OpenAPI メタデヌタ - ドキュメント { #openapi-metadata-docs } + +ラむセンス、バヌゞョン、連絡先などを含むメタデヌタを OpenAPI スキヌマに远加するには、[チュヌトリアル - メタデヌタずドキュメントの URL](../tutorial/metadata.md){.internal-link target=_blank} を参照しおください。 + +## OpenAPI のカスタム URL { #openapi-custom-url } + +OpenAPI の URL をカスタマむズたたは削陀するには、[チュヌトリアル - メタデヌタずドキュメントの URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} を参照しおください。 + +## OpenAPI ドキュメントの URL { #openapi-docs-urls } + +自動生成されるドキュメント UI が䜿甚する URL を倉曎するには、[チュヌトリアル - メタデヌタずドキュメントの URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} を参照しおください。 diff --git a/docs/ja/docs/how-to/graphql.md b/docs/ja/docs/how-to/graphql.md new file mode 100644 index 000000000..bd0d22349 --- /dev/null +++ b/docs/ja/docs/how-to/graphql.md @@ -0,0 +1,60 @@ +# GraphQL { #graphql } + +**FastAPI** は **ASGI** 暙準に基づいおいるため、ASGI に察応した任意の **GraphQL** ラむブラリを簡単に統合できたす。 + +同じアプリケヌション内で通垞の FastAPI の *path operation* ず GraphQL を組み合わせお䜿えたす。 + +/// tip | 豆知識 + +**GraphQL** は非垞に特定のナヌスケヌスを解決したす。 + +䞀般的な **Web API** ず比べるず、**長所** ず **短所** がありたす。 + +ご自身のナヌスケヌスで埗られる **利点** が **欠点** を補うかどうかを評䟡しおください。 🀓 + +/// + +## GraphQL ラむブラリ { #graphql-libraries } + +**ASGI** をサポヌトする **GraphQL** ラむブラリの䞀郚を以䞋に瀺したす。**FastAPI** ず組み合わせお䜿甚できたす: + +* Strawberry 🍓 + * FastAPI 向けドキュメントあり +* Ariadne + * FastAPI 向けドキュメントあり +* Tartiflette + * ASGI 連携甚の Tartiflette ASGI あり +* Graphene + * starlette-graphene3 あり + +## Strawberry で GraphQL { #graphql-with-strawberry } + +**GraphQL** が必芁、たたは利甚したい堎合は、**Strawberry** を**掚奚**したす。**FastAPI** の蚭蚈に最も近く、すべおが**型アノテヌション**に基づいおいたす。 + +ナヌスケヌスによっおは他のラむブラリを遞ぶ方がよい堎合もありたすが、私に尋ねられれば、おそらく **Strawberry** を詊すこずを勧めるでしょう。 + +FastAPI ず Strawberry を統合する方法の簡単なプレビュヌです: + +{* ../../docs_src/graphql_/tutorial001_py310.py hl[3,22,25] *} + +詳现は Strawberry のドキュメントをご芧ください。 + +たた、Strawberry ず FastAPI の連携に関するドキュメントもありたす。 + +## Starlette の旧 `GraphQLApp` { #older-graphqlapp-from-starlette } + +以前の Starlette には、Graphene ず統合するための `GraphQLApp` クラスが含たれおいたした。 + +これは Starlette からは非掚奚になりたしたが、もしそれを䜿甚しおいるコヌドがある堎合は、同じナヌスケヌスをカバヌし、**ほが同䞀のむンタヌフェヌス**を持぀ starlette-graphene3 ぞ容易に**移行**できたす。 + +/// tip | 豆知識 + +GraphQL が必芁であれば、䟝然ずしお Strawberry の利甚を掚奚したす。独自のクラスや型ではなく、型アノテヌションに基づいおいるためです。 + +/// + +## さらに孊ぶ { #learn-more } + +**GraphQL** に぀いおは、公匏 GraphQL ドキュメントでさらに孊べたす。 + +䞊蚘の各ラむブラリに぀いおは、リンク先のドキュメントをご参照ください。 diff --git a/docs/ja/docs/how-to/index.md b/docs/ja/docs/how-to/index.md new file mode 100644 index 000000000..b1cd17785 --- /dev/null +++ b/docs/ja/docs/how-to/index.md @@ -0,0 +1,13 @@ +# ハりツヌ - レシピ { #how-to-recipes } + +ここでは、**耇数のトピック**に関するさたざたなレシピや「ハりツヌ」ガむドを玹介したす。 + +これらのアむデアの倚くはおおむね**独立**しおおり、ほずんどの堎合、**あなたのプロゞェクト**に盎接圓おはたるものだけを読めば十分です。 + +プロゞェクトにずっお興味深く有甚だず思うものがあれば、ぜひ確認しおください。そうでなければ、読み飛ばしおも問題ありたせん。 + +/// tip | 豆知識 + +**FastAPI を孊ぶ**こずを䜓系的に進めたい堎合掚奚、代わりに [チュヌトリアル - ナヌザヌガむド](../tutorial/index.md){.internal-link target=_blank} を章ごずに読んでください。 + +/// diff --git a/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md new file mode 100644 index 000000000..f1414ac28 --- /dev/null +++ b/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -0,0 +1,135 @@ +# Pydantic v1 から Pydantic v2 ぞの移行 { #migrate-from-pydantic-v1-to-pydantic-v2 } + +叀い FastAPI アプリがある堎合、Pydantic v1 を䜿っおいるかもしれたせん。 + +FastAPI 0.100.0 は Pydantic v1 / v2 のどちらにも察応しおおり、むンストヌルされおいる方を䜿甚したした。 + +FastAPI 0.119.0 では、Pydantic v2 内からの Pydantic v1 の郚分的サポヌト`pydantic.v1`が導入され、v2 ぞの移行が容易になりたした。 + +FastAPI 0.126.0 で Pydantic v1 のサポヌトは終了したしたが、しばらくの間は `pydantic.v1` は利甚可胜でした。 + +/// warning | 泚意 + +Pydantic チヌムは Python の最新バヌゞョン、぀たり **Python 3.14** から、Pydantic v1 のサポヌトを終了したした。 + +これには `pydantic.v1` も含たれ、Python 3.14 以䞊ではサポヌトされたせん。 + +Python の最新機胜を䜿いたい堎合は、Pydantic v2 を䜿甚しおいるこずを確認する必芁がありたす。 + +/// + +叀い FastAPI アプリで Pydantic v1 を䜿っおいる堎合、ここでは Pydantic v2 ぞの移行方法ず、段階的移行を助ける **FastAPI 0.119.0 の機胜** を玹介したす。 + +## 公匏ガむド { #official-guide } + +Pydantic には v1 から v2 ぞの公匏の 移行ガむド がありたす。 + +倉曎点、怜蚌がより正確で厳密になった点、泚意事項などが含たれたす。 + +䜕が倉わったかをよりよく理解するために参照しおください。 + +## テスト { #tests } + +アプリに察する[テスト](../tutorial/testing.md){.internal-link target=_blank}を甚意し、継続的むンテグレヌションCIで実行するようにしおください。 + +これにより、アップグレヌド埌も期埅どおり動䜜しおいるこずを確認できたす。 + +## `bump-pydantic` { #bump-pydantic } + +倚くの堎合、カスタマむズのない通垞の Pydantic モデルを䜿っおいれば、v1 から v2 ぞの移行䜜業の倧半を自動化できたす。 + +同じ Pydantic チヌムが提䟛する `bump-pydantic` を䜿甚できたす。 + +このツヌルは必芁なコヌド倉曎のほずんどを自動で行いたす。 + +その埌テストを実行し、問題なければ完了です。😎 + +## v2 における Pydantic v1 { #pydantic-v1-in-v2 } + +Pydantic v2 には、Pydantic v1 がサブモゞュヌル `pydantic.v1` ずしお同梱されおいたす。ただし、これは Python 3.13 を超えるバヌゞョンではサポヌトされたせん。 + +぀たり、Pydantic v2 の最新バヌゞョンをむンストヌルし、このサブモゞュヌルから旧 Pydantic v1 のコンポヌネントをむンポヌトしお、あたかも v1 をむンストヌルしおいるかのように䜿甚できたす。 + +{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *} + +### v2 内の Pydantic v1 に察する FastAPI のサポヌト { #fastapi-support-for-pydantic-v1-in-v2 } + +FastAPI 0.119.0 以降では、移行を容易にするため、Pydantic v2 内の Pydantic v1 に察する郚分的サポヌトもありたす。 + +そのため、Pydantic を v2 の最新に䞊げ、むンポヌトを `pydantic.v1` サブモゞュヌルに切り替えるだけで、倚くの堎合そのたた動䜜したす。 + +{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *} + +/// warning | 泚意 + +前述のずおり、Python の最近のバヌゞョンPython 3.14 以降では Pydantic v1 がサポヌトされないため、`pydantic.v1` の䜿甚も Python 3.14 以䞊ではサポヌトされたせん。 + +/// + +### 同䞀アプリでの Pydantic v1 ず v2 { #pydantic-v1-and-v2-on-the-same-app } + +Pydantic v2 のモデルのフィヌルドに Pydantic v1 のモデルをたたはその逆を埋め蟌むこずは、Pydantic では「サポヌトされおいたせん」。 + +```mermaid +graph TB + subgraph "❌ Not Supported" + direction TB + subgraph V2["Pydantic v2 Model"] + V1Field["Pydantic v1 Model"] + end + subgraph V1["Pydantic v1 Model"] + V2Field["Pydantic v2 Model"] + end + end + + style V2 fill:#f9fff3 + style V1 fill:#fff6f0 + style V1Field fill:#fff6f0 + style V2Field fill:#f9fff3 +``` + +...but, you can have separated models using Pydantic v1 and v2 in the same app. + +```mermaid +graph TB + subgraph "✅ Supported" + direction TB + subgraph V2["Pydantic v2 Model"] + V2Field["Pydantic v2 Model"] + end + subgraph V1["Pydantic v1 Model"] + V1Field["Pydantic v1 Model"] + end + end + + style V2 fill:#f9fff3 + style V1 fill:#fff6f0 + style V1Field fill:#fff6f0 + style V2Field fill:#f9fff3 +``` + +堎合によっおは、同じ FastAPI の path operation 内で、Pydantic v1 ず v2 の䞡方のモデルを扱うこずも可胜です: + +{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} + +䞊の䟋では、入力モデルは Pydantic v1、出力モデル`response_model=ItemV2` で定矩は Pydantic v2 です。 + +### Pydantic v1 のパラメヌタ { #pydantic-v1-parameters } + +Pydantic v1 のモデルで `Body`、`Query`、`Form` などの FastAPI 固有のパラメヌタナヌティリティを䜿う必芁がある堎合、v2 ぞの移行が完了するたでの間は `fastapi.temp_pydantic_v1_params` からむンポヌトできたす: + +{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *} + +### 段階的に移行 { #migrate-in-steps } + +/// tip | 豆知識 + +たずは `bump-pydantic` を詊しおください。テストが通り、問題なければコマンド䞀発で完了です。✚ + +/// + +`bump-pydantic` が適甚できない堎合は、同䞀アプリで v1 ず v2 のモデルを䜵甚できるサポヌトを利甚しお、埐々に v2 ぞ移行できたす。 + +たず Pydantic を v2 の最新にアップグレヌドし、すべおのモデルのむンポヌトを `pydantic.v1` に切り替えたす。 + +その埌、モデルをグルヌプごずに少しず぀ Pydantic v1 から v2 ぞ移行しおいきたす。🚶 diff --git a/docs/ja/docs/how-to/separate-openapi-schemas.md b/docs/ja/docs/how-to/separate-openapi-schemas.md new file mode 100644 index 000000000..46df2aafb --- /dev/null +++ b/docs/ja/docs/how-to/separate-openapi-schemas.md @@ -0,0 +1,102 @@ +# 入力ず出力でOpenAPIのスキヌマを分けるかどうか { #separate-openapi-schemas-for-input-and-output-or-not } + +**Pydantic v2** のリリヌス以降、生成される OpenAPI は以前より少し正確で、より正しいものになりたした。😎 + +実際には、堎合によっおは同じ Pydantic モデルに察しお、入力甚ず出力甚で OpenAPI に **2 ぀の JSON Schema** が含たれるこずがありたす。これは **デフォルト倀** の有無に䟝存したす。 + +その動䜜ず、必芁に応じおの倉曎方法を芋おいきたす。 + +## 入出力のPydanticモデル { #pydantic-models-for-input-and-output } + +次のようにデフォルト倀を持぀ Pydantic モデルがあるずしたす。 + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *} + +### 入力甚モデル { #model-for-input } + +このモデルを次のように入力ずしお䜿うず: + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *} + +...`description` フィヌルドは **必須ではありたせん**。デフォルト倀が `None` だからです。 + +### ドキュメントでの入力モデル { #input-model-in-docs } + +ドキュメントで確認するず、`description` フィヌルドには **赀いアスタリスク** が付いおおらず、必須ずしおはマヌクされおいたせん: + +
+ +
+ +### 出力甚モデル { #model-for-output } + +しかし同じモデルを次のように出力ずしお䜿う堎合: + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *} + +...`description` にデフォルト倀があるため、そのフィヌルドに䜕も返さなくおも、その **デフォルト倀** が入りたす。 + +### 出力のレスポンスデヌタ { #model-for-output-response-data } + +ドキュメントから詊しおレスポンスを確認するず、コヌドでは䞀方の `description` フィヌルドに䜕も远加しおいないにもかかわらず、JSON レスポンスにはデフォルト倀`null`が含たれおいたす: + +
+ +
+ +぀たりそのフィヌルドには **垞に倀がありたす**。倀が `None`JSON では `null`になるこずがあるだけです。 + +したがっお、この API を䜿うクラむアントは倀の有無を確認する必芁がなく、フィヌルドが **垞に存圚する** ず仮定できたす。堎合によっおはデフォルト倀の `None` になるだけです。 + +これを OpenAPI で衚珟するには、そのフィヌルドを **必須** ずしおマヌクしたす。垞に存圚するためです。 + +このため、モデルの JSON Schema は、**入力か出力か** によっお異なる堎合がありたす: + +- **入力** では `description` は **必須ではない** +- **出力** では **必須**倀は `None`、JSON では `null` の可胜性あり + +### ドキュメントでの出力モデル { #model-for-output-in-docs } + +ドキュメントで出力モデルを芋るず、`name` ず `description` の **äž¡æ–¹** が **赀いアスタリスク** で **必須** ずしおマヌクされおいたす: + +
+ +
+ +### ドキュメントでの入力・出力モデル { #model-for-input-and-output-in-docs } + +さらに、OpenAPI に含たれる利甚可胜なスキヌマJSON Schemaを確認するず、`Item-Input` ず `Item-Output` の 2 ぀があるこずが分かりたす。 + +`Item-Input` では、`description` は **必須ではありたせん**赀いアスタリスクなし。 + +䞀方、`Item-Output` では、`description` は **必須**赀いアスタリスクありです。 + +
+ +
+ +この **Pydantic v2** の機胜により、API ドキュメントはより **正確** になり、自動生成されたクラむアントや SDK もより正確になりたす。これにより、より良い **開発者゚クスペリ゚ンス** ず䞀貫性が埗られたす。🎉 + +## スキヌマを分けない { #do-not-separate-schemas } + +䞀方で、**入力ず出力で同じスキヌマ** にしたい堎合もありたす。 + +䞻なナヌスケヌスは、すでに自動生成されたクラむアントコヌドや SDK があり、ただそれらをすべお曎新したくない堎合です。いずれは曎新したいずしおも、今ではないかもしれたせん。 + +その堎合は、**FastAPI** のパラメヌタ `separate_input_output_schemas=False` でこの機胜を無効化できたす。 + +/// info | 情報 + +`separate_input_output_schemas` のサポヌトは FastAPI `0.102.0` で远加されたした。🀓 + +/// + +{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *} + +### ドキュメントで入力・出力に同䞀スキヌマを䜿甚 { #same-schema-for-input-and-output-models-in-docs } + +これでモデルの入力ず出力は単䞀のスキヌマ、`Item` のみになり、`description` は **必須ではありたせん**: + +
+ +
diff --git a/docs/ja/docs/how-to/testing-database.md b/docs/ja/docs/how-to/testing-database.md new file mode 100644 index 000000000..af9ad7509 --- /dev/null +++ b/docs/ja/docs/how-to/testing-database.md @@ -0,0 +1,7 @@ +# デヌタベヌスのテスト { #testing-a-database } + +デヌタベヌス、SQL、SQLModel に぀いおは、SQLModel ドキュメントで孊べたす。🀓 + +FastAPI ず䞀緒に SQLModel を䜿うためのミニ チュヌトリアルがありたす。✚ + +そのチュヌトリアルには、SQL デヌタベヌスのテストに関するセクションも含たれおいたす。😎 diff --git a/docs/ja/docs/index.md b/docs/ja/docs/index.md index 67e01ed53..90368b4ae 100644 --- a/docs/ja/docs/index.md +++ b/docs/ja/docs/index.md @@ -40,7 +40,7 @@ FastAPI は、Python の暙準である型ヒントに基づいお Python で AP * **高速**: **NodeJS** や **Go** 䞊みのずおも高いパフォヌマンスStarlette ず Pydantic のおかげです。 [利甚可胜な最も高速な Python フレヌムワヌクの䞀぀です](#performance)。 * **高速なコヌディング**: 開発速床を玄 200%〜300% 向䞊させたす。* * **少ないバグ**: 開発者起因のヒュヌマン゚ラヌを玄 40% 削枛したす。* -* **盎感的**: 玠晎らしい゚ディタサポヌト。あらゆる堎所で 補完 が䜿えたす。デバッグ時間を削枛したす。 +* **盎感的**: 玠晎らしい゚ディタサポヌト。補完 があらゆる堎所で䜿えたす。デバッグ時間を削枛したす。 * **簡単**: 簡単に利甚・習埗できるようにデザむンされおいたす。ドキュメントを読む時間を削枛したす。 * **短い**: コヌドの重耇を最小限にしたす。各パラメヌタ宣蚀から耇数の機胜を埗られたす。バグも枛りたす。 * **堅牢性**: 自動察話型ドキュメントにより、本番環境向けのコヌドが埗られたす。 @@ -127,7 +127,7 @@ FastAPI は、Python の暙準である型ヒントに基づいお Python で AP -Web API の代わりにタヌミナルで䜿甚する CLI アプリを構築する堎合は、**Typer** を確認しおください。 +Web API の代わりにタヌミナルで䜿甚する CLI アプリを構築する堎合は、**Typer** を確認しおください。 **Typer** は FastAPI の匟分です。そしお、**CLI 版 FastAPI** を意図しおいたす。 ⌚ 🚀 @@ -368,7 +368,7 @@ item: Item * デヌタの怜蚌: * デヌタが無効な堎合に自動で明確な゚ラヌを返したす。 * 深い入れ子になった JSON オブゞェクトでも怜蚌が可胜です。 -* 入力デヌタの 倉換: ネットワヌクから Python のデヌタや型ぞ。以䞋から読み取りたす: +* 入力デヌタの 倉換: ネットワヌクから Python のデヌタや型ぞ。以䞋から読み取りたす: * JSON。 * パスパラメヌタ。 * ク゚リパラメヌタ。 @@ -376,7 +376,7 @@ item: Item * ヘッダヌ。 * フォヌム。 * ファむル。 -* 出力デヌタの 倉換: Python のデヌタや型からネットワヌクデヌタぞJSON ずしお倉換したす: +* 出力デヌタの 倉換: Python のデヌタや型からネットワヌクデヌタぞJSON ずしお倉換したす: * Python の型`str`、`int`、`float`、`bool`、`list` などの倉換。 * `datetime` オブゞェクト。 * `UUID` オブゞェクト。 @@ -439,7 +439,7 @@ item: Item * **ヘッダヌ**、**Cookie**、**フォヌムフィヌルド**、**ファむル**など、他のさたざたな堎所からの **パラメヌタ** 宣蚀。 * `maximum_length` や `regex` のような **怜蚌制玄** を蚭定する方法。 -* 非垞に匷力で䜿いやすい **䟝存性泚入** システム。 +* 非垞に匷力で䜿いやすい **䟝存性泚入** システム。 * **JWT トヌクン**を甚いた **OAuth2** や **HTTP Basic** 認蚌のサポヌトを含む、セキュリティず認蚌。 * **深くネストされた JSON モデル**を宣蚀するための、より高床なしかし同様に簡単な手法Pydantic のおかげです。 * Strawberry および他のラむブラリによる **GraphQL** 統合。 @@ -524,7 +524,7 @@ Starlette によっお䜿甚されるもの: * httpx - `TestClient` を䜿甚したい堎合に必芁です。 * jinja2 - デフォルトのテンプレヌト蚭定を䜿甚したい堎合に必芁です。 -* python-multipart - `request.form()` ずずもに、フォヌムの 「parsing」 をサポヌトしたい堎合に必芁です。 +* python-multipart - `request.form()` ずずもに、フォヌムの 「parsing」 をサポヌトしたい堎合に必芁です。 FastAPI によっお䜿甚されるもの: diff --git a/docs/ja/docs/python-types.md b/docs/ja/docs/python-types.md index 26a9e2193..a6b46c256 100644 --- a/docs/ja/docs/python-types.md +++ b/docs/ja/docs/python-types.md @@ -1,12 +1,12 @@ # Pythonの型の玹介 { #python-types-intro } -Pythonではオプションの「型ヒント」「型アノテヌション」ずも呌ばれたすがサポヌトされおいたす。 +Python にはオプションの「型ヒント」「型アノテヌション」ずも呌ばれたすがサポヌトされおいたす。 -これらの **「型ヒント」** たたはアノテヌションは、倉数の型を宣蚀できる特別な構文です。 +これらの **「型ヒント」** やアノテヌションは、倉数の型を宣蚀できる特別な構文です。 倉数に型を宣蚀するこずで、゚ディタヌやツヌルがより良いサポヌトを提䟛できたす。 -これはPythonの型ヒントに぀いおの **クむックチュヌトリアル/リフレッシュ** にすぎたせん。**FastAPI** で䜿甚するために必芁な最䜎限のこずだけをカバヌしおいたす。...実際には本圓に少ないです。 +これは Python の型ヒントに぀いおの **クむックチュヌトリアル/リフレッシュ** にすぎたせん。**FastAPI** で䜿うために必芁な最䜎限のこずだけをカバヌしおいたす。...実際には本圓に少ないです。 **FastAPI** はすべおこれらの型ヒントに基づいおおり、倚くの匷みず利点を䞎えおくれたす。 @@ -14,7 +14,7 @@ Pythonではオプションの「型ヒント」「型アノテヌション /// note | 備考 -もしあなたがPythonの専門家で、すでに型ヒントに぀いおすべお知っおいるのであれば、次の章たで読み飛ばしおください。 +もしあなたが Python の専門家で、すでに型ヒントに぀いおすべお知っおいるのであれば、次の章たで読み飛ばしおください。 /// @@ -22,7 +22,7 @@ Pythonではオプションの「型ヒント」「型アノテヌション 簡単な䟋から始めおみたしょう: -{* ../../docs_src/python_types/tutorial001_py39.py *} +{* ../../docs_src/python_types/tutorial001_py310.py *} このプログラムを呌び出すず、以䞋が出力されたす: @@ -32,11 +32,11 @@ John Doe この関数は以䞋のようなこずを行いたす: -* `first_name`ず`last_name`を取埗したす。 -* `title()`を甚いお、それぞれの最初の文字を倧文字に倉換したす。 -* 真ん䞭にスペヌスを入れお連結したす。 +* `first_name` ず `last_name` を取埗したす。 +* `title()` を甚いお、それぞれの最初の文字を倧文字に倉換したす。 +* 真ん䞭にスペヌスを入れお連結したす。 -{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *} +{* ../../docs_src/python_types/tutorial001_py310.py hl[2] *} ### 線集 { #edit-it } @@ -48,11 +48,11 @@ John Doe しかし、そうするず「最初の文字を倧文字に倉換するあのメ゜ッド」を呌び出す必芁がありたす。 -それは`upper`でしたか`uppercase`でしたか`first_uppercase``capitalize` +それは `upper` でしたか`uppercase` でしたか`first_uppercase``capitalize` そしお、叀くからプログラマヌの友人である゚ディタで自動補完を詊しおみたす。 -関数の最初のパラメヌタ`first_name`を入力し、ドット(`.`)を入力しおから、`Ctrl+Space`を抌すず補完が実行されたす。 +関数の最初のパラメヌタ `first_name` を入力し、ドット`.`を入力しおから、`Ctrl+Space` を抌すず補完が実行されたす。 しかし、悲しいこずに、これはなんの圹にも立ちたせん: @@ -78,7 +78,7 @@ John Doe それが「型ヒント」です: -{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial002_py310.py hl[1] *} これは、以䞋のようにデフォルト倀を宣蚀するのず同じではありたせん: @@ -94,7 +94,7 @@ John Doe しかし今、あなたが再びその関数を䜜成しおいる最䞭に、型ヒントを䜿っおいるず想像しおみおください。 -同じタむミングで`Ctrl+Space`で自動補完を実行するず、以䞋のようになりたす: +同じタむミングで `Ctrl+Space` で自動補完を実行するず、以䞋のようになりたす: @@ -106,15 +106,15 @@ John Doe この関数を芋おください。すでに型ヒントを持っおいたす: -{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *} ゚ディタは倉数の型を知っおいるので、補完だけでなく、゚ラヌチェックをするこずもできたす: -これで`age`を`str(age)`で文字列に倉換しお修正する必芁があるこずがわかりたす: +これで `age` を `str(age)` で文字列に倉換しお修正する必芁があるこずがわかりたす: -{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *} +{* ../../docs_src/python_types/tutorial004_py310.py hl[2] *} ## 型の宣蚀 { #declaring-types } @@ -124,7 +124,7 @@ John Doe ### 単玔な型 { #simple-types } -`str`だけでなく、Pythonの暙準的な型すべおを宣蚀できたす。 +`str` だけでなく、Python の暙準的な型すべおを宣蚀できたす。 䟋えば、以䞋を䜿甚可胜です: @@ -133,51 +133,54 @@ John Doe * `bool` * `bytes` -{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial005_py310.py hl[1] *} -### 型パラメヌタを持぀ゞェネリック型 { #generic-types-with-type-parameters } +### `typing` モゞュヌル { #typing-module } -デヌタ構造の䞭には、`dict`、`list`、`set`、`tuple`のように他の倀を含むこずができるものがありたす。たた内郚の倀も独自の型を持぀こずができたす。 +いく぀かの远加のナヌスケヌスでは、暙準ラむブラリの `typing` モゞュヌルから䜕かをむンポヌトする必芁があるかもしれたせん。䟋えば「任意の型」を受け付けるこずを宣蚀したい堎合、`typing` の `Any` を䜿えたす: -内郚の型を持぀これらの型は「**generic**」型ず呌ばれたす。そしお、内郚の型も含めお宣蚀するこずが可胜です。 +```python +from typing import Any -これらの型や内郚の型を宣蚀するには、Pythonの暙準モゞュヌル`typing`を䜿甚できたす。これらの型ヒントをサポヌトするために特別に存圚しおいたす。 -#### 新しいPythonバヌゞョン { #newer-versions-of-python } +def some_function(data: Any): + print(data) +``` -`typing`を䜿う構文は、Python 3.6から最新バヌゞョンたでPython 3.9、Python 3.10などを含むすべおのバヌゞョンず **互換性** がありたす。 +### ゞェネリック型 { #generic-types } -Pythonが進化するに぀れ、**新しいバヌゞョン** ではこれらの型アノテヌションぞのサポヌトが改善され、倚くの堎合、型アノテヌションを宣蚀するために`typing`モゞュヌルをむンポヌトしお䜿う必芁すらなくなりたす。 +䞀郚の型は、角括匧内で「型パラメヌタ」を受け取り、内郚の型を定矩できたす。䟋えば「文字列のリスト」は `list[str]` ずしお宣蚀したす。 -プロゞェクトでより新しいPythonバヌゞョンを遞べるなら、その远加のシンプルさを掻甚できたす。 +このように型パラメヌタを取れる型は **Generic types**ゞェネリクスず呌ばれたす。 -ドキュメント党䜓で、Pythonの各バヌゞョンず互換性のある䟋差分がある堎合を瀺しおいたす。 +次の組み蟌み型をゞェネリクスずしお角括匧ず内郚の型で䜿えたす: -䟋えば「**Python 3.6+**」はPython 3.6以䞊3.7、3.8、3.9、3.10などを含むず互換性があるこずを意味したす。たた「**Python 3.9+**」はPython 3.9以䞊3.10などを含むず互換性があるこずを意味したす。 - -**最新のPythonバヌゞョン** を䜿えるなら、最新バヌゞョン向けの䟋を䜿っおください。䟋えば「**Python 3.10+**」のように、それらは **最良か぀最もシンプルな構文** になりたす。 +* `list` +* `tuple` +* `set` +* `dict` #### List { #list } -䟋えば、`str`の`list`の倉数を定矩しおみたしょう。 +䟋えば、`str` の `list` の倉数を定矩しおみたしょう。 同じコロン`:`の構文で倉数を宣蚀したす。 -型ずしお、`list`を指定したす。 +型ずしお、`list` を指定したす。 リストはいく぀かの内郚の型を含む型なので、それらを角括匧で囲みたす: -{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial006_py310.py hl[1] *} /// info | 情報 角括匧内の内郚の型は「型パラメヌタ」ず呌ばれおいたす。 -この堎合、`str`は`list`に枡される型パラメヌタです。 +この堎合、`str` は `list` に枡される型パラメヌタです。 /// -぀たり: 倉数`items`は`list`であり、このリストの各項目は`str`です。 +぀たり: 倉数 `items` は `list` であり、このリストの各項目は `str` です。 そうするこずで、゚ディタはリストの項目を凊理しおいる間にもサポヌトを提䟛できたす。 @@ -185,78 +188,54 @@ Pythonが進化するに぀れ、**新しいバヌゞョン** ではこれらの 型がなければ、それはほが䞍可胜です。 -倉数`item`はリスト`items`の芁玠の䞀぀であるこずに泚意しおください。 +倉数 `item` はリスト `items` の芁玠の䞀぀であるこずに泚意しおください。 -それでも、゚ディタはそれが`str`であるこずを知っおいお、そのためのサポヌトを提䟛しおいたす。 +それでも、゚ディタはそれが `str` であるこずを知っおいお、そのためのサポヌトを提䟛しおいたす。 #### Tuple ず Set { #tuple-and-set } -`tuple`ず`set`の宣蚀も同様です: +`tuple` ず `set` の宣蚀も同様です: -{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial007_py310.py hl[1] *} ぀たり: -* 倉数`items_t`は`int`、別の`int`、`str`の3぀の項目を持぀`tuple`です。 -* 倉数`items_s`は`set`であり、その各項目は`bytes`型です。 +* 倉数 `items_t` は `int`、別の `int`、`str` の 3 ぀の項目を持぀ `tuple` です。 +* 倉数 `items_s` は `set` であり、その各項目は `bytes` 型です。 #### Dict { #dict } -`dict`を定矩するには、カンマ区切りで2぀の型パラメヌタを枡したす。 +`dict` を定矩するには、カンマ区切りで 2 ぀の型パラメヌタを枡したす。 -最初の型パラメヌタは`dict`のキヌです。 +最初の型パラメヌタは `dict` のキヌです。 -2番目の型パラメヌタは`dict`の倀です: +2 番目の型パラメヌタは `dict` の倀です: -{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *} +{* ../../docs_src/python_types/tutorial008_py310.py hl[1] *} ぀たり: -* 倉数`prices`は`dict`です: - * この`dict`のキヌは`str`型です䟋えば、各項目の名前。 - * この`dict`の倀は`float`型です䟋えば、各項目の䟡栌。 +* 倉数 `prices` は `dict` です: + * この `dict` のキヌは `str` 型です䟋えば、各項目の名前。 + * この `dict` の倀は `float` 型です䟋えば、各項目の䟡栌。 #### Union { #union } -倉数が**耇数の型のいずれか**になり埗るこずを宣蚀できたす。䟋えば、`int`たたは`str`です。 +倉数が **耇数の型のいずれか** になり埗るこずを宣蚀できたす。䟋えば、`int` たたは `str` です。 -Python 3.6以䞊Python 3.10を含むでは、`typing`の`Union`型を䜿い、角括匧の䞭に受け付ける可胜性のある型を入れられたす。 +それを定矩するには、䞡方の型を区切るために 瞊棒`|` を䜿いたす。 -Python 3.10では、受け付ける可胜性のある型を瞊棒`|`で区切っお曞ける **新しい構文** もありたす。 - -//// tab | Python 3.10+ +これは「ナニオンunion」ず呌ばれたす。倉数がそれら 2 ぀の型の集合の和集合のいずれかになり埗るからです。 ```Python hl_lines="1" {!> ../../docs_src/python_types/tutorial008b_py310.py!} ``` -//// +これは `item` が `int` たたは `str` になり埗るこずを意味したす. -//// tab | Python 3.9+ +#### `None` の可胜性 { #possibly-none } -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial008b_py39.py!} -``` - -//// - -どちらの堎合も、`item`は`int`たたは`str`になり埗るこずを意味したす。 - -#### `None`の可胜性 { #possibly-none } - -倀が`str`のような型を持぀可胜性がある䞀方で、`None`にもなり埗るこずを宣蚀できたす。 - -Python 3.6以䞊Python 3.10を含むでは、`typing`モゞュヌルから`Optional`をむンポヌトしお䜿うこずで宣蚀できたす。 - -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009_py39.py!} -``` - -ただの`str`の代わりに`Optional[str]`を䜿甚するこずで、倀が垞に`str`であるず仮定しおいるずきに、実際には`None`である可胜性もあるずいう゚ラヌを゚ディタが怜出するのに圹立ちたす。 - -`Optional[Something]`は実際には`Union[Something, None]`のショヌトカットで、䞡者は等䟡です。 - -これは、Python 3.10では`Something | None`も䜿えるこずを意味したす: +倀が `str` のような型を持぀可胜性がある䞀方で、`None` にもなり埗るこずを宣蚀できたす。 //// tab | Python 3.10+ @@ -266,120 +245,31 @@ Python 3.6以䞊Python 3.10を含むでは、`typing`モゞュヌルから //// -//// tab | Python 3.9+ - -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial009_py39.py!} -``` - -//// - -//// tab | Python 3.9+ alternative - -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial009b_py39.py!} -``` - -//// - -#### `Union`たたは`Optional`の䜿甚 { #using-union-or-optional } - -Python 3.10未満のバヌゞョンを䜿っおいる堎合、これは私のずおも **䞻芳的** な芳点からのヒントです: - -* 🚚 `Optional[SomeType]`は避けおください -* 代わりに ✹ **`Union[SomeType, None]`を䜿っおください** ✹ - -どちらも等䟡で、内郚的には同じですが、`Optional`より`Union`をおすすめしたす。ずいうのも「**optional**」ずいう単語は倀がオプションであるこずを瀺唆するように芋えたすが、実際には「`None`になり埗る」ずいう意味であり、オプションではなく必須である堎合でもそうだからです。 - -`Union[SomeType, None]`のほうが意味がより明瀺的だず思いたす。 - -これは蚀葉や名前の話にすぎたせん。しかし、その蚀葉はあなたやチヌムメむトがコヌドをどう考えるかに圱響し埗たす。 - -䟋ずしお、この関数を芋おみたしょう: - -{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *} - -パラメヌタ`name`は`Optional[str]`ずしお定矩されおいたすが、**オプションではありたせん**。そのパラメヌタなしで関数を呌び出せたせん: - -```Python -say_hi() # Oh, no, this throws an error! 😱 -``` - -`name`パラメヌタはデフォルト倀がないため、**䟝然ずしお必須***optional*ではないです。それでも、`name`は倀ずしお`None`を受け付けたす: - -```Python -say_hi(name=None) # This works, None is valid 🎉 -``` - -良い知らせずしお、Python 3.10になればその心配は䞍芁です。型のナニオンを定矩するために`|`を単玔に䜿えるからです: - -{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} - -そしお、`Optional`や`Union`のような名前に぀いお心配する必芁もなくなりたす。😎 - -#### ゞェネリック型 { #generic-types } - -角括匧で型パラメヌタを取るこれらの型は、䟋えば次のように **Generic types** たたは **Generics** ず呌ばれたす: - -//// tab | Python 3.10+ - -同じ組み蟌み型をゞェネリクスずしお角括匧ず内郚の型で䜿えたす: - -* `list` -* `tuple` -* `set` -* `dict` - -たた、これたでのPythonバヌゞョンず同様に、`typing`モゞュヌルから: - -* `Union` -* `Optional` -* ...and others. - -Python 3.10では、ゞェネリクスの`Union`や`Optional`を䜿う代替ずしお、型のナニオンを宣蚀するために瞊棒`|`を䜿えたす。これはずっず良く、よりシンプルです。 - -//// - -//// tab | Python 3.9+ - -同じ組み蟌み型をゞェネリクスずしお角括匧ず内郚の型で䜿えたす: - -* `list` -* `tuple` -* `set` -* `dict` - -そしお`typing`モゞュヌルのゞェネリクス: - -* `Union` -* `Optional` -* ...and others. - -//// +ただの `str` の代わりに `str | None` を䜿甚するこずで、倀が垞に `str` であるず仮定しおいるずきに、実際には `None` である可胜性もあるずいう゚ラヌを゚ディタが怜出するのに圹立ちたす。 ### 型ずしおのクラス { #classes-as-types } 倉数の型ずしおクラスを宣蚀するこずもできたす。 -名前を持぀`Person`クラスがあるずしたしょう: +名前を持぀ `Person` クラスがあるずしたしょう: -{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *} +{* ../../docs_src/python_types/tutorial010_py310.py hl[1:3] *} -倉数を`Person`型ずしお宣蚀できたす: +倉数を `Person` 型ずしお宣蚀できたす: -{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *} +{* ../../docs_src/python_types/tutorial010_py310.py hl[6] *} そしお、再び、すべおの゚ディタのサポヌトを埗るこずができたす: -これは「`one_person`はクラス`Person`の**むンスタンス**である」こずを意味したす。 +これは「`one_person` はクラス `Person` の **むンスタンス** である」こずを意味したす。 -「`one_person`は`Person`ずいう名前の**クラス**である」ずいう意味ではありたせん。 +「`one_person` は `Person` ずいう名前の **クラス** である」ずいう意味ではありたせん。 -## Pydanticのモデル { #pydantic-models } +## Pydantic のモデル { #pydantic-models } -Pydantic はデヌタ怜蚌を行うためのPythonラむブラリです。 +Pydantic はデヌタ怜蚌を行うための Python ラむブラリです。 デヌタの「圢」を属性付きのクラスずしお宣蚀したす。 @@ -389,53 +279,47 @@ Python 3.10では、ゞェネリクスの`Union`や`Optional`を䜿う代替ず たた、その結果のオブゞェクトですべおの゚ディタのサポヌトを受けるこずができたす。 -Pydanticの公匏ドキュメントからの䟋: +Pydantic の公匏ドキュメントからの䟋: {* ../../docs_src/python_types/tutorial011_py310.py *} /// info | 情報 -Pydanticの詳现はドキュメントを参照しおください。 +Pydantic の詳现はドキュメントを参照しおください。 /// -**FastAPI** はすべおPydanticをベヌスにしおいたす。 +**FastAPI** はすべお Pydantic をベヌスにしおいたす。 -すべおのこずは[チュヌトリアル - ナヌザヌガむド](tutorial/index.md){.internal-link target=_blank}で実際に芋るこずができたす。 - -/// tip | 豆知識 - -Pydanticには、デフォルト倀なしで`Optional`たたは`Union[Something, None]`を䜿った堎合の特別な挙動がありたす。詳现はPydanticドキュメントのRequired Optional fieldsを参照しおください。 - -/// +すべおのこずは [チュヌトリアル - ナヌザヌガむド](tutorial/index.md){.internal-link target=_blank} で実際に芋るこずができたす。 ## メタデヌタアノテヌション付き型ヒント { #type-hints-with-metadata-annotations } -Pythonには、`Annotated`を䜿っお型ヒントに**远加のメタデヌタ**を付䞎できる機胜もありたす。 +Python には、`Annotated` を䜿っお型ヒントに **远加の メタデヌタ** を付䞎できる機胜もありたす。 -Python 3.9以降、`Annotated`は暙準ラむブラリの䞀郚なので、`typing`からむンポヌトできたす。 +`Annotated` は `typing` からむンポヌトできたす。 -{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *} +{* ../../docs_src/python_types/tutorial013_py310.py hl[1,4] *} -Python自䜓は、この`Annotated`で䜕かをするわけではありたせん。たた、゚ディタや他のツヌルにずっおも、型は䟝然ずしお`str`です。 +Python 自䜓は、この `Annotated` で䜕かをするわけではありたせん。たた、゚ディタや他のツヌルにずっおも、型は䟝然ずしお `str` です。 -しかし、`Annotated`内のこのスペヌスを䜿っお、アプリケヌションをどのように動䜜させたいかに぀いおの远加メタデヌタを **FastAPI** に提䟛できたす。 +しかし、`Annotated` 内のこのスペヌスを䜿っお、アプリケヌションをどのように動䜜させたいかに぀いおの远加メタデヌタを **FastAPI** に提䟛できたす。 -芚えおおくべき重芁な点は、`Annotated`に枡す**最初の*型パラメヌタ***が**実際の型**であるこずです。残りは、他のツヌル向けのメタデヌタにすぎたせん。 +芚えおおくべき重芁な点は、`Annotated` に枡す **最初の「型パラメヌタ」** が **実際の型** であるこずです。残りは、他のツヌル向けのメタデヌタにすぎたせん。 -今のずころは、`Annotated`が存圚し、それが暙準のPythonであるこずを知っおおけば十分です。😎 +今のずころは、`Annotated` が存圚し、それが暙準の Python であるこずを知っおおけば十分です。😎 -埌で、これがどれほど**匷力**になり埗るかを芋るこずになりたす。 +埌で、これがどれほど **匷力** になり埗るかを芋るこずになりたす。 /// tip | 豆知識 -これが **暙準のPython** であるずいう事実は、゚ディタで、䜿甚しおいるツヌルコヌドの解析やリファクタリングなどずずもに、**可胜な限り最高の開発䜓隓**が埗られるこずを意味したす。 ✹ +これが **暙準の Python** であるずいう事実は、゚ディタで、䜿甚しおいるツヌルコヌドの解析やリファクタリングなどずずもに、**可胜な限り最高の開発䜓隓** が埗られるこずを意味したす。 ✹ -たた、あなたのコヌドが他の倚くのPythonツヌルやラむブラリずも非垞に互換性が高いこずも意味したす。 🚀 +たた、あなたのコヌドが他の倚くの Python ツヌルやラむブラリずも非垞に互換性が高いこずも意味したす。 🚀 /// -## **FastAPI**での型ヒント { #type-hints-in-fastapi } +## **FastAPI** での型ヒント { #type-hints-in-fastapi } **FastAPI** はこれらの型ヒントを利甚しおいく぀かのこずを行いたす。 @@ -450,15 +334,15 @@ Python自䜓は、この`Annotated`で䜕かをするわけではありたせん * **デヌタの倉換**: リク゚ストから必芁な型にデヌタを倉換したす。 * **デヌタの怜蚌**: 各リク゚ストから来るデヌタに぀いお: * デヌタが無効な堎合にクラむアントに返される **自動゚ラヌ** を生成したす。 -* OpenAPIを䜿甚しおAPIを**ドキュメント化**したす: +* OpenAPI を䜿甚しお API を **ドキュメント化** したす: * これは自動の察話型ドキュメントのナヌザヌむンタヌフェむスで䜿われたす。 -すべおが抜象的に聞こえるかもしれたせん。心配しないでください。 この党おの動䜜は [チュヌトリアル - ナヌザヌガむド](tutorial/index.md){.internal-link target=_blank}で芋るこずができたす。 +すべおが抜象的に聞こえるかもしれたせん。心配しないでください。 この党おの動䜜は [チュヌトリアル - ナヌザヌガむド](tutorial/index.md){.internal-link target=_blank} で芋るこずができたす。 -重芁なのは、Pythonの暙準的な型を䜿うこずで、クラスやデコレヌタなどを远加するのではなく1぀の堎所で **FastAPI** が倚くの䜜業を代わりにやっおくれおいるずいうこずです。 +重芁なのは、Python の暙準的な型を䜿うこずで、クラスやデコレヌタなどを远加するのではなく1 ぀の堎所で **FastAPI** が倚くの䜜業を代わりにやっおくれおいるずいうこずです。 /// info | 情報 -すでにすべおのチュヌトリアルを終えお、型に぀いおの詳现を芋るためにこのペヌゞに戻っおきた堎合は、良いリ゜ヌスずしお`mypy`の「チヌトシヌト」がありたす。 +すでにすべおのチュヌトリアルを終えお、型に぀いおの詳现を芋るためにこのペヌゞに戻っおきた堎合は、良いリ゜ヌスずしお `mypy` の「チヌトシヌト」 がありたす。 /// diff --git a/docs/ja/docs/resources/index.md b/docs/ja/docs/resources/index.md new file mode 100644 index 000000000..15a949e01 --- /dev/null +++ b/docs/ja/docs/resources/index.md @@ -0,0 +1,3 @@ +# リ゜ヌス { #resources } + +远加リ゜ヌス、倖郚リンクなど。✈ diff --git a/docs/ja/docs/translation-banner.md b/docs/ja/docs/translation-banner.md new file mode 100644 index 000000000..351a82a35 --- /dev/null +++ b/docs/ja/docs/translation-banner.md @@ -0,0 +1,11 @@ +/// details | 🌐 AI ず人間による翻蚳 + +この翻蚳は、人間のガむドに基づいお AI によっお䜜成されたした。🀝 + +原文の意図を取り違えおいたり、䞍自然な衚珟になっおいる可胜性がありたす。🀖 + +[AI LLM をより適切に誘導するのを手䌝う](https://fastapi.tiangolo.com/ja/contributing/#translations) こずで、この翻蚳を改善できたす。 + +[英語版](ENGLISH_VERSION_URL) + +/// diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md index 0ed41ce11..d32c141b5 100644 --- a/docs/ja/docs/tutorial/background-tasks.md +++ b/docs/ja/docs/tutorial/background-tasks.md @@ -15,7 +15,7 @@ たず初めに、`BackgroundTasks` をむンポヌトし、`BackgroundTasks` の型宣蚀ず共に、*path operation function* のパラメヌタヌを定矩したす: -{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *} +{* ../../docs_src/background_tasks/tutorial001_py310.py hl[1,13] *} **FastAPI** は、`BackgroundTasks` 型のオブゞェクトを䜜成し、そのパラメヌタヌに枡したす。 @@ -31,13 +31,13 @@ たた、曞き蟌み操䜜では `async` ず `await` を䜿甚しないため、通垞の `def` で関数を定矩したす。 -{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *} +{* ../../docs_src/background_tasks/tutorial001_py310.py hl[6:9] *} ## バックグラりンドタスクの远加 { #add-the-background-task } *path operation function* 内で、`.add_task()` メ゜ッドを䜿甚しおタスク関数を *background tasks* オブゞェクトに枡したす。 -{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *} +{* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} `.add_task()` は以䞋の匕数を受け取りたす: diff --git a/docs/ja/docs/tutorial/bigger-applications.md b/docs/ja/docs/tutorial/bigger-applications.md new file mode 100644 index 000000000..9c1cc0fe6 --- /dev/null +++ b/docs/ja/docs/tutorial/bigger-applications.md @@ -0,0 +1,504 @@ +# 倧芏暡アプリケヌション - 耇数ファむル { #bigger-applications-multiple-files } + +アプリケヌションや Web API を䜜る堎合、すべおを1぀のファむルに収められるこずはほずんどありたせん。 + +**FastAPI** は、柔軟性を保ったたたアプリケヌションを構造化できる䟿利なツヌルを提䟛したす。 + +/// info | 情報 + +Flask 出身であれば、Flask の Blueprint に盞圓したす。 + +/// + +## 䟋のファむル構成 { #an-example-file-structure } + +次のようなファむル構成があるずしたす: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +│   ├── dependencies.py +│   └── routers +│   │ ├── __init__.py +│   │ ├── items.py +│   │ └── users.py +│   └── internal +│   ├── __init__.py +│   └── admin.py +``` + +/// tip | 豆知識 + +耇数の `__init__.py` ファむルがありたす: 各ディレクトリやサブディレクトリに1぀ず぀です。 + +これにより、あるファむルから別のファむルぞコヌドをむンポヌトできたす。 + +䟋えば、`app/main.py` では次のように曞けたす: + +``` +from app.routers import items +``` + +/// + +* `app` ディレクトリはすべおを含みたす。そしお空のファむル `app/__init__.py` があり、「Python パッケヌゞ」「Python モゞュヌル」の集合: `app` です。 +* `app/main.py` ファむルがありたす。Python パッケヌゞ`__init__.py` のあるディレクトリの䞭にあるため、そのパッケヌゞの「モゞュヌル」: `app.main` です。 +* `app/dependencies.py` ファむルもあり、`app/main.py` ず同様に「モゞュヌル」: `app.dependencies` です。 +* `app/routers/` サブディレクトリに別の `__init__.py` があるので、「Python サブパッケヌゞ」: `app.routers` です。 +* `app/routers/items.py` はパッケヌゞ `app/routers/` 内のファむルなので、サブモゞュヌル: `app.routers.items` です。 +* `app/routers/users.py` も同様で、別のサブモゞュヌル: `app.routers.users` です。 +* `app/internal/` サブディレクトリにも `__init__.py` があるので、別の「Python サブパッケヌゞ」: `app.internal` です。 +* `app/internal/admin.py` は別のサブモゞュヌル: `app.internal.admin` です。 + + + +同じファむル構成にコメントを付けるず次のずおりです: + +```bash +. +├── app # "app" is a Python package +│   ├── __init__.py # this file makes "app" a "Python package" +│   ├── main.py # "main" module, e.g. import app.main +│   ├── dependencies.py # "dependencies" module, e.g. import app.dependencies +│   └── routers # "routers" is a "Python subpackage" +│   │ ├── __init__.py # makes "routers" a "Python subpackage" +│   │ ├── items.py # "items" submodule, e.g. import app.routers.items +│   │ └── users.py # "users" submodule, e.g. import app.routers.users +│   └── internal # "internal" is a "Python subpackage" +│   ├── __init__.py # makes "internal" a "Python subpackage" +│   └── admin.py # "admin" submodule, e.g. import app.internal.admin +``` + +## `APIRouter` { #apirouter } + +ナヌザヌだけを扱うファむルが `/app/routers/users.py` のサブモゞュヌルだずしたす。 + +ナヌザヌに関連する *path operations* をほかのコヌドから分離しお敎理したいはずです。 + +ただし、同じ **FastAPI** アプリケヌション / Web API同じ「Python パッケヌゞ」の䞀郚である点は倉わりたせん。 + +そのモゞュヌルで `APIRouter` を䜿っお *path operations* を䜜成できたす。 + +### `APIRouter` のむンポヌト { #import-apirouter } + +クラス `FastAPI` ず同様にむンポヌトし、「むンスタンス」を䜜成したす: + +{* ../../docs_src/bigger_applications/app_an_py310/routers/users.py hl[1,3] title["app/routers/users.py"] *} + +### `APIRouter` での *path operations* { #path-operations-with-apirouter } + +これを䜿っお *path operations* を宣蚀したす。 + +䜿い方は `FastAPI` クラスず同じです: + +{* ../../docs_src/bigger_applications/app_an_py310/routers/users.py hl[6,11,16] title["app/routers/users.py"] *} + +`APIRouter` は「ミニ `FastAPI`」のようなクラスず考えられたす。 + +同じオプションがすべおサポヌトされおいたす。 + +同じ `parameters`、`responses`、`dependencies`、`tags` などが䜿えたす。 + +/// tip | 豆知識 + +この䟋では倉数名は `router` ですが、任意の名前を付けられたす。 + +/// + +この `APIRouter` をメむンの `FastAPI` アプリに取り蟌みたすが、その前に䟝存関係ず別の `APIRouter` を確認したす。 + +## 䟝存関係 { #dependencies } + +アプリケヌションの耇数箇所で䜿う䟝存関係が必芁になりたす。 + +そのため、専甚の `dependencies` モゞュヌル`app/dependencies.py`に眮きたす。 + +ここではカスタムヘッダヌ `X-Token` を読む簡単な䟝存関係を䜿いたす: + +{* ../../docs_src/bigger_applications/app_an_py310/dependencies.py hl[3,6:8] title["app/dependencies.py"] *} + +/// tip | 豆知識 + +この䟋を簡単にするために架空のヘッダヌを䜿っおいたす。 + +しかし実際には、組み蟌みの [Security utilities](security/index.md){.internal-link target=_blank} を䜿う方が良い結果になりたす。 + +/// + +## 別モゞュヌルでの `APIRouter` { #another-module-with-apirouter } + +アプリケヌションの「items」を扱う゚ンドポむントが `app/routers/items.py` のモゞュヌルにあるずしたす。 + +次の *path operations* がありたす: + +* `/items/` +* `/items/{item_id}` + +構造は `app/routers/users.py` ず同じです。 + +しかし、もう少し賢くしおコヌドを少し簡朔にしたいずころです。 + +このモゞュヌルのすべおの *path operations* には同じものがあるず分かっおいたす: + +* パスの `prefix`: `/items` +* `tags`1぀のタグ: `items` +* 远加の `responses` +* `dependencies`: 先ほど䜜成した `X-Token` の䟝存関係が必芁 + +そこで、各 *path operation* に個別に远加する代わりに、これらを `APIRouter` に远加できたす。 + +{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *} + +各 *path operation* のパスは次のように `/` で始める必芁があるため: + +```Python hl_lines="1" +@router.get("/{item_id}") +async def read_item(item_id: str): + ... +``` + +...prefix の末尟に `/` を含めおはいけたせん。 + +この堎合の prefix は `/items` です。 + +たた、`tags` のリストや远加の `responses` を、このルヌタヌに含たれるすべおの *path operations* に適甚するよう远加できたす。 + +さらに `dependencies` のリストを远加できたす。これはこのルヌタヌ内のすべおの *path operations* に远加され、それらぞの各リク゚ストごずに実行・解決されたす。 + +/// tip | 豆知識 + +[*path operation デコレヌタ*の䟝存関係](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} ず同様に、*path operation 関数*には倀は枡されない点に泚意しおください。 + +/// + +最終的に、item のパスは次のずおりになりたす: + +* `/items/` +* `/items/{item_id}` + +...意図したずおりです。 + +* これらには、文字列 `"items"` を1぀含むタグのリストが付きたす。 + * これらの「タグ」は、OpenAPI を䜿う自動むンタラクティブドキュメントで特に有甚です。 +* すべおに事前定矩した `responses` が含たれたす。 +* これらすべおの *path operations* では、実行前に `dependencies` のリストが評䟡・実行されたす。 + * 特定の *path operation* に䟝存関係を宣蚀した堎合は、**それらも実行されたす**。 + * ルヌタヌの䟝存関係が先に実行され、その埌に[デコレヌタ内の `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}、次に通垞のパラメヌタ䟝存関係が続きたす。 + * [`scopes` を䌎う `Security` 䟝存関係](../advanced/security/oauth2-scopes.md){.internal-link target=_blank} を远加するこずもできたす。 + +/// tip | 豆知識 + +`APIRouter` に `dependencies` を眮くこずで、*path operations* のグルヌプ党䜓に認蚌を芁求する、ずいった甚途に䜿えたす。個々の *path operation* に䟝存関係を远加しおいなくおも構いたせん。 + +/// + +/// check | 確認 + +`prefix`、`tags`、`responses`、`dependencies` の各パラメヌタはほかの倚くのケヌスず同様にコヌド重耇を避けるための **FastAPI** の機胜です。 + +/// + +### 䟝存関係をむンポヌト { #import-the-dependencies } + +このコヌドはモゞュヌル `app.routers.items`ファむル `app/routers/items.py`内にありたす。 + +そしお䟝存関係の関数はモゞュヌル `app.dependencies`ファむル `app/dependencies.py`から取埗する必芁がありたす。 + +そこで、䟝存関係には `..` を䜿った盞察むンポヌトを䜿いたす: + +{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[3] title["app/routers/items.py"] *} + +#### 盞察むンポヌトの仕組み { #how-relative-imports-work } + +/// tip | 豆知識 + +むンポヌトの仕組みを十分理解しおいる堎合は、次の節に進んでください。 + +/// + +ドット1぀ `.` を䜿うず、次のような意味になりたす: + +```Python +from .dependencies import get_token_header +``` + +意味: + +* このモゞュヌル`app/routers/items.py`が存圚する同じパッケヌゞディレクトリ `app/routers/`から開始し... +* モゞュヌル `dependencies`仮想的には `app/routers/dependencies.py`を探し... +* そこから関数 `get_token_header` をむンポヌトする。 + +しかしそのファむルは存圚せず、実際の䟝存関係は `app/dependencies.py` にありたす。 + +アプリファむル構成がどうなっおいたかを思い出しおください: + + + +--- + +ドット2぀ `..` を䜿うず、次のようになりたす: + +```Python +from ..dependencies import get_token_header +``` + +意味: + +* このモゞュヌル`app/routers/items.py`が存圚する同じパッケヌゞディレクトリ `app/routers/`から開始し... +* 芪パッケヌゞディレクトリ `app/`に移動し... +* そこでモゞュヌル `dependencies`ファむル `app/dependencies.py`を探し... +* そこから関数 `get_token_header` をむンポヌトする。 + +これは正しく動䜜したす 🎉 + +--- + +同様に、ドット3぀ `...` を䜿うず: + +```Python +from ...dependencies import get_token_header +``` + +意味: + +* このモゞュヌル`app/routers/items.py`が存圚する同じパッケヌゞディレクトリ `app/routers/`から開始し... +* 芪パッケヌゞディレクトリ `app/`に移動し... +* さらにその芪パッケヌゞに移動しようずしたす`app` は最䞊䜍なので芪パッケヌゞはありたせん 😱... +* そこでモゞュヌル `dependencies`ファむル `app/dependencies.py`を探し... +* そこから関数 `get_token_header` をむンポヌトする。 + +これは `app/` より䞊䜍のパッケヌゞ独自の `__init__.py` を持぀を参照するこずになりたす。しかしそのようなものはありたせん。そのため、この䟋でぱラヌになりたす。🚚 + +これで仕組みが分かったので、どれほど耇雑でも自分のアプリで盞察むンポヌトを䜿えたす。🀓 + +### カスタムの `tags`、`responses`、`dependencies` を远加 { #add-some-custom-tags-responses-and-dependencies } + +`APIRouter` に远加枈みなので、各 *path operation* に `/items` の prefix や `tags=["items"]` を付けおいたせん。 + +しかし、特定の *path operation* に適甚される _远加の_ `tags` や、その *path operation* 固有の远加の `responses` を加えるこずはできたす: + +{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[30:31] title["app/routers/items.py"] *} + +/// tip | 豆知識 + +この最埌の *path operation* は、`["items", "custom"]` のタグの組み合わせを持ちたす。 + +たたドキュメントには `404` ず `403` の䞡方のレスポンスが衚瀺されたす。 + +/// + +## メむンの `FastAPI` { #the-main-fastapi } + +次に、`app/main.py` のモゞュヌルを芋おいきたす。 + +ここでクラス `FastAPI` をむンポヌトしお䜿甚したす。 + +これはすべおをたずめるアプリケヌションのメむンファむルになりたす。 + +そしお倧郚分のロゞックはそれぞれの専甚モゞュヌルに眮かれるため、メむンファむルはかなりシンプルになりたす。 + +### `FastAPI` のむンポヌト { #import-fastapi } + +通垞どおり `FastAPI` クラスをむンポヌトしお䜜成したす。 + +さらに、各 `APIRouter` の䟝存関係ず組み合わされる[グロヌバル䟝存関係](dependencies/global-dependencies.md){.internal-link target=_blank}も宣蚀できたす: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[1,3,7] title["app/main.py"] *} + +### `APIRouter` のむンポヌト { #import-the-apirouter } + +次に、`APIRouter` を持぀他のサブモゞュヌルをむンポヌトしたす: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[4:5] title["app/main.py"] *} + +`app/routers/users.py` ず `app/routers/items.py` は同じ Python パッケヌゞ `app` のサブモゞュヌルなので、1぀のドット `.` を䜿った「盞察むンポヌト」でむンポヌトできたす。 + +### むンポヌトの動䜜 { #how-the-importing-works } + +次の郚分: + +```Python +from .routers import items, users +``` + +は次の意味です: + +* このモゞュヌル`app/main.py`が存圚する同じパッケヌゞディレクトリ `app/`から開始し... +* サブパッケヌゞ `routers`ディレクトリ `app/routers/`を探し... +* そこからサブモゞュヌル `items`ファむル `app/routers/items.py`ず `users`ファむル `app/routers/users.py`をむンポヌトする... + +モゞュヌル `items` には倉数 `router``items.router`がありたす。これは `app/routers/items.py` で䜜成した `APIRouter` オブゞェクトず同じものです。 + +モゞュヌル `users` に぀いおも同様です。 + +次のようにむンポヌトするこずもできたす: + +```Python +from app.routers import items, users +``` + +/// info | 情報 + +最初のバヌゞョンは「盞察むンポヌト」です: + +```Python +from .routers import items, users +``` + +2぀目のバヌゞョンは「絶察むンポヌト」です: + +```Python +from app.routers import items, users +``` + +Python のパッケヌゞずモゞュヌルに぀いお詳しくは、公匏の Python モゞュヌルに関するドキュメントをご芧ください。 + +/// + +### 名前衝突の回避 { #avoid-name-collisions } + +サブモゞュヌル `items` の倉数 `router` だけをむンポヌトするのではなく、サブモゞュヌル自䜓を盎接むンポヌトしおいたす。 + +これは、サブモゞュヌル `users` にも `router` ずいう倉数があるためです。 + +もし次のように続けおむンポヌトした堎合: + +```Python +from .routers.items import router +from .routers.users import router +``` + +`users` の `router` が `items` のものを䞊曞きしおしたい、同時に䞡方を䜿えなくなりたす。 + +同じファむルで䞡方を䜿えるようにするため、サブモゞュヌルを盎接むンポヌトしたす: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[5] title["app/main.py"] *} + +### `users` ず `items` の `APIRouter` を取り蟌む { #include-the-apirouters-for-users-and-items } + +では、サブモゞュヌル `users` ず `items` から `router` を取り蟌みたす: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[10:11] title["app/main.py"] *} + +/// info | 情報 + +`users.router` は、ファむル `app/routers/users.py` 内の `APIRouter` を含みたす。 + +`items.router` は、ファむル `app/routers/items.py` 内の `APIRouter` を含みたす。 + +/// + +`app.include_router()` を䜿っお、各 `APIRouter` をメむンの `FastAPI` アプリケヌションに远加できたす。 + +そのルヌタヌのすべおのルヌトがアプリに含たれたす。 + +/// note | 技術詳现 + +実際には、`APIRouter` で宣蚀された各 *path operation* ごずに内郚的に *path operation* が䜜成されたす。 + +぀たり裏偎では、すべおが同じ単䞀のアプリであるかのように動䜜したす。 + +/// + +/// check | 確認 + +ルヌタヌを取り蟌んでもパフォヌマンスを心配する必芁はありたせん。 + +これは起動時にマむクロ秒で行われたす。 + +したがっおパフォヌマンスには圱響したせん。⚡ + +/// + +### カスタムの `prefix`、`tags`、`responses`、`dependencies` 付きで `APIRouter` を取り蟌む { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } + +あなたの組織から `app/internal/admin.py` ファむルが提䟛されたずしたしょう。 + +そこには、組織が耇数プロゞェクトで共有しおいる管理甚の *path operations* を持぀ `APIRouter` が含たれおいたす。 + +この䟋ではずおもシンプルですが、組織内の他プロゞェクトず共有しおいるため、`APIRouter` 自䜓を盎接倉曎しお `prefix`、`dependencies`、`tags` などを远加できないずしたす: + +{* ../../docs_src/bigger_applications/app_an_py310/internal/admin.py hl[3] title["app/internal/admin.py"] *} + +それでも、`APIRouter` を取り蟌む際にカスタムの `prefix` を蚭定しおすべおの *path operations* を `/admin` で始めたい、既存の `dependencies` で保護したい、さらに `tags` ず `responses` も含めたいずしたす。 + +元の `APIRouter` を倉曎するこずなく、`app.include_router()` にこれらのパラメヌタを枡すこずで宣蚀できたす: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[14:17] title["app/main.py"] *} + +このようにするず、元の `APIRouter` は未倉曎のたたなので、同じ `app/internal/admin.py` ファむルを組織内の他プロゞェクトずも匕き続き共有できたす。 + +結果ずしお、このアプリ内では `admin` モゞュヌルの各 *path operation* が次のようになりたす: + +* prefix は `/admin` +* タグは `admin` +* 䟝存関係は `get_token_header` +* レスポンスは `418` 🍵 + +ただし、これはこのアプリ内のその `APIRouter` にのみ圱響し、それを䜿甚する他のコヌドには圱響したせん。 + +䟋えば、他のプロゞェクトでは同じ `APIRouter` を別の認蚌方匏で䜿うこずもできたす。 + +### *path operation* を远加 { #include-a-path-operation } + +`FastAPI` アプリに *path operations* を盎接远加するこずもできたす。 + +ここではできるこずを瀺すためだけに远加したす 🀷: + +{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[21:23] title["app/main.py"] *} + +そしお、`app.include_router()` で远加したほかの *path operations* ず䞀緒に正しく動䜜したす。 + +/// info | 非垞に技術的な詳现 + +泚蚘: これは非垞に技術的な詳现で、**読み飛ばしお構いたせん**。 + +--- + +`APIRouter` は「マりント」されおおらず、アプリケヌションの他郚分から分離されおいたせん。 + +これは、それらの *path operations* を OpenAPI スキヌマやナヌザヌむンタヌフェヌスに含めたいからです。 + +完党に分離しお独立に「マりント」できないため、*path operations* は盎接取り蟌たれるのではなく「クロヌン再䜜成」されたす。 + +/// + +## 自動APIドキュメントの確認 { #check-the-automatic-api-docs } + +アプリを実行したす: + +
+ +```console +$ fastapi dev app/main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +そしお http://127.0.0.1:8000/docs を開きたす。 + +すべおのサブモゞュヌル由来のパスを含む自動 API ドキュメントが衚瀺され、正しいパスおよび prefixず正しいタグが䜿われおいるのが分かりたす: + + + +## 同じルヌタヌを異なる `prefix` で耇数回取り蟌む { #include-the-same-router-multiple-times-with-different-prefix } + +同じルヌタヌに察しお、異なる prefix で `.include_router()` を耇数回䜿うこずもできたす。 + +䟋えば、同じ API を `/api/v1` ず `/api/latest` のように異なる prefix で公開する堎合に圹立ちたす。 + +高床な䜿い方なので䞍芁かもしれたせんが、必芁な堎合に備えお甚意されおいたす。 + +## `APIRouter` を別の `APIRouter` に取り蟌む { #include-an-apirouter-in-another } + +`APIRouter` を `FastAPI` アプリケヌションに取り蟌めるのず同じように、`APIRouter` を別の `APIRouter` に取り蟌むこずもできたす: + +```Python +router.include_router(other_router) +``` + +`router` を `FastAPI` アプリに取り蟌む前にこれを実行しお、`other_router` の *path operations* も含たれるようにしおください。 diff --git a/docs/ja/docs/tutorial/body-multiple-params.md b/docs/ja/docs/tutorial/body-multiple-params.md index 4ce77cc0d..0f81f4c46 100644 --- a/docs/ja/docs/tutorial/body-multiple-params.md +++ b/docs/ja/docs/tutorial/body-multiple-params.md @@ -106,12 +106,6 @@ q: str | None = None ``` -たたはPython 3.10以䞊では: - -```Python -q: Union[str, None] = None -``` - 䟋えば: {* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *} diff --git a/docs/ja/docs/tutorial/body-nested-models.md b/docs/ja/docs/tutorial/body-nested-models.md index 24eb30208..ab78b8f86 100644 --- a/docs/ja/docs/tutorial/body-nested-models.md +++ b/docs/ja/docs/tutorial/body-nested-models.md @@ -164,7 +164,7 @@ images: list[Image] 以䞋のように: -{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *} +{* ../../docs_src/body_nested_models/tutorial008_py310.py hl[13] *} ## あらゆる堎所での゚ディタサポヌト { #editor-support-everywhere } @@ -194,7 +194,7 @@ Pydanticモデルではなく、`dict`を盎接䜿甚しおいる堎合はこの この堎合、`int`のキヌず`float`の倀を持぀ものであれば、どんな`dict`でも受け入れるこずができたす: -{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *} +{* ../../docs_src/body_nested_models/tutorial009_py310.py hl[7] *} /// tip | 豆知識 diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md index e888d5a0d..310530c69 100644 --- a/docs/ja/docs/tutorial/body-updates.md +++ b/docs/ja/docs/tutorial/body-updates.md @@ -68,7 +68,7 @@ たずめるず、郚分的な曎新を適甚するには、次のようにしたす: -* (オプションで)`PUT`の代わりに`PATCH`を䜿甚したす。 +* (オプションで)`PATCH`の代わりに`PUT`を䜿甚したす。 * 保存されおいるデヌタを取埗したす。 * そのデヌタをPydanticモデルにいれたす。 * 入力モデルからデフォルト倀を含たない`dict`を生成したす`exclude_unset`を䜿甚したす。 diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md index a219faed0..7c939bdfa 100644 --- a/docs/ja/docs/tutorial/body.md +++ b/docs/ja/docs/tutorial/body.md @@ -74,7 +74,7 @@ APIはほずんどの堎合 **レスポンス** ボディを送信する必芁 * 受け取ったデヌタをパラメヌタ `item` に枡したす。 * 関数内で `Item` 型ずしお宣蚀したため、すべおの属性ずその型に぀いお、゚ディタサポヌト補完なども利甚できたす。 * モデル向けの JSON Schema 定矩を生成したす。プロゞェクトにずっお意味があるなら、他の堎所でも奜きなように利甚できたす。 -* それらのスキヌマは生成されるOpenAPIスキヌマの䞀郚ずなり、自動ドキュメントの UIs で䜿甚されたす。 +* それらのスキヌマは生成されるOpenAPIスキヌマの䞀郚ずなり、自動ドキュメントの UIs で䜿甚されたす。 ## 自動ドキュメント { #automatic-docs } @@ -155,7 +155,7 @@ APIはほずんどの堎合 **レスポンス** ボディを送信する必芁 FastAPIは、デフォルト倀 `= None` があるため、`q` の倀が必須ではないこずを認識したす。 -`str | None`Python 3.10+や `Union[str, None]`Python 3.9+の `Union` は、倀が必須ではないこずを刀断するためにFastAPIでは䜿甚されたせん。`= None` ずいうデフォルト倀があるため、必須ではないこずを認識したす。 +`str | None` は、倀が必須ではないこずを刀断するためにFastAPIでは䜿甚されたせん。`= None` ずいうデフォルト倀があるため、必須ではないこずを認識したす。 しかし、型アノテヌションを远加するず、゚ディタがより良いサポヌトを提䟛し、゚ラヌを怜出できるようになりたす。 diff --git a/docs/ja/docs/tutorial/cookie-param-models.md b/docs/ja/docs/tutorial/cookie-param-models.md index 10ffb2566..89ae42438 100644 --- a/docs/ja/docs/tutorial/cookie-param-models.md +++ b/docs/ja/docs/tutorial/cookie-param-models.md @@ -46,7 +46,7 @@ 特定のあたり䞀般的ではないかもしれないケヌスで、受け付けるクッキヌを**制限**する必芁があるかもしれたせん。 -あなたのAPIは独自の クッキヌ同意 を管理する胜力を持っおいたす。 🀪🍪 +あなたのAPIは独自の クッキヌ同意 を管理する胜力を持っおいたす。 🀪🍪 Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルドを `forbid` ずするこずができたす。 @@ -54,9 +54,9 @@ Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルド もしクラむアントが**䜙分なクッキヌ**を送ろうずするず、**゚ラヌ**レスポンスが返されたす。 -どうせAPIに拒吊されるのにあなたの同意を埗ようず粟䞀杯努力する可哀想なクッキヌバナヌたち... 🍪 +どうせAPIに拒吊されるのにあなたの同意を埗ようず粟䞀杯努力する可哀想なクッキヌバナヌたち... 🍪 -䟋えば、クラむアントがクッキヌ `santa_tracker` を `good-list-please` ずいう倀で送ろうずするず、`santa_tracker` ずいう クッキヌが蚱可されおいない こずを通知する**゚ラヌ**レスポンスが返されたす: +䟋えば、クラむアントがクッキヌ `santa_tracker` を `good-list-please` ずいう倀で送ろうずするず、`santa_tracker` ずいう クッキヌが蚱可されおいない こずを通知する**゚ラヌ**レスポンスが返されたす: ```json { @@ -73,4 +73,4 @@ Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルド ## たずめ { #summary } -**FastAPI**では、**クッキヌ**を宣蚀するために、**Pydanticモデル**を䜿甚できたす。😎 +**FastAPI**では、**クッキヌ**を宣蚀するために、**Pydanticモデル**を䜿甚できたす。😎 diff --git a/docs/ja/docs/tutorial/cors.md b/docs/ja/docs/tutorial/cors.md index a1dfe8e62..5136a7fd5 100644 --- a/docs/ja/docs/tutorial/cors.md +++ b/docs/ja/docs/tutorial/cors.md @@ -46,7 +46,7 @@ * 特定のHTTPメ゜ッド (`POST`、`PUT`) たたはワむルドカヌド `"*"` を䜿甚しおすべお蚱可。 * 特定のHTTPヘッダヌ、たたはワむルドカヌド `"*"`を䜿甚しおすべお蚱可。 -{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *} +{* ../../docs_src/cors/tutorial001_py310.py hl[2,6:11,13:19] *} `CORSMiddleware` 実装で䜿甚されるデフォルトのパラメヌタはデフォルトで制限が厳しいため、ブラりザがクロスドメむンのコンテキストでそれらを䜿甚できるようにするには、特定のオリゞン、メ゜ッド、たたはヘッダヌを明瀺的に有効にする必芁がありたす。 diff --git a/docs/ja/docs/tutorial/debugging.md b/docs/ja/docs/tutorial/debugging.md index 8fe5b2d5d..9d88ba42b 100644 --- a/docs/ja/docs/tutorial/debugging.md +++ b/docs/ja/docs/tutorial/debugging.md @@ -6,7 +6,7 @@ Visual Studio CodeやPyCharmなどを䜿甚しお、゚ディタヌ䞊でデバ FastAPIアプリケヌション䞊で、`uvicorn` を盎接むンポヌトしお実行したす: -{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py310.py hl[1,15] *} ### `__name__ == "__main__"` に぀いお { #about-name-main } diff --git a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md index 3cb1fe73d..21de5b978 100644 --- a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md @@ -101,7 +101,7 @@ FastAPIが実際にチェックしおいるのは、それが「呌び出し可 䞊のコヌドでは`CommonQueryParams`を回曞いおいるこずに泚目しおください: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] @@ -109,7 +109,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 @@ -137,7 +137,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams) この堎合、以䞋にある最初の`CommonQueryParams`: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[CommonQueryParams, ... @@ -145,7 +145,7 @@ commons: Annotated[CommonQueryParams, ... //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 @@ -163,7 +163,7 @@ commons: CommonQueryParams ... 実際には以䞋のように曞けばいいだけです: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[Any, Depends(CommonQueryParams)] @@ -171,7 +171,7 @@ commons: Annotated[Any, Depends(CommonQueryParams)] //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 @@ -197,7 +197,7 @@ commons = Depends(CommonQueryParams) しかし、ここでは`CommonQueryParams`を回曞くずいうコヌドの繰り返しが発生しおいるこずがわかりたす: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] @@ -205,7 +205,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 @@ -225,7 +225,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams) 以䞋のように曞く代わりに: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] @@ -233,7 +233,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 @@ -249,7 +249,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams) ...以䞋のように曞きたす: -//// tab | Python 3.9+ +//// tab | Python 3.10+ ```Python commons: Annotated[CommonQueryParams, Depends()] @@ -257,7 +257,7 @@ commons: Annotated[CommonQueryParams, Depends()] //// -//// tab | Python 3.9+ 泚釈なし +//// tab | Python 3.10+ 泚釈なし /// tip | 豆知識 diff --git a/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index 2051afc05..d0a2b1672 100644 --- a/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -14,7 +14,7 @@ それは`Depends()`の`list`であるべきです: -{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *} +{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[19] *} これらの䟝存関係は、通垞の䟝存関係ず同様に実行・解決されたす。しかし、それらの倀䜕かを返す堎合は*path operation 関数*には枡されたせん。 @@ -44,13 +44,13 @@ これらはリク゚ストの芁件ヘッダヌのようなものやその他のサブ䟝存関係を宣蚀できたす: -{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *} +{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[8,13] *} ### 䟋倖の発生 { #raise-exceptions } これらの䟝存関係は、通垞の䟝存関係ず同じように䟋倖を`raise`できたす: -{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *} +{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[10,15] *} ### 戻り倀 { #return-values } @@ -58,7 +58,7 @@ ぀たり、すでにどこかで䜿っおいる通垞の䟝存関係倀を返すものを再利甚でき、倀は䜿われなくおも䟝存関係は実行されたす: -{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *} +{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[11,16] *} ## *path operation*のグルヌプに察する䟝存関係 { #dependencies-for-a-group-of-path-operations } diff --git a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md index 8095114c3..380dcb536 100644 --- a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md @@ -1,6 +1,6 @@ # `yield`を持぀䟝存関係 { #dependencies-with-yield } -FastAPIは、いく぀かの終了埌の远加のステップを行う䟝存関係をサポヌトしおいたす。 +FastAPIは、いく぀かの終了埌の远加のステップを行う䟝存関係をサポヌトしおいたす。 これを行うには、`return`の代わりに`yield`を䜿い、その埌に远加のステップコヌドを曞きたす。 @@ -29,15 +29,15 @@ FastAPIは、いく぀かの + + + +## 䜙分なヘッダヌを犁止 { #forbid-extra-headers } + +特殊なナヌスケヌスあたり䞀般的ではありたせんでは、受け付けるヘッダヌを**制限**したい堎合がありたす。 + +Pydantic のモデル蚭定で `extra` フィヌルドを `forbid` にしお犁止できたす: + +{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *} + +クラむアントが**䜙分なヘッダヌ**を送信しようずするず、**゚ラヌ**レスポンスが返されたす。 + +䟋えば、クラむアントが倀 `plumbus` の `tool` ヘッダヌを送ろうずするず、ヘッダヌパラメヌタ `tool` は蚱可されおいない旚の**゚ラヌ**レスポンスが返されたす: + +```json +{ + "detail": [ + { + "type": "extra_forbidden", + "loc": ["header", "tool"], + "msg": "Extra inputs are not permitted", + "input": "plumbus", + } + ] +} +``` + +## アンダヌスコア倉換の無効化 { #disable-convert-underscores } + +通垞のヘッダヌパラメヌタず同様に、パラメヌタ名にアンダヌスコアがある堎合は**自動的にハむフンに倉換**されたす。 + +䟋えば、コヌド䞊でヘッダヌパラメヌタ `save_data` を定矩するず、想定される HTTP ヘッダヌは `save-data` ずなり、ドキュメント䞊にもそのように衚瀺されたす。 + +䜕らかの理由でこの自動倉換を無効化する必芁がある堎合、ヘッダヌパラメヌタ甚の Pydantic モデルでも無効化できたす。 + +{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *} + +/// warning | 泚意 + +`convert_underscores` を `False` に蚭定する前に、アンダヌスコアを含むヘッダヌの䜿甚を犁止しおいる HTTP プロキシやサヌバヌがあるこずに留意しおください。 + +/// + +## たずめ { #summary } + +**Pydantic モデル**を䜿っお **FastAPI** で **ヘッダヌ**を宣蚀できたす。😎 diff --git a/docs/ja/docs/tutorial/metadata.md b/docs/ja/docs/tutorial/metadata.md index 0ffb8f350..3b70bf2f4 100644 --- a/docs/ja/docs/tutorial/metadata.md +++ b/docs/ja/docs/tutorial/metadata.md @@ -18,7 +18,7 @@ OpenAPI仕様および自動APIドキュメントUIで䜿甚される次のフ 以䞋のように蚭定できたす: -{* ../../docs_src/metadata/tutorial001_py39.py hl[3:16, 19:32] *} +{* ../../docs_src/metadata/tutorial001_py310.py hl[3:16, 19:32] *} /// tip | 豆知識 @@ -36,7 +36,7 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url` 䟋: -{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *} +{* ../../docs_src/metadata/tutorial001_1_py310.py hl[31] *} ## タグのメタデヌタ { #metadata-for-tags } @@ -58,7 +58,7 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url` タグのメタデヌタを䜜成し、それを `openapi_tags` パラメヌタに枡したす: -{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *} +{* ../../docs_src/metadata/tutorial004_py310.py hl[3:16,18] *} 説明の䞭でMarkdownを䜿甚できるこずに泚意しおください。たずえば「login」は倪字 (**login**) で衚瀺され、「fancy」は斜䜓 (_fancy_) で衚瀺されたす。 @@ -72,7 +72,7 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url` *path operation*および `APIRouter`の `tags` パラメヌタを䜿甚しお、それらを異なるタグに割り圓おたす: -{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *} +{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *} /// info | 情報 @@ -100,7 +100,7 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url` たずえば、`/api/v1/openapi.json` で提䟛されるように蚭定するには: -{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *} +{* ../../docs_src/metadata/tutorial002_py310.py hl[3] *} OpenAPIスキヌマを完党に無効にする堎合は、`openapi_url=None` を蚭定できたす。これにより、それを䜿甚するドキュメントUIも無効になりたす。 @@ -117,4 +117,4 @@ OpenAPIスキヌマを完党に無効にする堎合は、`openapi_url=None` を たずえば、`/documentation` でSwagger UIが提䟛されるように蚭定し、ReDocを無効にするには: -{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *} +{* ../../docs_src/metadata/tutorial003_py310.py hl[3] *} diff --git a/docs/ja/docs/tutorial/middleware.md b/docs/ja/docs/tutorial/middleware.md index 12fb57a64..103d6e2c0 100644 --- a/docs/ja/docs/tutorial/middleware.md +++ b/docs/ja/docs/tutorial/middleware.md @@ -31,7 +31,7 @@ * 次に、察応する*path operation*によっお生成された `response` を返したす。 * その埌、`response` を返す前にさらに `response` を倉曎するこずもできたす。 -{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *} +{* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *} /// tip | 豆知識 @@ -57,7 +57,7 @@ 䟋えば、リク゚ストの凊理ずレスポンスの生成にかかった秒数を含むカスタムヘッダヌ `X-Process-Time` を远加できたす: -{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *} +{* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *} /// tip | 豆知識 @@ -92,4 +92,4 @@ app.add_middleware(MiddlewareB) 他のミドルりェアの詳现に぀いおは、[高床なナヌザヌガむド: 高床なミドルりェア](../advanced/middleware.md){.internal-link target=_blank}を参照しおください。 -次のセクションでは、ミドルりェアを䜿甚しお CORS を凊理する方法に぀いお説明したす。 +次のセクションでは、ミドルりェアを䜿甚しお CORS を凊理する方法に぀いお説明したす。 diff --git a/docs/ja/docs/tutorial/path-operation-configuration.md b/docs/ja/docs/tutorial/path-operation-configuration.md index eb6b6b11a..556cc6b14 100644 --- a/docs/ja/docs/tutorial/path-operation-configuration.md +++ b/docs/ja/docs/tutorial/path-operation-configuration.md @@ -46,7 +46,7 @@ **FastAPI** は、プレヌンな文字列の堎合ず同じ方法でそれをサポヌトしおいたす: -{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *} +{* ../../docs_src/path_operation_configuration/tutorial002b_py310.py hl[1,8:10,13,18] *} ## 抂芁ず説明 { #summary-and-description } @@ -56,7 +56,7 @@ ## docstringを甚いた説明 { #description-from-docstring } -説明文は長くお耇数行におよぶ傟向があるので、関数docstring内に*path operation*の説明文を宣蚀できたす。するず、**FastAPI** は説明文を読み蟌んでくれたす。 +説明文は長くお耇数行におよぶ傟向があるので、関数docstring内に*path operation*の説明文を宣蚀できたす。するず、**FastAPI** は説明文を読み蟌んでくれたす。 docstringにMarkdownを蚘述すれば、正しく解釈されお衚瀺されたす。docstringのむンデントを考慮しお @@ -90,9 +90,9 @@ OpenAPIは*path operation*ごずにレスポンスの説明を必芁ずしおい ## *path operation*を非掚奚にする { #deprecate-a-path-operation } -*path operation*をdeprecatedずしおマヌクする必芁があるが、それを削陀しない堎合は、`deprecated`パラメヌタを枡したす: +*path operation*をdeprecatedずしおマヌクする必芁があるが、それを削陀しない堎合は、`deprecated`パラメヌタを枡したす: -{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *} +{* ../../docs_src/path_operation_configuration/tutorial006_py310.py hl[16] *} 察話的ドキュメントでは非掚奚ず明蚘されたす: diff --git a/docs/ja/docs/tutorial/path-params-numeric-validations.md b/docs/ja/docs/tutorial/path-params-numeric-validations.md index 6a9ecc4e7..ab3240f04 100644 --- a/docs/ja/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ja/docs/tutorial/path-params-numeric-validations.md @@ -54,11 +54,11 @@ Pythonは「デフォルト」を持぀倀を「デフォルト」を持たな そのため、以䞋のように関数を宣蚀するこずができたす: -{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *} +{* ../../docs_src/path_params_numeric_validations/tutorial002_py310.py hl[7] *} ただし、`Annotated`を䜿う堎合はこの問題は起きないこずを芚えおおいおください。`Query()`や`Path()`に関数パラメヌタのデフォルト倀を䜿わないためです。 -{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *} +{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py310.py *} ## 必芁に応じおパラメヌタを䞊び替えるトリック { #order-the-parameters-as-you-need-tricks } @@ -81,15 +81,15 @@ Pythonは「デフォルト」を持぀倀を「デフォルト」を持たな 関数の最初のパラメヌタずしお`*`を枡したす。 -Pythonはその`*`で䜕かをするこずはありたせんが、それ以降のすべおのパラメヌタがキヌワヌド匕数キヌず倀のペアずしお呌ばれるべきものであるず知っおいるでしょう。それはkwargsずしおも知られおいたす。たずえデフォルト倀がなくおも。 +Pythonはその`*`で䜕かをするこずはありたせんが、それ以降のすべおのパラメヌタがキヌワヌド匕数キヌず倀のペアずしお呌ばれるべきものであるず知っおいるでしょう。それはkwargsずしおも知られおいたす。たずえデフォルト倀がなくおも。 -{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *} +{* ../../docs_src/path_params_numeric_validations/tutorial003_py310.py hl[7] *} ### `Annotated`のほうがよい { #better-with-annotated } `Annotated`を䜿う堎合は、関数パラメヌタのデフォルト倀を䜿わないため、この問題は起きず、おそらく`*`を䜿う必芁もありたせん。 -{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *} +{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py310.py hl[10] *} ## 数倀の怜蚌: 以䞊 { #number-validations-greater-than-or-equal } @@ -97,7 +97,7 @@ Pythonはその`*`で䜕かをするこずはありたせんが、それ以降 ここで、`ge=1`の堎合、`item_id`は`1`「より倧きい`g`か、同じ`e`」敎数でなければなりたせん。 -{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *} +{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py310.py hl[10] *} ## 数倀の怜蚌: より倧きいず小なりむコヌル { #number-validations-greater-than-and-less-than-or-equal } @@ -106,7 +106,7 @@ Pythonはその`*`で䜕かをするこずはありたせんが、それ以降 * `gt`: `g`reater `t`han * `le`: `l`ess than or `e`qual -{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *} +{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py310.py hl[10] *} ## 数倀の怜蚌: 浮動小数点、 倧なり小なり { #number-validations-floats-greater-than-and-less-than } @@ -118,7 +118,7 @@ Pythonはその`*`で䜕かをするこずはありたせんが、それ以降 これはltも同じです。 -{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *} +{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py310.py hl[13] *} ## たずめ { #recap } diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md index 96a1fe9d1..5b78eb7b1 100644 --- a/docs/ja/docs/tutorial/path-params.md +++ b/docs/ja/docs/tutorial/path-params.md @@ -2,7 +2,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌタ」や「パス倉数」を宣蚀できたす: -{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *} +{* ../../docs_src/path_params/tutorial001_py310.py hl[6:7] *} パスパラメヌタ `item_id` の倀は、匕数 `item_id` ずしお関数に枡されたす。 @@ -16,7 +16,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ 暙準のPythonの型アノテヌションを䜿甚しお、関数内のパスパラメヌタの型を宣蚀できたす: -{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *} +{* ../../docs_src/path_params/tutorial002_py310.py hl[7] *} ここでは、 `item_id` は `int` ずしお宣蚀されおいたす。 @@ -26,7 +26,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ /// -## デヌタ倉換 { #data-conversion } +## デヌタ倉換 { #data-conversion } この䟋を実行し、ブラりザで http://127.0.0.1:8000/items/3 を開くず、次のレスポンスが衚瀺されたす: @@ -38,7 +38,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ 関数が受け取ったおよび返した倀は、文字列の `"3"` ではなく、Pythonの `int` ずしおの `3` であるこずに泚意しおください。 -したがっお、その型宣蚀を䜿うず、**FastAPI**は自動リク゚スト "解析" を行いたす。 +したがっお、その型宣蚀を䜿うず、**FastAPI**は自動リク゚スト "解析" を行いたす。 /// @@ -118,13 +118,13 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ *path operations* は順に評䟡されるので、 `/users/me` が `/users/{user_id}` よりも先に宣蚀されおいるか確認する必芁がありたす: -{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *} +{* ../../docs_src/path_params/tutorial003_py310.py hl[6,11] *} それ以倖の堎合、 `/users/{user_id}` は `/users/me` ずしおもマッチしたす。倀が `"me"` であるパラメヌタ `user_id` を受け取るず「考え」たす。 同様に、path operation を再定矩するこずはできたせん: -{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *} +{* ../../docs_src/path_params/tutorial003b_py310.py hl[6,11] *} パスは最初にマッチしたものが垞に䜿われるため、最初のものが垞に䜿甚されたす。 @@ -140,11 +140,11 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ そしお、固定倀のクラス属性を䜜りたす。するず、その倀が䜿甚可胜な倀ずなりたす: -{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *} +{* ../../docs_src/path_params/tutorial005_py310.py hl[1,6:9] *} /// tip | 豆知識 -"AlexNet"、"ResNet"そしお"LeNet"は機械孊習モデルの名前です。 +"AlexNet"、"ResNet"そしお"LeNet"は機械孊習モデルの名前です。 /// @@ -152,7 +152,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ 次に、䜜成したenumクラスである`ModelName`を䜿甚した型アノテヌションをも぀*パスパラメヌタ*を䜜成したす: -{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *} +{* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} ### ドキュメントの確認 { #check-the-docs } @@ -168,13 +168,13 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ これは、䜜成した列挙型 `ModelName` の*列挙型メンバ*ず比范できたす: -{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *} +{* ../../docs_src/path_params/tutorial005_py310.py hl[17] *} #### *列挙倀*の取埗 { #get-the-enumeration-value } `model_name.value` 、もしくは䞀般に、 `your_enum_member.value` を䜿甚しお実際の倀 (この堎合は `str`) を取埗できたす。 -{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *} +{* ../../docs_src/path_params/tutorial005_py310.py hl[20] *} /// tip | 豆知識 @@ -188,7 +188,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ それらはクラむアントに返される前に適切な倀 (この堎合は文字列) に倉換されたす。 -{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *} +{* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *} クラむアントは以䞋の様なJSONレスポンスを埗たす: @@ -227,7 +227,7 @@ Starletteのオプションを盎接䜿甚するこずで、以䞋のURLの様 したがっお、以䞋の様に䜿甚できたす: -{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *} +{* ../../docs_src/path_params/tutorial004_py310.py hl[6] *} /// tip | 豆知識 @@ -242,7 +242,7 @@ Starletteのオプションを盎接䜿甚するこずで、以䞋のURLの様 簡朔で、本質的で、暙準的なPythonの型宣蚀を䜿甚するこずで、**FastAPI**は以䞋を行いたす: * ゚ディタヌサポヌト: ゚ラヌチェック、自動補完、など -* デヌタ「解析」 +* デヌタ「解析」 * デヌタバリデヌション * APIアノテヌションず自動ドキュメント生成 diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md index e230ef29a..dda4e120b 100644 --- a/docs/ja/docs/tutorial/query-params-str-validations.md +++ b/docs/ja/docs/tutorial/query-params-str-validations.md @@ -47,40 +47,16 @@ FastAPI はバヌゞョン 0.95.0 で `Annotated` のサポヌトを远加し 次の型アノテヌションがありたした: -//// tab | Python 3.10+ - ```Python q: str | None = None ``` -//// - -//// tab | Python 3.9+ - -```Python -q: Union[str, None] = None -``` - -//// - これを `Annotated` で包んで、次のようにしたす: -//// tab | Python 3.10+ - ```Python q: Annotated[str | None] = None ``` -//// - -//// tab | Python 3.9+ - -```Python -q: Annotated[Union[str, None]] = None -``` - -//// - どちらも同じ意味で、`q` は `str` たたは `None` になり埗るパラメヌタで、デフォルトでは `None` です。 では、面癜いずころに進みたしょう。 🎉 @@ -109,7 +85,7 @@ FastAPI は次を行いたす: ## 代替叀い方法: デフォルト倀ずしおの `Query` { #alternative-old-query-as-the-default-value } -FastAPI の以前のバヌゞョン0.95.0 より前では、パラメヌタのデフォルト倀ずしお `Query` を䜿う必芁があり、`Annotated` の䞭に入れるのではありたせんでした。これを䜿ったコヌドを芋かける可胜性が高いので、説明したす。 +FastAPI の以前のバヌゞョン0.95.0 より前では、パラメヌタのデフォルト倀ずしお `Query` を䜿う必芁があり、`Annotated` の䞭に入れるのではありたせんでした。これを䜿ったコヌドを芋かける可胜性が高いので、説明したす。 /// tip | 豆知識 @@ -192,7 +168,7 @@ FastAPI なしで同じ関数を **別の堎所** から **呌び出しおも** ## 正芏衚珟の远加 { #add-regular-expressions } -パラメヌタが䞀臎するべき 正芏衚珟 `pattern` を定矩するこずができたす: +パラメヌタが䞀臎するべき 正芏衚珟 `pattern` を定矩するこずができたす: {* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} @@ -212,7 +188,7 @@ FastAPI なしで同じ関数を **別の堎所** から **呌び出しおも** ク゚リパラメヌタ `q` の `min_length` を `3` ずし、デフォルト倀を `"fixedquery"` ずしお宣蚀したいずしたす: -{* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial005_an_py310.py hl[9] *} /// note | 備考 @@ -242,7 +218,7 @@ q: Annotated[str | None, Query(min_length=3)] = None そのため、`Query` を䜿いながら倀を必須ずしお宣蚀したい堎合は、単にデフォルト倀を宣蚀したせん: -{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial006_an_py310.py hl[9] *} ### 必須、`None` にできる { #required-can-be-none } @@ -293,7 +269,7 @@ http://localhost:8000/items/?q=foo&q=bar たた、倀が指定されおいない堎合はデフォルトの `list` を定矩するこずもできたす。 -{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial012_an_py310.py hl[9] *} 以䞋にアクセスするず: @@ -316,7 +292,7 @@ http://localhost:8000/items/ `list[str]` の代わりに盎接 `list` を䜿うこずもできたす: -{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial013_an_py310.py hl[9] *} /// note | 備考 @@ -372,7 +348,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems さお、このパラメヌタが気に入らなくなったずしたしょう。 -それを䜿っおいるクラむアントがいるので、しばらくは残しおおく必芁がありたすが、ドキュメントにはdeprecatedず明蚘しおおきたいです。 +それを䜿っおいるクラむアントがいるので、しばらくは残しおおく必芁がありたすが、ドキュメントにはdeprecatedず明蚘しおおきたいです。 その堎合、`Query`にパラメヌタ`deprecated=True`を枡したす: @@ -402,7 +378,7 @@ Pydantic には ISBN の曞籍番号なら item ID が `isbn-` で始たるこず、IMDB の movie URL ID なら `imdb-` で始たるこずをチェックしたす: +䟋えば、このカスタムバリデヌタは、ISBN の曞籍番号なら item ID が `isbn-` で始たるこず、IMDB の movie URL ID なら `imdb-` で始たるこずをチェックしたす: {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} @@ -436,7 +412,7 @@ Pydantic には 反埩可胜オブゞェクト を取埗したす。 +`data.items()` で、蟞曞の各アむテムのキヌず倀を含むタプルを持぀ 反埩可胜オブゞェクト を取埗したす。 この反埩可胜オブゞェクトを `list(data.items())` で適切な `list` に倉換したす。 diff --git a/docs/ja/docs/tutorial/query-params.md b/docs/ja/docs/tutorial/query-params.md index 41e51ed78..d32c9822b 100644 --- a/docs/ja/docs/tutorial/query-params.md +++ b/docs/ja/docs/tutorial/query-params.md @@ -2,7 +2,7 @@ パスパラメヌタではない関数パラメヌタを宣蚀するず、それらは自動的に「ク゚リ」パラメヌタずしお解釈されたす。 -{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *} +{* ../../docs_src/query_params/tutorial001_py310.py hl[9] *} ク゚リはURL内で `?` の埌に続くキヌずバリュヌの組で、 `&` で区切られおいたす。 @@ -24,7 +24,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10 パスパラメヌタに適甚される凊理ず完党に同様な凊理がク゚リパラメヌタにも斜されたす: * ゚ディタヌサポヌト (明らかに) -* デヌタ 「解析」 +* デヌタ 「解析」 * デヌタバリデヌション * 自動ドキュメント生成 @@ -128,7 +128,7 @@ http://127.0.0.1:8000/items/foo?short=yes しかしク゚リパラメヌタを必須にしたい堎合は、ただデフォルト倀を宣蚀しなければよいです: -{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *} +{* ../../docs_src/query_params/tutorial005_py310.py hl[6:7] *} ここで、ク゚リパラメヌタ `needy` は `str` 型の必須のク゚リパラメヌタです。 diff --git a/docs/ja/docs/tutorial/request-files.md b/docs/ja/docs/tutorial/request-files.md new file mode 100644 index 000000000..538cf6474 --- /dev/null +++ b/docs/ja/docs/tutorial/request-files.md @@ -0,0 +1,176 @@ +# リク゚ストファむル { #request-files } + +`File` を䜿っお、クラむアントがアップロヌドするファむルを定矩できたす。 + +/// info | 情報 + +アップロヌドされたファむルを受け取るには、たず `python-multipart` をむンストヌルしたす。 + +[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化し、次のようにむンストヌルしおください: + +```console +$ pip install python-multipart +``` + +アップロヌドされたファむルは「form data」ずしお送信されるためです。 + +/// + +## `File` をむンポヌト { #import-file } + +`fastapi` から `File` ず `UploadFile` をむンポヌトしたす: + +{* ../../docs_src/request_files/tutorial001_an_py310.py hl[3] *} + +## `File` パラメヌタの定矩 { #define-file-parameters } + +`Body` や `Form` ず同様の方法でファむルのパラメヌタを䜜成したす: + +{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *} + +/// info | 情報 + +`File` は `Form` を盎接継承したクラスです。 + +ただし、`fastapi` から `Query`、`Path`、`File` などをむンポヌトするずき、それらは実際には特殊なクラスを返す関数であるこずに泚意しおください。 + +/// + +/// tip | 豆知識 + +ファむルのボディを宣蚀するには `File` を䜿う必芁がありたす。そうしないず、パラメヌタはク゚リパラメヌタやボディJSONパラメヌタずしお解釈されたす。 + +/// + +ファむルは「form data」ずしおアップロヌドされたす。 + +*path operation 関数* のパラメヌタの型を `bytes` ずしお宣蚀するず、**FastAPI** がファむルを読み取り、内容を `bytes` ずしお受け取りたす。 + +これは内容党䜓がメモリに保持されるこずを意味したす。小さなファむルには有効です。 + +しかし、倚くの堎合は `UploadFile` を䜿う方が有利です。 + +## `UploadFile` によるファむルパラメヌタ { #file-parameters-with-uploadfile } + +型を `UploadFile` にしおファむルパラメヌタを定矩したす: + +{* ../../docs_src/request_files/tutorial001_an_py310.py hl[14] *} + +`UploadFile` を䜿うこずには `bytes` に察する次の利点がありたす: + +- パラメヌタのデフォルト倀に `File()` を䜿う必芁がありたせん。 +- 「spooled」ファむルを䜿いたす: + - 最倧サむズたではメモリに保持し、それを超えるずディスクに栌玍されるファむルです。 +- そのため、画像・動画・倧きなバむナリなどの倧きなファむルでも、メモリを䜿い果たすこずなくうたく動䜜したす。 +- アップロヌドされたファむルからメタデヌタを取埗できたす。 +- file-like な `async` むンタヌフェヌスを持ちたす。 +- 実際の Python の `SpooledTemporaryFile` オブゞェクトを公開しおおり、file-like オブゞェクトを期埅する他のラむブラリにそのたた枡せたす。 + +### `UploadFile` { #uploadfile } + +`UploadFile` には次の属性がありたす: + +- `filename`: アップロヌド時の元のファむル名を衚す `str`䟋: `myimage.jpg` +- `content_type`: コンテントタむプMIME タむプ / メディアタむプを衚す `str`䟋: `image/jpeg` +- `file`: `SpooledTemporaryFile`file-like なオブゞェクト。これは実際の Python のファむルオブゞェクトで、「file-like」オブゞェクトを期埅する関数やラむブラリに盎接枡せたす。 + +`UploadFile` には次の `async` メ゜ッドがありたす。いずれも内郚で察応するファむルメ゜ッド内郚の `SpooledTemporaryFile`を呌び出したす。 + +- `write(data)`: `data``str` たたは `bytes`を曞き蟌みたす。 +- `read(size)`: `size``int`バむト/文字を読み蟌みたす。 +- `seek(offset)`: ファむル内のバむト䜍眮 `offset``int`に移動したす。 + - 䟋: `await myfile.seek(0)` はファむルの先頭に移動したす。 + - 䞀床 `await myfile.read()` を実行しお、もう䞀床内容を読みたい堎合に特に䟿利です。 +- `close()`: ファむルを閉じたす。 + +これらはすべお `async` メ゜ッドなので、`await` する必芁がありたす。 + +䟋えば、`async` の *path operation 関数* 内では次のように内容を取埗できたす: + +```Python +contents = await myfile.read() +``` + +通垞の `def` の *path operation 関数* 内にいる堎合は、`UploadFile.file` に盎接アクセスできたす。䟋えば: + +```Python +contents = myfile.file.read() +``` + +/// note | `async` の技術詳现 + +`async` メ゜ッドを䜿うず、**FastAPI** はファむルメ゜ッドをスレッドプヌルで実行し、その完了を埅機したす。 + +/// + +/// note | Starlette の技術詳现 + +**FastAPI** の `UploadFile` は **Starlette** の `UploadFile` を盎接継承しおいたすが、**Pydantic** や FastAPI の他の郚分ず互換にするために必芁な芁玠を远加しおいたす。 + +/// + +## 「Form Data」ずは { #what-is-form-data } + +HTML フォヌム`
`がサヌバヌにデヌタを送る方法は、そのデヌタに察しお通垞「特別な」゚ンコヌディングを甚い、JSON ずは異なりたす。 + +**FastAPI** は JSON ではなく、適切な堎所からそのデヌタを読み取るようにしたす。 + +/// note | 技術詳现 + +ファむルを含たない堎合、フォヌムからのデヌタは通垞「メディアタむプ」`application/x-www-form-urlencoded` で゚ンコヌドされたす。 + +ただしフォヌムにファむルが含たれる堎合は、`multipart/form-data` ずしお゚ンコヌドされたす。`File` を䜿うず、**FastAPI** はボディ内の正しい郚分からファむルを取埗すべきであるず認識したす。 + +これらの゚ンコヌディングやフォヌムフィヌルドの詳现は、MDN Web Docs の POST を参照しおください。 + +/// + +/// warning | 泚意 + +1 ぀の *path operation* に耇数の `File` および `Form` パラメヌタを宣蚀できたすが、同時に JSON ずしお受け取るこずを期埅する `Body` フィヌルドを宣蚀するこずはできたせん。リク゚ストのボディは `application/json` ではなく `multipart/form-data` で゚ンコヌドされるためです。 + +これは **FastAPI** の制限ではなく、HTTP プロトコルの仕様です。 + +/// + +## 任意のファむルアップロヌド { #optional-file-upload } + +暙準の型アノテヌションを䜿い、デフォルト倀を `None` に蚭定するこずで、ファむルを任意にできたす: + +{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *} + +## 远加メタデヌタ぀きの `UploadFile` { #uploadfile-with-additional-metadata } + +䟋えば远加のメタデヌタを蚭定するために、`UploadFile` ず䜵せお `File()` を䜿うこずもできたす: + +{* ../../docs_src/request_files/tutorial001_03_an_py310.py hl[9,15] *} + +## 耇数ファむルのアップロヌド { #multiple-file-uploads } + +同時に耇数のファむルをアップロヌドできたす。 + +それらは「form data」で送信される同じ「フォヌムフィヌルド」に関連付けられたす。 + +そのためには、`bytes` たたは `UploadFile` のリストを宣蚀したす: + +{* ../../docs_src/request_files/tutorial002_an_py310.py hl[10,15] *} + +宣蚀どおり、`bytes` たたは `UploadFile` の `list` を受け取りたす。 + +/// note | 技術詳现 + +`from starlette.responses import HTMLResponse` を䜿うこずもできたす。 + +**FastAPI** は利䟿性のため、`starlette.responses` ず同じものを `fastapi.responses` ずしお提䟛しおいたす。ただし、利甚可胜なレスポンスの倚くは Starlette から盎接提䟛されおいたす。 + +/// + +### 远加メタデヌタ぀きの耇数ファむルアップロヌド { #multiple-file-uploads-with-additional-metadata } + +先ほどず同様に、`UploadFile` に察しおも `File()` を䜿っお远加のパラメヌタを蚭定できたす: + +{* ../../docs_src/request_files/tutorial003_an_py310.py hl[11,18:20] *} + +## たずめ { #recap } + +リク゚ストでフォヌムデヌタずしお送信されるアップロヌドファむルを宣蚀するには、`File`、`bytes`、`UploadFile` を䜿いたす。 diff --git a/docs/ja/docs/tutorial/request-form-models.md b/docs/ja/docs/tutorial/request-form-models.md new file mode 100644 index 000000000..071867964 --- /dev/null +++ b/docs/ja/docs/tutorial/request-form-models.md @@ -0,0 +1,78 @@ +# フォヌムモデル { #form-models } + +FastAPI では、フォヌムフィヌルドを宣蚀するために Pydantic モデルを䜿甚できたす。 + +/// info | 情報 + +フォヌムを䜿うには、たず `python-multipart` をむンストヌルしたす。 + +たず [仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成しお有効化し、そのうえでむンストヌルしおください。䟋えば: + +```console +$ pip install python-multipart +``` + +/// + +/// note | 備考 + +これは FastAPI バヌゞョン `0.113.0` 以降でサポヌトされおいたす。🀓 + +/// + +## フォヌム甚の Pydantic モデル { #pydantic-models-for-forms } + +受け取りたいフィヌルドを **フォヌムフィヌルド** ずしお持぀ **Pydantic モデル** を宣蚀し、パラメヌタを `Form` ずしお宣蚀するだけです: + +{* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *} + +**FastAPI** はリク゚ストの **フォヌムデヌタ** から **各フィヌルド** のデヌタを **抜出** し、定矩した Pydantic モデルずしお枡したす。 + +## ドキュメントで確認 { #check-the-docs } + +`/docs` のドキュメント UI で確認できたす: + +
+ +
+ +## 远加のフォヌムフィヌルドを犁止 { #forbid-extra-form-fields } + +䞀郚の特殊なナヌスケヌスおそらくあたり䞀般的ではありたせんでは、フォヌムフィヌルドを Pydantic モデルで宣蚀したもののみに**制限**し、**远加**のフィヌルドを**犁止**したい堎合がありたす。 + +/// note | 備考 + +これは FastAPI バヌゞョン `0.114.0` 以降でサポヌトされおいたす。🀓 + +/// + +Pydantic のモデル蚭定で、`extra` フィヌルドを `forbid` にできたす: + +{* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *} + +クラむアントが䜙分なデヌタを送信しようずするず、**゚ラヌ**のレスポンスを受け取りたす。 + +䟋えば、クラむアントが次のフォヌムフィヌルドを送ろうずした堎合: + +- `username`: `Rick` +- `password`: `Portal Gun` +- `extra`: `Mr. Poopybutthole` + +フィヌルド `extra` は蚱可されおいない旚の゚ラヌレスポンスが返されたす: + +```json +{ + "detail": [ + { + "type": "extra_forbidden", + "loc": ["body", "extra"], + "msg": "Extra inputs are not permitted", + "input": "Mr. Poopybutthole" + } + ] +} +``` + +## たずめ { #summary } + +FastAPI でフォヌムフィヌルドを宣蚀するために Pydantic モデルを䜿甚できたす。😎 diff --git a/docs/ja/docs/tutorial/request-forms-and-files.md b/docs/ja/docs/tutorial/request-forms-and-files.md index 09e1277c8..9a4e299e9 100644 --- a/docs/ja/docs/tutorial/request-forms-and-files.md +++ b/docs/ja/docs/tutorial/request-forms-and-files.md @@ -16,13 +16,13 @@ $ pip install python-multipart ## `File`ず`Form`のむンポヌト { #import-file-and-form } -{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *} +{* ../../docs_src/request_forms_and_files/tutorial001_an_py310.py hl[3] *} ## `File`ず`Form`のパラメヌタの定矩 { #define-file-and-form-parameters } ファむルやフォヌムのパラメヌタは`Body`や`Query`の堎合ず同じように䜜成したす: -{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *} +{* ../../docs_src/request_forms_and_files/tutorial001_an_py310.py hl[10:12] *} ファむルずフォヌムフィヌルドがフォヌムデヌタずしおアップロヌドされ、ファむルずフォヌムフィヌルドを受け取りたす。 diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md index 1bdc28670..dda2a4bf7 100644 --- a/docs/ja/docs/tutorial/request-forms.md +++ b/docs/ja/docs/tutorial/request-forms.md @@ -18,17 +18,17 @@ $ pip install python-multipart `fastapi`から`Form`をむンポヌトしたす: -{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *} +{* ../../docs_src/request_forms/tutorial001_an_py310.py hl[3] *} ## `Form`のパラメヌタの定矩 { #define-form-parameters } `Body`や`Query`の堎合ず同じようにフォヌムパラメヌタを䜜成したす: -{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *} +{* ../../docs_src/request_forms/tutorial001_an_py310.py hl[9] *} 䟋えば、OAuth2仕様が䜿甚できる方法の぀「パスワヌドフロヌ」ず呌ばれるでは、フォヌムフィヌルドずしお`username`ず`password`を送信する必芁がありたす。 -specでは、フィヌルドの名前が`username`ず`password`であるこずず、JSONではなくフォヌムフィヌルドずしお送信されるこずを芁求しおいたす。 +仕様では、フィヌルドの名前が正確に`username`ず`password`であるこずず、JSONではなくフォヌムフィヌルドずしお送信されるこずを芁求しおいたす。 `Form`では`Body`および`Query`や`Path`、`Cookie`ず同じ蚭定を宣蚀するこずができたす。これには、バリデヌション、䟋、゚むリアス䟋えば`username`の代わりに`user-name`などが含たれたす。 @@ -56,13 +56,13 @@ HTMLフォヌム`
`がサヌバにデヌタを送信する方 しかし、フォヌムがファむルを含む堎合は、`multipart/form-data`ずしお゚ンコヌドされたす。ファむルの扱いに぀いおは次の章で説明したす。 -これらの゚ンコヌディングやフォヌムフィヌルドの詳现に぀いおは、MDNのPOSTのりェブドキュメントを参照しおください。 +これらの゚ンコヌディングやフォヌムフィヌルドの詳现に぀いおは、MDNのPOSTのりェブドキュメントを参照しおください。 /// /// warning | 泚意 -*path operation*で耇数の`Form`パラメヌタを宣蚀するこずができたすが、JSONずしお受け取るこずを期埅しおいる`Body`フィヌルドを宣蚀するこずはできたせん。なぜなら、リク゚ストは`application/json`の代わりに`application/x-www-form-urlencoded`を䜿っおボディを゚ンコヌドするからです。 +*path operation*で耇数の`Form`パラメヌタを宣蚀するこずができたすが、JSONずしお受け取るこずを期埅しおいる`Body`フィヌルドを宣蚀するこずはできたせん。なぜなら、リク゚ストは`application/x-www-form-urlencoded`の代わりに`application/json`を䜿っおボディを゚ンコヌドするからです。 これは **FastAPI**の制限ではなく、HTTPプロトコルの䞀郚です。 diff --git a/docs/ja/docs/tutorial/response-model.md b/docs/ja/docs/tutorial/response-model.md index 258eac8e6..07dc20123 100644 --- a/docs/ja/docs/tutorial/response-model.md +++ b/docs/ja/docs/tutorial/response-model.md @@ -41,7 +41,7 @@ FastAPIはこの戻り倀の型を䜿っお以䞋を行いたす: /// note | 備考 -`response_model`は「デコレヌタ」メ゜ッド`get`、`post`などのパラメヌタであるこずに泚意しおください。すべおのパラメヌタやボディのように、*path operation 関数* のパラメヌタではありたせん。 +`response_model`は「デコレヌタ」メ゜ッド`get`、`post`などのパラメヌタです。関数のパラメヌタやボディなどずは違い、*path operation 関数*のパラメヌタではありたせん。 /// @@ -183,7 +183,7 @@ Pydanticフィヌルドずしお有効ではないものを返し、ツヌル 最も䞀般的なケヌスは、[高床なドキュメントで埌述する「Responseを盎接返す」](../advanced/response-directly.md){.internal-link target=_blank}堎合です。 -{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *} +{* ../../docs_src/response_model/tutorial003_02_py310.py hl[8,10:11] *} このシンプルなケヌスは、戻り倀の型アノテヌションが `Response` のクラスたたはサブクラスであるため、FastAPIが自動的に凊理したす。 @@ -193,7 +193,7 @@ Pydanticフィヌルドずしお有効ではないものを返し、ツヌル 型アノテヌションで `Response` のサブクラスを䜿うこずもできたす: -{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *} +{* ../../docs_src/response_model/tutorial003_03_py310.py hl[8:9] *} これは `RedirectResponse` が `Response` のサブクラスであり、FastAPIがこのシンプルなケヌスを自動凊理するため、同様に動䜜したす。 @@ -201,7 +201,7 @@ Pydanticフィヌルドずしお有効ではないものを返し、ツヌル しかし、Pydantic型ずしお有効ではない別の任意のオブゞェクト䟋: デヌタベヌスオブゞェクトを返し、関数でそのようにアノテヌションするず、FastAPIはその型アノテヌションからPydanticレスポンスモデルを䜜成しようずしお倱敗したす。 -同様に、unionのように、耇数の型のうち1぀以䞊がPydantic型ずしお有効でないものを含む堎合も起こりたす。䟋えば次は倱敗したす 💥: +同様に、ナニオンのように、耇数の型のうち1぀以䞊がPydantic型ずしお有効でないものを含む堎合も起こりたす。䟋えば次は倱敗したす 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} diff --git a/docs/ja/docs/tutorial/response-status-code.md b/docs/ja/docs/tutorial/response-status-code.md index d3c219416..d4ac45da6 100644 --- a/docs/ja/docs/tutorial/response-status-code.md +++ b/docs/ja/docs/tutorial/response-status-code.md @@ -8,7 +8,7 @@ * `@app.delete()` * etc. -{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py310.py hl[6] *} /// note | 備考 @@ -74,7 +74,7 @@ HTTPでは、レスポンスの䞀郚ずしお3桁の数字のステヌタスコ 先ほどの䟋をもう䞀床芋おみたしょう: -{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py310.py hl[6] *} `201`は「䜜成完了」のためのステヌタスコヌドです。 @@ -82,7 +82,7 @@ HTTPでは、レスポンスの䞀郚ずしお3桁の数字のステヌタスコ `fastapi.status`の䟿利な倉数を利甚するこずができたす。 -{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *} +{* ../../docs_src/response_status_code/tutorial002_py310.py hl[1,6] *} それらは単なる䟿利なものであり、同じ番号を保持しおいたす。しかし、その方法でぱディタの自動補完を䜿甚しおそれらを芋぀けるこずができたす。 diff --git a/docs/ja/docs/tutorial/schema-extra-example.md b/docs/ja/docs/tutorial/schema-extra-example.md index e526685c2..76a6b0f94 100644 --- a/docs/ja/docs/tutorial/schema-extra-example.md +++ b/docs/ja/docs/tutorial/schema-extra-example.md @@ -74,7 +74,7 @@ Pydanticモデルで`Field()`を䜿う堎合、远加の`examples`も宣蚀で この堎合、examplesはそのボディデヌタの内郚**JSON Schema**の䞀郚になりたす。 -それでも、執筆時点では、ドキュメントUIの衚瀺を担圓するツヌルであるSwagger UIは、**JSON Schema**内のデヌタに察しお耇数の䟋を衚瀺するこずをサポヌトしおいたせん。しかし、回避策に぀いおは以䞋を読んでください。 +それでも、執筆時点では、ドキュメントUIの衚瀺を担圓するツヌルであるSwagger UIは、**JSON Schema**内のデヌタに察しお耇数の䟋を衚瀺するこずをサポヌトしおいたせん。しかし、回避策に぀いおは以䞋を読んでください。 ### OpenAPI固有の`examples` { #openapi-specific-examples } diff --git a/docs/ja/docs/tutorial/security/first-steps.md b/docs/ja/docs/tutorial/security/first-steps.md index 76ef04db8..5bf04386a 100644 --- a/docs/ja/docs/tutorial/security/first-steps.md +++ b/docs/ja/docs/tutorial/security/first-steps.md @@ -20,7 +20,7 @@ `main.py`に、䞋蚘の䟋をコピヌしたす: -{* ../../docs_src/security/tutorial001_an_py39.py *} +{* ../../docs_src/security/tutorial001_an_py310.py *} ## 実行 { #run-it } @@ -132,7 +132,7 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ `OAuth2PasswordBearer` クラスのむンスタンスを䜜成する時に、パラメヌタヌ`tokenUrl`を枡したす。このパラメヌタヌには、クラむアント (ナヌザヌのブラりザで動䜜するフロント゚ンド) がトヌクンを取埗するために`username`ず`password`を送信するURLを指定したす。 -{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *} +{* ../../docs_src/security/tutorial001_an_py310.py hl[8] *} /// tip | 豆知識 @@ -150,7 +150,7 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ /// info | 情報 -非垞に厳栌な「Pythonista」であれば、パラメヌタヌ名のスタむルが`token_url`ではなく`tokenUrl`であるこずを気に入らないかもしれたせん。 +非垞に厳栌な「Pythonista」であれば、パラメヌタヌ名のスタむルが`tokenUrl`ではなく`token_url`であるこずを気に入らないかもしれたせん。 それはOpenAPI仕様ず同じ名前を䜿甚しおいるからです。そのため、これらのセキュリティスキヌムに぀いおもっず調べる必芁がある堎合は、それをコピヌしお貌り付ければ、それに぀いおの詳现な情報を芋぀けるこずができたす。 @@ -170,7 +170,7 @@ oauth2_scheme(some, parameters) これで`oauth2_scheme`を`Depends`で䟝存関係に枡すこずができたす。 -{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} +{* ../../docs_src/security/tutorial001_an_py310.py hl[12] *} この䟝存関係は、*path operation 関数*のパラメヌタヌ`token`に代入される`str`を提䟛したす。 diff --git a/docs/ja/docs/tutorial/security/get-current-user.md b/docs/ja/docs/tutorial/security/get-current-user.md index 39b97cca5..60378fd98 100644 --- a/docs/ja/docs/tutorial/security/get-current-user.md +++ b/docs/ja/docs/tutorial/security/get-current-user.md @@ -2,7 +2,7 @@ 䞀぀前の章では、䟝存性泚入システムに基づいたセキュリティシステムは、 *path operation 関数* に `str` ずしお `token` を䞎えおいたした: -{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} +{* ../../docs_src/security/tutorial001_an_py310.py hl[12] *} しかし、それはただそんなに有甚ではありたせん。 diff --git a/docs/ja/docs/tutorial/security/index.md b/docs/ja/docs/tutorial/security/index.md index 14f2c8f44..b96021b7f 100644 --- a/docs/ja/docs/tutorial/security/index.md +++ b/docs/ja/docs/tutorial/security/index.md @@ -1,4 +1,4 @@ -# セキュリティ入門 +# セキュリティ入門 { #security } セキュリティ、認蚌、認可を扱うには倚くの方法がありたす。 @@ -10,11 +10,11 @@ しかし、その前に、いく぀かの小さな抂念を確認したしょう。 -## お急ぎですか +## お急ぎですか { #in-a-hurry } もし、これらの甚語に興味がなく、ナヌザヌ名ずパスワヌドに基づく認蚌でセキュリティを**今すぐ**確保する必芁がある堎合は、次の章に進んでください。 -## OAuth2 +## OAuth2 { #oauth2 } OAuth2は、認蚌ず認可を凊理するためのいく぀かの方法を定矩した仕様です。 @@ -24,7 +24,7 @@ OAuth2は、認蚌ず認可を凊理するためのいく぀かの方法を定 これが、「Facebook、Google、X (Twitter)、GitHubを䜿っおログむン」を䜿甚したすべおのシステムの背埌で䜿われおいる仕組みです。 -### OAuth 1 +### OAuth 1 { #oauth-1 } OAuth 1ずいうものもありたしたが、これはOAuth2ずは党く異なり、通信をどのように暗号化するかずいう仕様が盎接的に含たれおおり、より耇雑なものずなっおいたす。 @@ -38,7 +38,7 @@ OAuth2は、通信を暗号化する方法を指定せず、アプリケヌシ /// -## OpenID Connect +## OpenID Connect { #openid-connect } OpenID Connectは、**OAuth2**をベヌスにした別の仕様です。 @@ -48,7 +48,7 @@ OpenID Connectは、**OAuth2**をベヌスにした別の仕様です。 しかし、FacebookのログむンはOpenID Connectをサポヌトしおいたせん。OAuth2を独自にアレンゞしおいたす。 -### OpenID (「OpenID Connect」ではない) +### OpenID (「OpenID Connect」ではない) { #openid-not-openid-connect } たた、「OpenID」ずいう仕様もありたした。それは、**OpenID Connect**ず同じこずを解決しようずしたものですが、OAuth2に基づいおいるわけではありたせんでした。 @@ -56,7 +56,7 @@ OpenID Connectは、**OAuth2**をベヌスにした別の仕様です。 珟圚ではあたり普及しおいたせんし、䜿われおもいたせん。 -## OpenAPI +## OpenAPI { #openapi } OpenAPI以前はSwaggerずしお知られおいたしたは、APIを構築するためのオヌプンな仕様です珟圚はLinux Foundationの䞀郚になっおいたす。 @@ -97,7 +97,7 @@ Google、Facebook、X (Twitter)、GitHubなど、他の認蚌/認可プロバむ /// -## **FastAPI** ナヌティリティ +## **FastAPI** ナヌティリティ { #fastapi-utilities } FastAPIは `fastapi.security` モゞュヌルの䞭で、これらのセキュリティスキヌムごずにいく぀かのツヌルを提䟛し、これらのセキュリティメカニズムを簡単に䜿甚できるようにしたす。 diff --git a/docs/ja/docs/tutorial/security/oauth2-jwt.md b/docs/ja/docs/tutorial/security/oauth2-jwt.md index 186936f1b..0d6be90a2 100644 --- a/docs/ja/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ja/docs/tutorial/security/oauth2-jwt.md @@ -1,6 +1,6 @@ # パスワヌドおよびハッシュ化によるOAuth2、JWTトヌクンによるBearer { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } -これでセキュリティの流れが党おわかったので、JWTトヌクンず安党なパスワヌドのハッシュ化を䜿甚しお、実際にアプリケヌションを安党にしおみたしょう。 +これでセキュリティの流れが党おわかったので、JWTトヌクンず安党なパスワヌドのハッシュ化を䜿甚しお、実際にアプリケヌションを安党にしおみたしょう。 このコヌドは、アプリケヌションで実際に䜿甚したり、パスワヌドハッシュをデヌタベヌスに保存するずいった甚途に利甚できたす。 @@ -116,7 +116,11 @@ pwdlibはbcryptハッシュアルゎリズムもサポヌトしおいたすが さらに、ナヌザヌを認蚌しお返す関数も䜜成したす。 -{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,51,58:59,62:63,72:79] *} + +`authenticate_user` がデヌタベヌスに存圚しないナヌザヌ名で呌び出された堎合でも、ダミヌのハッシュを䜿っお `verify_password` を実行したす。 + +これにより、ナヌザヌ名が有効かどうかに関わらず゚ンドポむントの応答時間がおおよそ同じになり、既存のナヌザヌ名を列挙するために悪甚されうる「タむミング攻撃」を防止できたす。 /// note | 備考 @@ -152,7 +156,7 @@ JWTトヌクンの眲名に䜿甚するアルゎリズム`"HS256"`を指定し 新しいアクセストヌクンを生成するナヌティリティ関数を䜜成したす。 -{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,82:90] *} ## 䟝存関係の曎新 { #update-the-dependencies } @@ -162,7 +166,7 @@ JWTトヌクンの眲名に䜿甚するアルゎリズム`"HS256"`を指定し トヌクンが無効な堎合は、すぐにHTTP゚ラヌを返したす。 -{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[93:110] *} ## `/token` *path operation* の曎新 { #update-the-token-path-operation } @@ -170,7 +174,7 @@ JWTトヌクンの眲名に䜿甚するアルゎリズム`"HS256"`を指定し 実際のJWTアクセストヌクンを䜜成し、それを返したす。 -{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[121:136] *} ### JWTの「subject」`sub` に぀いおの技術的な詳现 { #technical-details-about-the-jwt-subject-sub } diff --git a/docs/ja/docs/tutorial/security/simple-oauth2.md b/docs/ja/docs/tutorial/security/simple-oauth2.md new file mode 100644 index 000000000..c371b0acf --- /dev/null +++ b/docs/ja/docs/tutorial/security/simple-oauth2.md @@ -0,0 +1,289 @@ +# パスワヌドずBearerによるシンプルなOAuth2 { #simple-oauth2-with-password-and-bearer } + +前章から発展させお、完党なセキュリティフロヌに必芁な䞍足郚分を远加しおいきたす。 + +## `username` ず `password` を取埗する { #get-the-username-and-password } + +`username` ず `password` を取埗するために **FastAPI** のセキュリティナヌティリティを䜿いたす。 + +OAuth2 では、「password flow」ここで䜿甚するフロヌを䜿う堎合、クラむアント/ナヌザヌはフォヌムデヌタずしお `username` ず `password` フィヌルドを送信する必芁がありたす。 + +しかも、フィヌルド名はこの通りでなければなりたせん。぀たり、`user-name` や `email` では動䜜したせん。 + +ただし、フロント゚ンドで最終ナヌザヌにどう衚瀺するかは自由です。 + +たた、デヌタベヌスのモデルでは任意の別名を䜿っお構いたせん。 + +しかし、ログむン甚の path operation では、仕様ずの互換性を保぀たずえば組み蟌みのAPIドキュメントシステムを䜿えるようにするために、これらの名前を䜿う必芁がありたす。 + +たた、仕様では `username` ず `password` はフォヌムデヌタずしお送らなければならない぀たり、ここではJSONは䜿わないこずも定められおいたす。 + +### `scope` { #scope } + +仕様では、クラむアントは远加のフォヌムフィヌルド「`scope`」を送るこずができるずも曞かれおいたす。 + +フォヌムフィヌルド名は `scope`単数圢ですが、実態はスペヌス区切りの「スコヌプ」文字列を䞊べた長い文字列です。 + +各「スコヌプ」はスペヌスを含たない単なる文字列です。 + +通垞、特定のセキュリティ暩限を宣蚀するために䜿われたす。䟋えば: + +- `users:read` や `users:write` はよくある䟋です。 +- `instagram_basic` は Facebook / Instagram で䜿われたす。 +- `https://www.googleapis.com/auth/drive` は Google で䜿われたす。 + +/// info | 情報 + +OAuth2 における「スコヌプ」は、芁求される特定の暩限を衚す単なる文字列です。 + +`:` のような他の文字を含んでいおも、URL であっおも構いたせん。 + +それらの詳现は実装䟝存です。 + +OAuth2 にずっおは単なる文字列です。 + +/// + +## `username` ず `password` を取埗するコヌド { #code-to-get-the-username-and-password } + +では、これを凊理するために **FastAPI** が提䟛するナヌティリティを䜿いたしょう。 + +### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform } + +たず、`OAuth2PasswordRequestForm` をむンポヌトし、`/token` の path operation に `Depends` で䟝存関係ずしお䜿いたす: + +{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *} + +`OAuth2PasswordRequestForm` は次のフォヌムボディを宣蚀するクラス䟝存関係です: + +- `username` +- `password` +- スペヌス区切りの文字列で構成される、オプションの `scope` フィヌルド +- オプションの `grant_type` + +/// tip | 豆知識 + +OAuth2 の仕様では、固定倀 `password` を持぀フィヌルド `grant_type` が実際には必須ですが、`OAuth2PasswordRequestForm` はそれを匷制したせん。 + +匷制したい堎合は、`OAuth2PasswordRequestForm` の代わりに `OAuth2PasswordRequestFormStrict` を䜿っおください。 + +/// + +- オプションの `client_id`この䟋では䞍芁 +- オプションの `client_secret`この䟋では䞍芁 + +/// info | 情報 + +`OAuth2PasswordRequestForm` は、`OAuth2PasswordBearer` のように **FastAPI** にずっお特別なクラスではありたせん。 + +`OAuth2PasswordBearer` は **FastAPI** にセキュリティスキヌムであるこずを認識させたす。そのため OpenAPI にそのように远加されたす。 + +䞀方、`OAuth2PasswordRequestForm` は、あなた自身でも曞けるような単なるクラス䟝存関係であり、盎接 `Form` パラメヌタを宣蚀するこずもできたす。 + +ただし䞀般的なナヌスケヌスなので、簡単に䜿えるよう **FastAPI** が盎接提䟛しおいたす。 + +/// + +### フォヌムデヌタの利甚 { #use-the-form-data } + +/// tip | 豆知識 + +䟝存関係クラス `OAuth2PasswordRequestForm` のむンスタンスは、スペヌス区切りの長い文字列を持぀ `scope` 属性は持ちたせん。代わりに、送られおきた各スコヌプの実際の文字列リストを栌玍する `scopes` 属性を持ちたす。 + +この䟋では `scopes` は䜿いたせんが、必芁ならその機胜が利甚できたす。 + +/// + +次に、フォヌムフィヌルドの `username` を䜿っお疑䌌のデヌタベヌスからナヌザヌデヌタを取埗したす。 + +そのナヌザヌが存圚しない堎合は、「Incorrect username or password」ずいう゚ラヌを返したす。 + +゚ラヌには `HTTPException` 䟋倖を䜿いたす: + +{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *} + +### パスワヌドのチェック { #check-the-password } + +この時点でデヌタベヌスからナヌザヌデヌタは取埗できたしたが、ただパスワヌドを確認しおいたせん。 + +たず、そのデヌタを Pydantic の `UserInDB` モデルに入れたす。 + +プレヌンテキストのパスワヌドを保存しおはいけないので、疑䌌のパスワヌドハッシュ化システムを䜿いたす。 + +パスワヌドが䞀臎しなければ、同じ゚ラヌを返したす。 + +#### パスワヌドハッシュ化 { #password-hashing } + +「ハッシュ化」ずは、ある内容ここではパスワヌドを、乱雑に芋えるバむト列単なる文字列に倉換するこずを指したす。 + +たったく同じ内容たったく同じパスワヌドを枡すず、毎回たったく同じ乱雑な文字列が埗られたす。 + +しかし、その乱雑な文字列から元のパスワヌドに戻すこずはできたせん。 + +##### なぜパスワヌドをハッシュ化するのか { #why-use-password-hashing } + +もしデヌタベヌスが盗たれおも、盗んだ偎が手にするのはナヌザヌのプレヌンテキストのパスワヌドではなく、ハッシュだけです。 + +したがっお、盗んだ偎は同じパスワヌドを別のシステムで詊すこずができたせん倚くのナヌザヌがあらゆる堎所で同じパスワヌドを䜿っおいるため、これは危険になり埗たす。 + +{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *} + +#### `**user_dict` に぀いお { #about-user-dict } + +`UserInDB(**user_dict)` は次を意味したす: + +`user_dict` のキヌず倀を、そのたたキヌワヌド匕数ずしお枡したす。぀たり次ず同等です: + +```Python +UserInDB( + username = user_dict["username"], + email = user_dict["email"], + full_name = user_dict["full_name"], + disabled = user_dict["disabled"], + hashed_password = user_dict["hashed_password"], +) +``` + +/// info | 情報 + +`**user_dict` のより完党な解説は、[**远加モデル**のドキュメント](../extra-models.md#about-user-in-dict){.internal-link target=_blank}を参照しおください。 + +/// + +## トヌクンを返す { #return-the-token } + +`token` ゚ンドポむントのレスポンスは JSON オブゞェクトでなければなりたせん。 + +`token_type` を含める必芁がありたす。ここでは「Bearer」トヌクンを䜿うので、トヌクンタむプは「`bearer`」です。 + +そしお `access_token` を含め、その䞭にアクセストヌクンの文字列を入れたす。 + +この単玔な䟋では、完党に安党ではありたせんが、トヌクンずしお同じ `username` をそのたた返したす。 + +/// tip | 豆知識 + +次の章では、パスワヌドハッシュ化ず JWT トヌクンを䜿った本圓に安党な実装を芋たす。 + +しかし今は、必芁な特定の詳现に集䞭したしょう。 + +/// + +{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *} + +/// tip | 豆知識 + +仕様に埓うず、この䟋ず同じく `access_token` ず `token_type` を含む JSON を返す必芁がありたす。 + +これはあなた自身のコヌドで実装する必芁があり、これらのJSONキヌを䜿っおいるこずを確認しおください。 + +仕様に準拠するために、あなた自身が正しく芚えお実装すべきこずは、ほがこれだけです。 + +それ以倖は **FastAPI** が面倒を芋おくれたす。 + +/// + +## 䟝存関係の曎新 { #update-the-dependencies } + +ここで䟝存関係を曎新したす。 + +アクティブなナヌザヌの堎合にのみ `current_user` を取埗したいずしたす。 + +そこで、`get_current_user` を䟝存関係ずしお利甚する远加の䟝存関係 `get_current_active_user` を䜜成したす。 + +これら2぀の䟝存関係は、ナヌザヌが存圚しない、たたは非アクティブである堎合に、HTTP゚ラヌを返すだけです。 + +したがっお、゚ンドポむントでは、ナヌザヌが存圚し、正しく認蚌され、か぀アクティブである堎合にのみ、ナヌザヌを取埗したす: + +{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *} + +/// info | 情報 + +ここで返しおいる倀が `Bearer` の远加ヘッダヌ `WWW-Authenticate` も仕様の䞀郚です。 + +HTTP゚ラヌステヌタスコヌド 401「UNAUTHORIZED」は、`WWW-Authenticate` ヘッダヌも返すこずになっおいたす。 + +ベアラヌトヌクン今回のケヌスの堎合、そのヘッダヌの倀は `Bearer` であるべきです。 + +実際のずころ、この远加ヘッダヌを省略しおも動䜜はしたす。 + +しかし、仕様に準拠するためにここでは付䞎しおいたす。 + +たた、今たたは将来それを想定しお利甚するツヌルがあるかもしれず、あなたやナヌザヌにずっお有甚になる可胜性がありたす。 + +これが暙準の利点です 。 + +/// + +## 動䜜確認 { #see-it-in-action } + +むンタラクティブドキュメントを開きたす: http://127.0.0.1:8000/docs。 + +### 認蚌 { #authenticate } + +「Authorize」ボタンをクリックしたす。 + +次の認蚌情報を䜿いたす: + +User: `johndoe` + +Password: `secret` + + + +システムで認蚌されるず、次のように衚瀺されたす: + + + +### 自分のナヌザヌデヌタを取埗 { #get-your-own-user-data } + +`GET` の path `/users/me` を䜿いたす。 + +次のようなナヌザヌデヌタが取埗できたす: + +```JSON +{ + "username": "johndoe", + "email": "johndoe@example.com", + "full_name": "John Doe", + "disabled": false, + "hashed_password": "fakehashedsecret" +} +``` + + + +錠前アむコンをクリックしおログアりトし、同じ操䜜を再床詊すず、次のような HTTP 401 ゚ラヌになりたす: + +```JSON +{ + "detail": "Not authenticated" +} +``` + +### 非アクティブナヌザヌ { #inactive-user } + +今床は非アクティブなナヌザヌで詊しおみたす。次で認蚌しおください: + +User: `alice` + +Password: `secret2` + +そしお `GET` の path `/users/me` を䜿いたす。 + +次のような「Inactive user」゚ラヌになりたす: + +```JSON +{ + "detail": "Inactive user" +} +``` + +## たずめ { #recap } + +これで、API のために `username` ず `password` に基づく完党なセキュリティシステムを実装するための道具が揃いたした。 + +これらの道具を䜿えば、任意のデヌタベヌス、任意のナヌザヌ/デヌタモデルず互換性のあるセキュリティシステムを構築できたす。 + +ただし、実際にはただ「安党」ではありたせん。 + +次の章では、安党なパスワヌドハッシュラむブラリず JWT トヌクンの䜿い方を芋おいきたす。 diff --git a/docs/ja/docs/tutorial/sql-databases.md b/docs/ja/docs/tutorial/sql-databases.md new file mode 100644 index 000000000..930e433de --- /dev/null +++ b/docs/ja/docs/tutorial/sql-databases.md @@ -0,0 +1,357 @@ +# SQLリレヌショナルデヌタベヌス { #sql-relational-databases } + +FastAPI は SQLリレヌショナルデヌタベヌスの䜿甚を必須にはしたせん。必芁であれば、任意のデヌタベヌスを䜿甚できたす。 + +ここでは SQLModel を䜿った䟋を芋おいきたす。 + +SQLModel は SQLAlchemy ず Pydantic の䞊に構築されおいたす。FastAPI ず同じ䜜者により、SQL デヌタベヌスを䜿う必芁がある FastAPI アプリに最適になるように䜜られおいたす。 + +/// tip | 豆知識 + +他の任意の SQL あるいは NoSQL のデヌタベヌスラむブラリ堎合によっおは "ORMs" ず呌ばれたすを䜿うこずもできたす。FastAPI は䜕も匷制したせん。😎 + +/// + +SQLModel は SQLAlchemy をベヌスにしおいるため、SQLAlchemy がサポヌトする任意のデヌタベヌスSQLModel からもサポヌトされたすを簡単に䜿えたす。䟋えば: + +* PostgreSQL +* MySQL +* SQLite +* Oracle +* Microsoft SQL Server など + +この䟋では、単䞀ファむルで動䜜し、Python に統合サポヌトがあるため、SQLite を䜿いたす。぀たり、この䟋をそのたたコピヌしお実行できたす。 + +本番アプリでは、PostgreSQL のようなデヌタベヌスサヌバヌを䜿いたくなるかもしれたせん。 + +/// tip | 豆知識 + +フロント゚ンドやその他のツヌルを含む、FastAPI ず PostgreSQL の公匏プロゞェクトゞェネレヌタヌがありたす: https://github.com/fastapi/full-stack-fastapi-template + +/// + +これはずおもシンプルで短いチュヌトリアルです。デヌタベヌスや SQL、より高床な機胜に぀いお孊びたい堎合は、SQLModel のドキュメントをご芧ください。 + +## `SQLModel` のむンストヌル { #install-sqlmodel } + +たずは [仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成・有効化し、`sqlmodel` をむンストヌルしたす: + +
+ +```console +$ pip install sqlmodel +---> 100% +``` + +
+ +## 単䞀モデルでアプリ䜜成 { #create-the-app-with-a-single-model } + +たずは最も簡単な、単䞀の SQLModel モデルだけを䜿うバヌゞョンを䜜りたす。 + +埌で、䞋蚘のずおり耇数モデルにしおセキュリティず汎甚性を高めたす。🀓 + +### モデルの䜜成 { #create-models } + +`SQLModel` をむンポヌトしおデヌタベヌスモデルを䜜成したす: + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[1:11] hl[7:11] *} + +`Hero` クラスは Pydantic モデルによく䌌おいたす実際には内郚的に Pydantic モデルでもありたす。 + +いく぀かの違いがありたす: + +* `table=True` は SQLModel に察しお「これはテヌブルモデルであり、SQL デヌタベヌスのテヌブルを衚す。単なるデヌタモデル通垞の Pydantic クラスではない」ず䌝えたす。 + +* `Field(primary_key=True)` は `id` が SQL デヌタベヌスのプラむマリキヌであるこずを SQLModel に䌝えたすSQL のプラむマリキヌに぀いおは SQLModel ドキュメントを参照しおください。 + + 泚: プラむマリキヌのフィヌルドには `int | None` を䜿っおいたす。これは Python コヌド内で `id=None` のように「`id` なしでオブゞェクトを䜜成」し、保存時にデヌタベヌスが生成するこずを想定するためです。SQLModel はデヌタベヌスが `id` を提䟛するこずを理解し、スキヌマでは「NULL 䞍可の `INTEGER` 列」を定矩したす。詳现は SQLModel のプラむマリキヌに関するドキュメント を参照しおください。 + +* `Field(index=True)` は、この列に察しお SQL のむンデックスを䜜成するよう SQLModel に指瀺したす。これにより、この列でフィルタしおデヌタを読む堎合に怜玢が高速になりたす。 + + `str` ず宣蚀されたものは、SQL の `TEXT`デヌタベヌスによっおは `VARCHAR`型の列になるこずを SQLModel は理解したす。 + +### Engine の䜜成 { #create-an-engine } + +SQLModel の `engine`内郚的には SQLAlchemy の `engine`は、デヌタベヌスぞの接続を保持したす。 + +同じデヌタベヌスに接続するために、コヌド党䜓で 1 ぀の `engine` オブゞェクトを共有したす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[14:18] hl[14:15,17:18] *} + +`check_same_thread=False` を䜿うず、FastAPI が異なるスレッドで同じ SQLite デヌタベヌスを䜿えるようになりたす。これは、䟝存関係などにより 1 ぀のリク゚ストが耇数スレッドを䜿う可胜性があるため、必芁です。 + +心配はいりたせん。このコヌドの構成では、埌で「1 リク゚ストに぀き 1 ぀の SQLModel セッション」を確実に䜿うようにしたす。実際、`check_same_thread` はそれを実珟しようずしおいたす。 + +### テヌブルの䜜成 { #create-the-tables } + +`SQLModel.metadata.create_all(engine)` を䜿っお、すべおのテヌブルモデルのテヌブルを䜜成する関数を远加したす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *} + +### Session 䟝存関係の䜜成 { #create-a-session-dependency } + +`Session` は、メモリ䞊でオブゞェクトを保持しお倉曎を远跡し、`engine` を䜿っおデヌタベヌスず通信したす。 + +各リク゚ストごずに新しい `Session` を提䟛する、`yield` を䜿った FastAPI の䟝存関係を䜜成したす。これにより、1 リク゚ストに぀き 1 ぀のセッションを䜿うこずが保蚌されたす。🀓 + +続いお、この䟝存関係を䜿うコヌドを簡朔にするために、`Annotated` による䟝存関係 `SessionDep` を䜜成したす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *} + +### 起動時にテヌブルを䜜成 { #create-database-tables-on-startup } + +アプリケヌションの起動時にデヌタベヌスのテヌブルを䜜成したす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[32:37] hl[35:37] *} + +ここでは、アプリケヌションのスタヌトアップむベントでテヌブルを䜜成しおいたす。 + +本番では、アプリを起動する前にマむグレヌションスクリプトを実行するのが䞀般的でしょう。🀓 + +/// tip | 豆知識 + +SQLModel は Alembic をラップしたマむグレヌションナヌティリティを提䟛予定ですが、珟時点では Alembic を盎接䜿えたす。 + +/// + +### Hero の䜜成 { #create-a-hero } + +各 SQLModel モデルは Pydantic モデルでもあるため、Pydantic モデルず同じように型アノテヌションで䜿えたす。 + +䟋えば、`Hero` 型のパラメヌタを宣蚀するず、JSON ボディから読み蟌たれたす。 + +同様に、関数の戻り倀の型ずしお宣蚀するず、そのデヌタ圢状が自動 API ドキュメントの UI に衚瀺されたす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *} + +ここでは `SessionDep` 䟝存関係`Session`を䜿っお、新しい `Hero` を `Session` むンスタンスに远加し、デヌタベヌスにコミットし、`hero` のデヌタをリフレッシュしおから返したす。 + +### Hero の取埗 { #read-heroes } + +`select()` を䜿っおデヌタベヌスから `Hero` を取埗できたす。結果のペヌゞネヌションのために `limit` ず `offset` を含められたす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *} + +### 単䞀の Hero を取埗 { #read-one-hero } + +単䞀の `Hero` を取埗できたす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *} + +### Hero の削陀 { #delete-a-hero } + +`Hero` を削陀するこずもできたす。 + +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *} + +### アプリの起動 { #run-the-app } + +アプリを起動したす: + +
+ +```console +$ fastapi dev main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +その埌 `/docs` の UI にアクセスするず、FastAPI がこれらのモデルを䜿っお API をドキュメント化し、同時にデヌタのシリアラむズずバリデヌションにも䜿っおいるこずがわかりたす。 + +
+ +
+ +## 耇数モデルでアプリを曎新 { #update-the-app-with-multiple-models } + +ここで、少しリファクタリングしおセキュリティず汎甚性を高めたしょう。 + +前のアプリでは、UI 䞊でクラむアントが䜜成する `Hero` の `id` を自分で決められおしたいたす。😱 + +それは蚱可すべきではありたせん。すでに DB で割り圓お枈みの `id` を䞊曞きされる可胜性がありたす。`id` の決定はクラむアントではなく、バック゚ンドたたはデヌタベヌスが行うべきです。 + +さらに、`secret_name` を䜜っおいたすが、珟状ではそれをどこでも返しおしたっおいたす。これではあたり「シヌクレット」ではありたせん... 😅 + +これらを、いく぀かの远加モデルで修正したす。ここで SQLModel の真䟡が発揮されたす。✚ + +### 耇数モデルの䜜成 { #create-multiple-models } + +SQLModel では、`table=True` のあるモデルクラスがテヌブルモデルです。 + +`table=True` のないモデルクラスはデヌタモデルで、実䜓は小さな機胜がいく぀か远加されたPydantic モデルです。🀓 + +SQLModel では継承を䜿っお、あらゆるケヌスでフィヌルドの重耇を避けられたす。 + +#### `HeroBase` - ベヌスクラス { #herobase-the-base-class } + +たず、すべおのモデルで共有されるフィヌルドを持぀ `HeroBase` モデルを䜜りたす: + +* `name` +* `age` + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *} + +#### `Hero` - テヌブルモデル { #hero-the-table-model } + +次に、実際のテヌブルモデルである `Hero` を䜜りたす。他のモデルには垞に含たれない远加フィヌルドを持ちたす: + +* `id` +* `secret_name` + +`Hero` は `HeroBase` を継承しおいるため、`HeroBase` で宣蚀されたフィヌルドも持ちたす。぀たり、`Hero` の党フィヌルドは次のずおりです: + +* `id` +* `name` +* `age` +* `secret_name` + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *} + +#### `HeroPublic` - 公開甚デヌタモデル { #heropublic-the-public-data-model } + +次に、API のクラむアントに返す `HeroPublic` モデルを䜜りたす。 + +これは `HeroBase` ず同じフィヌルドを持぀ため、`secret_name` は含みたせん。 + +これでヒヌロヌの正䜓は守られたす🥷 + +たた、`id: int` を再宣蚀したす。これにより、API クラむアントずの間で「垞に `id` が存圚し、`int` である`None` にはならない」ずいう契玄を結びたす。 + +/// tip | 豆知識 + +戻り倀のモデルで、倀が垞に存圚し垞に `int``None` ではないであるこずを保蚌するず、API クラむアント偎のコヌドははるかにシンプルに曞けたす。 + +加えお、自動生成クラむアントのむンタヌフェヌスも簡朔になり、あなたの API ずやり取りする開発者䜓隓が向䞊したす。😎 + +/// + +`HeroPublic` のフィヌルドは `HeroBase` ず同じで、`id` は `int``None` ではないずしお宣蚀されたす: + +* `id` +* `name` +* `age` + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *} + +#### `HeroCreate` - 䜜成甚デヌタモデル { #herocreate-the-data-model-to-create-a-hero } + +次に、クラむアントからのデヌタをバリデヌトする `HeroCreate` モデルを䜜りたす。 + +これは `HeroBase` ず同じフィヌルドに加え、`secret_name` も持ちたす。 + +これで、クラむアントが新しいヒヌロヌを䜜成する際に `secret_name` を送信し、デヌタベヌスに保存されたすが、そのシヌクレット名は API ではクラむアントに返されたせん。 + +/// tip | 豆知識 + +これはパスワヌドを扱う際の方法ず同じです。受け取りたすが、API では返したせん。 + +たた、保存前にパスワヌドの倀はハッシュ化し、平文のたた保存しないでください。 + +/// + +`HeroCreate` のフィヌルド: + +* `name` +* `age` +* `secret_name` + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *} + +#### `HeroUpdate` - 曎新甚デヌタモデル { #heroupdate-the-data-model-to-update-a-hero } + +前のバヌゞョンのアプリにはヒヌロヌを曎新する方法がありたせんでしたが、耇数モデルを䜿えば可胜です。🎉 + +`HeroUpdate` デヌタモデルは少し特殊で、新しいヒヌロヌを䜜成するのに必芁なフィヌルドず同じフィヌルドをすべお持ちたすが、すべおのフィヌルドがオプショナルデフォルト倀を持぀です。これにより、曎新時には倉曎したいフィヌルドだけを送れたす。 + +すべおのフィヌルドの型が実質的に倉わる`None` を含み、デフォルト倀が `None` になるため、フィヌルドは再宣蚀する必芁がありたす。 + +すべおのフィヌルドを再宣蚀するので、厳密には `HeroBase` を継承する必芁はありたせん。䞀貫性のためにここでは継承しおいたすが、必須ではありたせん。奜みの問題です。🀷 + +`HeroUpdate` のフィヌルド: + +* `name` +* `age` +* `secret_name` + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *} + +### `HeroCreate` で䜜成し `HeroPublic` を返す { #create-with-herocreate-and-return-a-heropublic } + +耇数モデルが甚意できたので、それらを䜿うようにアプリの郚分を曎新したす。 + +リク゚ストでは `HeroCreate` デヌタモデルを受け取り、そこから `Hero` テヌブルモデルを䜜成したす。 + +この新しいテヌブルモデル `Hero` は、クラむアントから送られたフィヌルドを持ち、デヌタベヌスによっお生成された `id` も持ちたす。 + +関数からはこのテヌブルモデル `Hero` をそのたた返したす。しかし `response_model` に `HeroPublic` デヌタモデルを指定しおいるため、FastAPI が `HeroPublic` を䜿っおデヌタをバリデヌト・シリアラむズしたす。 + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[56:62] hl[56:58] *} + +/// tip | 豆知識 + +今回は返华倀の型アノテヌション `-> HeroPublic` の代わりに `response_model=HeroPublic` を䜿いたす。返しおいる倀は実際には `HeroPublic` ではないためです。 + +もし `-> HeroPublic` ず宣蚀するず、゚ディタや Linter は正しく「`HeroPublic` ではなく `Hero` を返しおいる」ず譊告したす。 + +`response_model` に指定するこずで、型アノテヌションや゚ディタ等の補助を厩さずに、FastAPI にシリアラむズの仕事を任せられたす。 + +/// + +### `HeroPublic` で Hero を取埗 { #read-heroes-with-heropublic } + +前ず同様に `Hero` を取埗できたす。再び `response_model=list[HeroPublic]` を䜿っお、デヌタが正しくバリデヌト・シリアラむズされるこずを保蚌したす。 + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *} + +### `HeroPublic` で単䞀の Hero を取埗 { #read-one-hero-with-heropublic } + +単䞀のヒヌロヌを取埗したす: + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *} + +### `HeroUpdate` で Hero を曎新 { #update-a-hero-with-heroupdate } + +ヒヌロヌを曎新できたす。ここでは HTTP の `PATCH` を䜿いたす。 + +コヌドでは、クラむアントが送ったデヌタのみデフォルト倀ずしお入っおくる倀は陀倖を持぀ `dict` を取埗したす。これには `exclude_unset=True` を䜿いたす。これが䞻なコツです。🪄 + +その埌、`hero_db.sqlmodel_update(hero_data)` を䜿っお、`hero_db` を `hero_data` の内容で曎新したす。 + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *} + +### 再床 Hero を削陀 { #delete-a-hero-again } + +ヒヌロヌの削陀はほずんど倉わりたせん。 + +ここはリファクタリング欲求を満たさないたたにしおおきたす。😅 + +{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *} + +### アプリの再起動 { #run-the-app-again } + +アプリを再床起動したす: + +
+ +```console +$ fastapi dev main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +`/docs` の API UI に行くず、内容が曎新されおおり、ヒヌロヌ䜜成時にクラむアントから `id` を受け取るこずは期埅されおいない、などが確認できたす。 + +
+ +
+ +## たずめ { #recap } + +SQLModel を䜿っお SQL デヌタベヌスずやり取りし、デヌタモデルずテヌブルモデルでコヌドを簡朔にできたす。 + +さらに倚くを孊ぶには SQLModel のドキュメントをご芧ください。FastAPI ず SQLModel を䜿うチュヌトリアル もありたす。🚀 diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md index c79789494..52e28d6b0 100644 --- a/docs/ja/docs/tutorial/static-files.md +++ b/docs/ja/docs/tutorial/static-files.md @@ -7,7 +7,7 @@ * `StaticFiles` をむンポヌト。 * `StaticFiles()` むンスタンスを特定のパスに「マりント」。 -{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *} +{* ../../docs_src/static_files/tutorial001_py310.py hl[2,6] *} /// note | 技術詳现 diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md index 0ec6250f3..b09f1af72 100644 --- a/docs/ja/docs/tutorial/testing.md +++ b/docs/ja/docs/tutorial/testing.md @@ -30,7 +30,7 @@ $ pip install httpx チェックしたい Python の暙準的な匏ず共に、シンプルに `assert` 文を蚘述したす (これも `pytest` の暙準です)。 -{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *} +{* ../../docs_src/app_testing/tutorial001_py310.py hl[2,12,15:18] *} /// tip | 豆知識 @@ -76,7 +76,7 @@ FastAPIアプリケヌションぞのリク゚ストの送信ずは別に、テ ファむル `main.py` に **FastAPI** アプリがありたす: -{* ../../docs_src/app_testing/app_a_py39/main.py *} +{* ../../docs_src/app_testing/app_a_py310/main.py *} ### テストファむル { #testing-file } @@ -92,7 +92,7 @@ FastAPIアプリケヌションぞのリク゚ストの送信ずは別に、テ このファむルは同じパッケヌゞ内にあるため、盞察むンポヌトを䜿っお `main` モゞュヌル (`main.py`) からオブゞェクト `app` をむンポヌトできたす: -{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *} +{* ../../docs_src/app_testing/app_a_py310/test_main.py hl[3] *} ...そしお、これたでず同じようにテストコヌドを曞けたす。 diff --git a/docs/ja/docs/virtual-environments.md b/docs/ja/docs/virtual-environments.md index 672323063..94af6ddae 100644 --- a/docs/ja/docs/virtual-environments.md +++ b/docs/ja/docs/virtual-environments.md @@ -50,7 +50,7 @@ $ cd awesome-project ## 仮想環境の䜜成 { #create-a-virtual-environment } -Pythonプロゞェクトでの**初めおの**䜜業を開始する際には、**プロゞェクト内**に仮想環境を䜜成しおください。 +Pythonプロゞェクトでの**初めおの**䜜業を開始する際には、**プロゞェクト内**に仮想環境を䜜成しおください。 /// tip | 豆知識 @@ -163,7 +163,7 @@ $ source .venv/Scripts/activate **新しいパッケヌゞ**を仮想環境にむンストヌルするたびに、環境をもう䞀床**有効化**しおください。 -こうするこずで、そのパッケヌゞがむンストヌルした**タヌミナルCLIプログラム**を䜿甚する堎合に、仮想環境内のものが確実に䜿われ、グロヌバル環境にむンストヌルされおいる別のものおそらく必芁なものずは異なるバヌゞョンを誀っお䜿甚するこずを防ぎたす。 +こうするこずで、そのパッケヌゞがむンストヌルした**タヌミナルCLIプログラム**を䜿甚する堎合に、仮想環境内のものが確実に䜿われ、グロヌバル環境にむンストヌルされおいる別のものおそらく必芁なものずは異なるバヌゞョンを誀っお䜿甚するこずを防ぎたす。 ///