mirror of
https://github.com/fastapi/fastapi.git
synced 2026-01-29 00:11:16 -05:00
Apply path operation suggestion to other files
This commit is contained in:
@@ -53,7 +53,7 @@
|
||||
**FastAPI** からHTMLを直接返す場合は、`HTMLResponse` を使います。
|
||||
|
||||
* `HTMLResponse` をインポートする。
|
||||
* *パスオペレーションデコレータ* のパラメータ `response_class` に `HTMLResponse` を渡す。
|
||||
* *path operation デコレータ* のパラメータ `response_class` に `HTMLResponse` を渡す。
|
||||
|
||||
{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *}
|
||||
|
||||
@@ -297,7 +297,7 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス
|
||||
|
||||
これを定義するパラメータは `default_response_class` です。
|
||||
|
||||
以下の例では、**FastAPI** はすべての*パスオペレーション*で、`JSONResponse` の代わりに `ORJSONResponse` をデフォルトとして使います。
|
||||
以下の例では、**FastAPI** はすべての*path operation*で、`JSONResponse` の代わりに `ORJSONResponse` をデフォルトとして使います。
|
||||
|
||||
{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *}
|
||||
|
||||
|
||||
@@ -149,7 +149,7 @@ FastAPIでWeb APIを構築する際に、コードにエラーがある場合、
|
||||
|
||||
しかしながら、**アプリケーション全体をクラッシュさせるようなコードを書いて**UvicornとPythonをクラッシュさせるようなケースもあるかもしれません。💥
|
||||
|
||||
それでも、ある箇所でエラーが発生したからといって、アプリケーションを停止させたままにしたくないでしょう。 少なくとも壊れていない*パスオペレーション*については、**実行し続けたい**はずです。
|
||||
それでも、ある箇所でエラーが発生したからといって、アプリケーションを停止させたままにしたくないでしょう。 少なくとも壊れていない*path operation*については、**実行し続けたい**はずです。
|
||||
|
||||
### クラッシュ後の再起動 { #restart-after-crash }
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ APIはほとんどの場合 **レスポンス** ボディを送信する必要
|
||||
|
||||
## パラメータとして宣言 { #declare-it-as-a-parameter }
|
||||
|
||||
*パスオペレーション* に追加するには、パスパラメータやクエリパラメータを宣言したのと同じ方法で宣言します:
|
||||
*path operation* に追加するには、パスパラメータやクエリパラメータを宣言したのと同じ方法で宣言します:
|
||||
|
||||
{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
|
||||
|
||||
@@ -82,7 +82,7 @@ APIはほとんどの場合 **レスポンス** ボディを送信する必要
|
||||
|
||||
<img src="/img/tutorial/body/image01.png">
|
||||
|
||||
また、それらが必要な各 *パスオペレーション* 内のAPIドキュメントでも使用されます:
|
||||
また、それらが必要な各 *path operation* 内のAPIドキュメントでも使用されます:
|
||||
|
||||
<img src="/img/tutorial/body/image02.png">
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
|
||||
**ブラウザがクッキーを処理し**ていますが、特別な方法で内部的に処理を行っているために、**JavaScript**からは簡単に操作**できない**ことに留意してください。
|
||||
|
||||
**APIドキュメントUI** `/docs` にアクセスすれば、*パスオペレーション*に関するクッキーの**ドキュメンテーション**を確認できます。
|
||||
**APIドキュメントUI** `/docs` にアクセスすれば、*path operation*に関するクッキーの**ドキュメンテーション**を確認できます。
|
||||
|
||||
しかし、たとえ**データを入力して**「Execute」をクリックしても、ドキュメントUIは**JavaScript**で動作しているためクッキーは送信されず、まるで値を入力しなかったかのような**エラー**メッセージが表示されます。
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
|
||||
**ブラウザがクッキーを**特殊な方法で裏側で扱うため、**JavaScript** から簡単には触れられないことを念頭に置いてください。
|
||||
|
||||
`/docs` の **API docs UI** に移動すると、*パスオペレーション* のクッキーに関する **documentation** を確認できます。
|
||||
`/docs` の **API docs UI** に移動すると、*path operation* のクッキーに関する **documentation** を確認できます。
|
||||
|
||||
しかし、データを **入力** して「Execute」をクリックしても、docs UI は **JavaScript** で動作するためクッキーは送信されず、値を何も書かなかったかのような **error** メッセージが表示されます。
|
||||
|
||||
|
||||
@@ -1,28 +1,28 @@
|
||||
# パスオペレーションデコレータの依存関係 { #dependencies-in-path-operation-decorators }
|
||||
# path operation デコレータの依存関係 { #dependencies-in-path-operation-decorators }
|
||||
|
||||
場合によっては、*パスオペレーション関数*の中で依存関係の戻り値を実際には必要としないことがあります。
|
||||
場合によっては、*path operation 関数*の中で依存関係の戻り値を実際には必要としないことがあります。
|
||||
|
||||
または、依存関係が値を返さない場合もあります。
|
||||
|
||||
しかし、それでも実行・解決される必要があります。
|
||||
|
||||
そのような場合、`Depends` で *パスオペレーション関数* のパラメータを宣言する代わりに、*パスオペレーションデコレータ*に `dependencies` の `list` を追加できます。
|
||||
そのような場合、`Depends` で *path operation 関数* のパラメータを宣言する代わりに、*path operation デコレータ*に `dependencies` の `list` を追加できます。
|
||||
|
||||
## *パスオペレーションデコレータ*に`dependencies`を追加 { #add-dependencies-to-the-path-operation-decorator }
|
||||
## *path operation デコレータ*に`dependencies`を追加 { #add-dependencies-to-the-path-operation-decorator }
|
||||
|
||||
*パスオペレーションデコレータ*はオプション引数`dependencies`を受け取ります。
|
||||
*path operation デコレータ*はオプション引数`dependencies`を受け取ります。
|
||||
|
||||
それは`Depends()`の`list`であるべきです:
|
||||
|
||||
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
|
||||
|
||||
これらの依存関係は、通常の依存関係と同様に実行・解決されます。しかし、それらの値(何かを返す場合)は*パスオペレーション関数*には渡されません。
|
||||
これらの依存関係は、通常の依存関係と同様に実行・解決されます。しかし、それらの値(何かを返す場合)は*path operation 関数*には渡されません。
|
||||
|
||||
/// tip | 豆知識
|
||||
|
||||
一部のエディタは、未使用の関数パラメータをチェックしてエラーとして表示します。
|
||||
|
||||
これらの`dependencies`を*パスオペレーションデコレータ*で使用することで、エディタ/ツールのエラーを回避しつつ、確実に実行されるようにできます。
|
||||
これらの`dependencies`を*path operation デコレータ*で使用することで、エディタ/ツールのエラーを回避しつつ、確実に実行されるようにできます。
|
||||
|
||||
また、コード内の未使用のパラメータを見た新しい開発者が、それを不要だと思って混乱するのを避ける助けにもなるかもしれません。
|
||||
|
||||
@@ -60,10 +60,10 @@
|
||||
|
||||
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
|
||||
|
||||
## *パスオペレーション*のグループに対する依存関係 { #dependencies-for-a-group-of-path-operations }
|
||||
## *path operation*のグループに対する依存関係 { #dependencies-for-a-group-of-path-operations }
|
||||
|
||||
後で、より大きなアプリケーションを(おそらく複数ファイルで)構造化する方法([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank})について読むときに、*パスオペレーション*のグループに対して単一の`dependencies`パラメータを宣言する方法を学びます。
|
||||
後で、より大きなアプリケーションを(おそらく複数ファイルで)構造化する方法([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank})について読むときに、*path operation*のグループに対して単一の`dependencies`パラメータを宣言する方法を学びます。
|
||||
|
||||
## グローバル依存関係 { #global-dependencies }
|
||||
|
||||
次に、`FastAPI`アプリケーション全体に依存関係を追加して、各*パスオペレーション*に適用する方法を見ていきます。
|
||||
次に、`FastAPI`アプリケーション全体に依存関係を追加して、各*path operation*に適用する方法を見ていきます。
|
||||
|
||||
@@ -103,7 +103,7 @@ FastAPIは、いくつかの<abbr title='sometimes also called "exit code", "cle
|
||||
|
||||
/// tip | 豆知識
|
||||
|
||||
これはやや高度なテクニックで、ほとんどの場合は本当に必要にはなりません。例えば、*パスオペレーション関数*など、アプリケーションコードの他の場所から(`HTTPException`を含む)例外を発生させられるためです。
|
||||
これはやや高度なテクニックで、ほとんどの場合は本当に必要にはなりません。例えば、*path operation 関数*など、アプリケーションコードの他の場所から(`HTTPException`を含む)例外を発生させられるためです。
|
||||
|
||||
ただし必要であれば使えます。 🤓
|
||||
|
||||
@@ -180,7 +180,7 @@ participant tasks as Background tasks
|
||||
|
||||
/// tip | 豆知識
|
||||
|
||||
*パスオペレーション関数*のコードで例外をraiseした場合、`HTTPException`を含め、それはyieldを持つ依存関係に渡されます。ほとんどの場合、その例外が正しく処理されるように、`yield`を持つ依存関係から同じ例外、または新しい例外を再raiseしたくなるでしょう。
|
||||
*path operation 関数*のコードで例外をraiseした場合、`HTTPException`を含め、それはyieldを持つ依存関係に渡されます。ほとんどの場合、その例外が正しく処理されるように、`yield`を持つ依存関係から同じ例外、または新しい例外を再raiseしたくなるでしょう。
|
||||
|
||||
///
|
||||
|
||||
@@ -188,14 +188,14 @@ participant tasks as Background tasks
|
||||
|
||||
通常、`yield`を持つ依存関係の終了コードは、クライアントに**レスポンスが送信された後**に実行されます。
|
||||
|
||||
しかし、*パスオペレーション関数*からreturnした後に依存関係を使う必要がないと分かっている場合は、`Depends(scope="function")`を使って、**レスポンスが送信される前**に、*パスオペレーション関数*のreturn後に依存関係を閉じるべきだとFastAPIに伝えられます。
|
||||
しかし、*path operation 関数*からreturnした後に依存関係を使う必要がないと分かっている場合は、`Depends(scope="function")`を使って、**レスポンスが送信される前**に、*path operation 関数*のreturn後に依存関係を閉じるべきだとFastAPIに伝えられます。
|
||||
|
||||
{* ../../docs_src/dependencies/tutorial008e_an_py39.py hl[12,16] *}
|
||||
|
||||
`Depends()`は、以下のいずれかを取る`scope`パラメータを受け取ります:
|
||||
|
||||
* `"function"`: リクエストを処理する*パスオペレーション関数*の前に依存関係を開始し、*パスオペレーション関数*の終了後に依存関係を終了しますが、クライアントにレスポンスが返される**前**に終了します。つまり、依存関係関数は*パスオペレーション関数*の**周囲**で実行されます。
|
||||
* `"request"`: リクエストを処理する*パスオペレーション関数*の前に依存関係を開始し(`"function"`を使用する場合と同様)、クライアントにレスポンスが返された**後**に終了します。つまり、依存関係関数は**リクエスト**とレスポンスのサイクルの**周囲**で実行されます。
|
||||
* `"function"`: リクエストを処理する*path operation 関数*の前に依存関係を開始し、*path operation 関数*の終了後に依存関係を終了しますが、クライアントにレスポンスが返される**前**に終了します。つまり、依存関係関数は*path operation 関数*の**周囲**で実行されます。
|
||||
* `"request"`: リクエストを処理する*path operation 関数*の前に依存関係を開始し(`"function"`を使用する場合と同様)、クライアントにレスポンスが返された**後**に終了します。つまり、依存関係関数は**リクエスト**とレスポンスのサイクルの**周囲**で実行されます。
|
||||
|
||||
指定されておらず、依存関係に`yield`がある場合、デフォルトで`scope`は`"request"`になります。
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 「Dependency Injection」とは { #what-is-dependency-injection }
|
||||
|
||||
**「Dependency Injection」** とは、プログラミングにおいて、コード(この場合は、*パスオペレーション関数*)が動作したり使用したりするために必要なもの(「依存関係」)を宣言する方法があることを意味します:
|
||||
**「Dependency Injection」** とは、プログラミングにおいて、コード(この場合は、*path operation 関数*)が動作したり使用したりするために必要なもの(「依存関係」)を宣言する方法があることを意味します:
|
||||
|
||||
そして、そのシステム(この場合は、**FastAPI**)は、必要な依存関係をコードに提供するために必要なことは何でも行います(依存関係を「注入」します)。
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
まずは依存関係に注目してみましょう。
|
||||
|
||||
以下のように、*パスオペレーション関数*と同じパラメータを全て取ることができる関数にすぎません:
|
||||
以下のように、*path operation 関数*と同じパラメータを全て取ることができる関数にすぎません:
|
||||
|
||||
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *}
|
||||
|
||||
@@ -37,9 +37,9 @@
|
||||
|
||||
**2行**。
|
||||
|
||||
そして、それはすべての*パスオペレーション関数*が持っているのと同じ形と構造を持っています。
|
||||
そして、それはすべての*path operation 関数*が持っているのと同じ形と構造を持っています。
|
||||
|
||||
「デコレータ」を含まない(`@app.get("/some-path")`を含まない)*パスオペレーション関数*と考えることもできます。
|
||||
「デコレータ」を含まない(`@app.get("/some-path")`を含まない)*path operation 関数*と考えることもできます。
|
||||
|
||||
そして何でも返すことができます。
|
||||
|
||||
@@ -67,7 +67,7 @@ FastAPI はバージョン 0.95.0 で `Annotated` のサポートを追加し(
|
||||
|
||||
### 「dependant」での依存関係の宣言 { #declare-the-dependency-in-the-dependant }
|
||||
|
||||
*パスオペレーション関数*のパラメータに`Body`や`Query`などを使用するのと同じように、新しいパラメータに`Depends`を使用することができます:
|
||||
*path operation 関数*のパラメータに`Body`や`Query`などを使用するのと同じように、新しいパラメータに`Depends`を使用することができます:
|
||||
|
||||
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}
|
||||
|
||||
@@ -79,7 +79,7 @@ FastAPI はバージョン 0.95.0 で `Annotated` のサポートを追加し(
|
||||
|
||||
直接**呼び出しません**(末尾に括弧を付けません)。`Depends()` のパラメータとして渡すだけです。
|
||||
|
||||
そして、その関数は、*パスオペレーション関数*が行うのと同じ方法でパラメータを取ります。
|
||||
そして、その関数は、*path operation 関数*が行うのと同じ方法でパラメータを取ります。
|
||||
|
||||
/// tip | 豆知識
|
||||
|
||||
@@ -91,7 +91,7 @@ FastAPI はバージョン 0.95.0 で `Annotated` のサポートを追加し(
|
||||
|
||||
* 依存関係("dependable")関数を正しいパラメータで呼び出します。
|
||||
* 関数の結果を取得します。
|
||||
* *パスオペレーション関数*のパラメータにその結果を代入してください。
|
||||
* *path operation 関数*のパラメータにその結果を代入してください。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
@@ -104,7 +104,7 @@ common_parameters --> read_items
|
||||
common_parameters --> read_users
|
||||
```
|
||||
|
||||
この方法では、共有されるコードを一度書き、**FastAPI** が*パスオペレーション*のための呼び出しを行います。
|
||||
この方法では、共有されるコードを一度書き、**FastAPI** が*path operation*のための呼び出しを行います。
|
||||
|
||||
/// check | 確認
|
||||
|
||||
@@ -138,15 +138,15 @@ commons: Annotated[dict, Depends(common_parameters)]
|
||||
|
||||
依存関係は期待どおりに動作し続け、**一番良い点** は **型情報が保持される** ことです。つまり、エディタは **自動補完**、**インラインエラー** などを提供し続けられます。`mypy` のような他のツールでも同様です。
|
||||
|
||||
これは **大規模なコードベース** で、**同じ依存関係** を **多くの *パスオペレーション*** で何度も使う場合に特に役立ちます。
|
||||
これは **大規模なコードベース** で、**同じ依存関係** を **多くの *path operation*** で何度も使う場合に特に役立ちます。
|
||||
|
||||
## `async`にするかどうか { #to-async-or-not-to-async }
|
||||
|
||||
依存関係は **FastAPI**(*パスオペレーション関数*と同じ)からも呼び出されるため、関数を定義する際にも同じルールが適用されます。
|
||||
依存関係は **FastAPI**(*path operation 関数*と同じ)からも呼び出されるため、関数を定義する際にも同じルールが適用されます。
|
||||
|
||||
`async def`や通常の`def`を使用することができます。
|
||||
|
||||
また、通常の`def`*パスオペレーション関数*の中に`async def`を入れて依存関係を宣言したり、`async def`*パスオペレーション関数*の中に`def`を入れて依存関係を宣言したりすることなどができます。
|
||||
また、通常の`def`*path operation 関数*の中に`async def`を入れて依存関係を宣言したり、`async def`*path operation 関数*の中に`def`を入れて依存関係を宣言したりすることなどができます。
|
||||
|
||||
それは重要ではありません。**FastAPI** は何をすべきかを知っています。
|
||||
|
||||
@@ -166,13 +166,13 @@ commons: Annotated[dict, Depends(common_parameters)]
|
||||
|
||||
## 簡単な使い方 { #simple-usage }
|
||||
|
||||
見てみると、*path*と*operation*が一致した時に*パスオペレーション関数*が宣言されていて、**FastAPI** が正しいパラメータで関数を呼び出してリクエストからデータを抽出する処理をしています。
|
||||
見てみると、*path*と*operation*が一致した時に*path operation 関数*が宣言されていて、**FastAPI** が正しいパラメータで関数を呼び出してリクエストからデータを抽出する処理をしています。
|
||||
|
||||
実は、すべての(あるいはほとんどの)Webフレームワークは、このように動作します。
|
||||
|
||||
これらの関数を直接呼び出すことはありません。これらの関数はフレームワーク(この場合は、**FastAPI**)によって呼び出されます。
|
||||
|
||||
Dependency Injection システムでは、**FastAPI** に*パスオペレーション関数*もまた、*パスオペレーション関数*の前に実行されるべき他の何かに「依存」していることを伝えることができ、**FastAPI** がそれを実行し、結果を「注入」することを引き受けます。
|
||||
Dependency Injection システムでは、**FastAPI** に*path operation 関数*もまた、*path operation 関数*の前に実行されるべき他の何かに「依存」していることを伝えることができ、**FastAPI** がそれを実行し、結果を「注入」することを引き受けます。
|
||||
|
||||
他にも、「dependency injection」と同じような考えの一般的な用語があります:
|
||||
|
||||
@@ -184,7 +184,7 @@ Dependency Injection システムでは、**FastAPI** に*パスオペレーシ
|
||||
|
||||
## **FastAPI** プラグイン { #fastapi-plug-ins }
|
||||
|
||||
統合や「プラグイン」は **Dependency Injection** システムを使って構築することができます。しかし、実際には、**「プラグイン」を作成する必要はありません**。依存関係を使用することで、無限の数の統合やインタラクションを宣言することができ、それが*パスオペレーション関数*で利用可能になるからです。
|
||||
統合や「プラグイン」は **Dependency Injection** システムを使って構築することができます。しかし、実際には、**「プラグイン」を作成する必要はありません**。依存関係を使用することで、無限の数の統合やインタラクションを宣言することができ、それが*path operation 関数*で利用可能になるからです。
|
||||
|
||||
依存関係は非常にシンプルで直感的な方法で作成することができ、必要なPythonパッケージをインポートするだけで、*文字通り*数行のコードでAPI関数と統合することができます。
|
||||
|
||||
@@ -211,7 +211,7 @@ dependency injection システムがシンプルなので、**FastAPI** は以
|
||||
|
||||
最終的には、依存関係の階層ツリーが構築され、**Dependency Injection**システムが、これらの依存関係(およびそのサブ依存関係)をすべて解決し、各ステップで結果を提供(注入)します。
|
||||
|
||||
例えば、4つのAPIエンドポイント(*パスオペレーション*)があるとします:
|
||||
例えば、4つのAPIエンドポイント(*path operation*)があるとします:
|
||||
|
||||
* `/items/public/`
|
||||
* `/items/private/`
|
||||
@@ -245,6 +245,6 @@ paying_user --> pro_items
|
||||
|
||||
## **OpenAPI** との統合 { #integrated-with-openapi_1 }
|
||||
|
||||
これら全ての依存関係は、要件を宣言すると同時に、*パスオペレーション*にパラメータやバリデーションを追加します。
|
||||
これら全ての依存関係は、要件を宣言すると同時に、*path operation*にパラメータやバリデーションを追加します。
|
||||
|
||||
**FastAPI** はそれをすべてOpenAPIスキーマに追加して、対話型のドキュメントシステムに表示されるようにします。
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
|
||||
/// info | 情報
|
||||
|
||||
*パスオペレーション関数*の中で宣言している依存関係は`query_or_cookie_extractor`の1つだけであることに注意してください。
|
||||
*path operation 関数*の中で宣言している依存関係は`query_or_cookie_extractor`の1つだけであることに注意してください。
|
||||
|
||||
しかし、**FastAPI** は`query_extractor`を最初に解決し、その結果を`query_or_cookie_extractor`を呼び出す時に渡す必要があることを知っています。
|
||||
|
||||
@@ -56,7 +56,7 @@ query_extractor --> query_or_cookie_extractor --> read_query
|
||||
|
||||
## 同じ依存関係の複数回の使用 { #using-the-same-dependency-multiple-times }
|
||||
|
||||
依存関係の1つが同じ*パスオペレーション*に対して複数回宣言されている場合、例えば、複数の依存関係が共通のサブ依存関係を持っている場合、**FastAPI** はリクエストごとに1回だけそのサブ依存関係を呼び出します。
|
||||
依存関係の1つが同じ*path operation*に対して複数回宣言されている場合、例えば、複数の依存関係が共通のサブ依存関係を持っている場合、**FastAPI** はリクエストごとに1回だけそのサブ依存関係を呼び出します。
|
||||
|
||||
そして、返された値を<abbr title="A utility/system to store computed/generated values, to reuse them instead of computing them again. – 計算/生成された値を保存し、再計算する代わりに再利用するためのユーティリティ/システム。">「キャッシュ」</abbr>に保存し、同じリクエストに対して依存関係を何度も呼び出す代わりに、その特定のリクエストでそれを必要とする全ての「依存」に渡すことになります。
|
||||
|
||||
@@ -90,7 +90,7 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False
|
||||
|
||||
ここで使われている派手な言葉は別にして、**Dependency Injection** システムは非常にシンプルです。
|
||||
|
||||
*パスオペレーション関数*と同じように見えるただの関数です。
|
||||
*path operation 関数*と同じように見えるただの関数です。
|
||||
|
||||
しかし、それでも非常に強力で、任意の深くネストされた依存関係「グラフ」(ツリー)を宣言することができます。
|
||||
|
||||
|
||||
@@ -263,7 +263,7 @@ APIを構築するときは、通常、これらの特定のHTTPメソッドを
|
||||
|
||||
「**オペレーションズ**」とも呼ぶことにします。
|
||||
|
||||
#### *パスオペレーションデコレータ*を定義 { #define-a-path-operation-decorator }
|
||||
#### *path operation デコレータ*を定義 { #define-a-path-operation-decorator }
|
||||
|
||||
{* ../../docs_src/first_steps/tutorial001_py39.py hl[6] *}
|
||||
|
||||
@@ -282,7 +282,7 @@ Pythonにおける`@something`シンタックスはデコレータと呼ばれ
|
||||
|
||||
私たちの場合、このデコレーターは直下の関数が**オペレーション** `get`を使用した**パス** `/`に対応することを**FastAPI** に通知します。
|
||||
|
||||
これが「*パスオペレーションデコレータ*」です。
|
||||
これが「*path operation デコレータ*」です。
|
||||
|
||||
///
|
||||
|
||||
@@ -311,9 +311,9 @@ Pythonにおける`@something`シンタックスはデコレータと呼ばれ
|
||||
|
||||
///
|
||||
|
||||
### Step 4: **パスオペレーション関数**を定義 { #step-4-define-the-path-operation-function }
|
||||
### Step 4: **path operation 関数**を定義 { #step-4-define-the-path-operation-function }
|
||||
|
||||
以下は「**パスオペレーション関数**」です:
|
||||
以下は「**path operation 関数**」です:
|
||||
|
||||
* **パス**: は`/`です。
|
||||
* **オペレーション**: は`get`です。
|
||||
@@ -373,7 +373,7 @@ FastAPIはオープンソースで、標準に基づいています。選択し
|
||||
|
||||
* `FastAPI`をインポートします。
|
||||
* `app`インスタンスを生成します。
|
||||
* `@app.get("/")`のようなデコレータを使用して、**パスオペレーションデコレータ**を記述します。
|
||||
* **パスオペレーション関数**を定義します。例: `def root(): ...`。
|
||||
* `@app.get("/")`のようなデコレータを使用して、**path operation デコレータ**を記述します。
|
||||
* **path operation 関数**を定義します。例: `def root(): ...`。
|
||||
* `fastapi dev`コマンドで開発サーバーを起動します。
|
||||
* 任意で`fastapi deploy`を使ってアプリをデプロイします。
|
||||
|
||||
@@ -40,13 +40,13 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url`
|
||||
|
||||
## タグのメタデータ { #metadata-for-tags }
|
||||
|
||||
パラメータ `openapi_tags` を使うと、パスオペレーションをグループ分けするために使用する各タグに追加のメタデータを追加できます。
|
||||
パラメータ `openapi_tags` を使うと、path operation をグループ分けするために使用する各タグに追加のメタデータを追加できます。
|
||||
|
||||
それぞれのタグごとに1つの辞書を含むリストを取ります。
|
||||
|
||||
それぞれの辞書は以下を含められます:
|
||||
|
||||
* `name` (**必須**): *パスオペレーション* および `APIRouter` の `tags` パラメータで使用するのと同じタグ名の `str`。
|
||||
* `name` (**必須**): *path operation* および `APIRouter` の `tags` パラメータで使用するのと同じタグ名の `str`。
|
||||
* `description`: タグの短い説明の `str`。Markdownを含められ、ドキュメントUIに表示されます。
|
||||
* `externalDocs`: 外部ドキュメントを説明する `dict`。以下を含みます:
|
||||
* `description`: 外部ドキュメントの短い説明の `str`。
|
||||
@@ -70,7 +70,7 @@ OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url`
|
||||
|
||||
### タグの使用 { #use-your-tags }
|
||||
|
||||
*パスオペレーション*(および `APIRouter`)の `tags` パラメータを使用して、それらを異なるタグに割り当てます:
|
||||
*path operation*(および `APIRouter`)の `tags` パラメータを使用して、それらを異なるタグに割り当てます:
|
||||
|
||||
{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
|
||||
|
||||
|
||||
@@ -122,7 +122,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
|
||||
|
||||
それ以外の場合、 `/users/{user_id}` は `/users/me` としてもマッチします。値が `"me"` であるパラメータ `user_id` を受け取ると「考え」ます。
|
||||
|
||||
同様に、パスオペレーションを再定義することはできません:
|
||||
同様に、path operation を再定義することはできません:
|
||||
|
||||
{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
|
||||
|
||||
@@ -130,7 +130,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
|
||||
|
||||
## 定義済みの値 { #predefined-values }
|
||||
|
||||
*パスパラメータ*を受け取る *path operation* をもち、有効な*パスパラメータ*の値を事前に定義したい場合は、標準のPython <abbr title="Enumeration">`Enum`</abbr> を利用できます。
|
||||
*パスパラメータ*を受け取る *path operation* をもち、有効な*パスパラメータ*の値を事前に定義したい場合は、標準のPython <abbr title="Enumeration - 列挙型">`Enum`</abbr> を利用できます。
|
||||
|
||||
### `Enum` クラスの作成 { #create-an-enum-class }
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# レスポンスモデル - 戻り値の型 { #response-model-return-type }
|
||||
|
||||
*パスオペレーション関数*の**戻り値の型**にアノテーションを付けることで、レスポンスに使用される型を宣言できます。
|
||||
*path operation 関数*の**戻り値の型**にアノテーションを付けることで、レスポンスに使用される型を宣言できます。
|
||||
|
||||
関数**パラメータ**の入力データと同じように **型アノテーション** を使用できます。Pydanticモデル、リスト、辞書、整数や真偽値などのスカラー値を使用できます。
|
||||
|
||||
@@ -10,7 +10,7 @@ FastAPIはこの戻り値の型を使って以下を行います:
|
||||
|
||||
* 返却データを**検証**します。
|
||||
* データが不正(例: フィールドが欠けている)であれば、それは*あなた*のアプリコードが壊れていて、返すべきものを返していないことを意味し、不正なデータを返す代わりにサーバーエラーを返します。これにより、あなたとクライアントは、期待されるデータとデータ形状を受け取れることを確実にできます。
|
||||
* OpenAPIの *パスオペレーション* に、レスポンス用の **JSON Schema** を追加します。
|
||||
* OpenAPIの *path operation* に、レスポンス用の **JSON Schema** を追加します。
|
||||
* これは**自動ドキュメント**で使用されます。
|
||||
* 自動クライアントコード生成ツールでも使用されます。
|
||||
|
||||
@@ -27,9 +27,9 @@ FastAPIはこの戻り値の型を使って以下を行います:
|
||||
|
||||
戻り値の型アノテーションを追加すると、ツールやエディタが(正しく)エラーとして、関数が宣言した型(例: Pydanticモデル)とは異なる型(例: dict)を返していると警告します。
|
||||
|
||||
そのような場合、戻り値の型の代わりに、*パスオペレーションデコレータ*のパラメータ `response_model` を使用できます。
|
||||
そのような場合、戻り値の型の代わりに、*path operation デコレータ*のパラメータ `response_model` を使用できます。
|
||||
|
||||
`response_model`パラメータは、いずれの *パスオペレーション* でも使用できます:
|
||||
`response_model`パラメータは、いずれの *path operation* でも使用できます:
|
||||
|
||||
* `@app.get()`
|
||||
* `@app.post()`
|
||||
@@ -41,7 +41,7 @@ FastAPIはこの戻り値の型を使って以下を行います:
|
||||
|
||||
/// note | 備考
|
||||
|
||||
`response_model`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*パスオペレーション関数* のパラメータではありません。
|
||||
`response_model`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation 関数* のパラメータではありません。
|
||||
|
||||
///
|
||||
|
||||
@@ -63,7 +63,7 @@ FastAPIはこの `response_model` を使って、データのドキュメント
|
||||
|
||||
これにより、レスポンスモデルとは異なる型を返している場合でも、エディタやmypyなどのツールで使用するために関数へ正しい型アノテーションを追加できます。それでもFastAPIは `response_model` を使用してデータの検証やドキュメント化などを実行できます。
|
||||
|
||||
また `response_model=None` を使用して、その*パスオペレーション*のレスポンスモデル生成を無効化することもできます。これは、Pydanticのフィールドとして有効ではないものに対して型アノテーションを追加する場合に必要になることがあります。以下のセクションのいずれかで例を示します。
|
||||
また `response_model=None` を使用して、その*path operation*のレスポンスモデル生成を無効化することもできます。これは、Pydanticのフィールドとして有効ではないものに対して型アノテーションを追加する場合に必要になることがあります。以下のセクションのいずれかで例を示します。
|
||||
|
||||
## 同じ入力データの返却 { #return-the-same-input-data }
|
||||
|
||||
@@ -97,7 +97,7 @@ $ pip install "pydantic[email]"
|
||||
|
||||
この場合、同じユーザーがパスワードを送信しているので問題ないかもしれません。
|
||||
|
||||
しかし、同じモデルを別の*パスオペレーション*に使用すると、すべてのクライアントにユーザーのパスワードを送信してしまう可能性があります。
|
||||
しかし、同じモデルを別の*path operation*に使用すると、すべてのクライアントにユーザーのパスワードを送信してしまう可能性があります。
|
||||
|
||||
/// danger | 警告
|
||||
|
||||
@@ -111,7 +111,7 @@ $ pip install "pydantic[email]"
|
||||
|
||||
{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
|
||||
|
||||
ここでは、*パスオペレーション関数*がパスワードを含む同じ入力ユーザーを返しているにもかかわらず:
|
||||
ここでは、*path operation 関数*がパスワードを含む同じ入力ユーザーを返しているにもかかわらず:
|
||||
|
||||
{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
|
||||
|
||||
@@ -235,13 +235,13 @@ Pydanticフィールドとして有効ではないものを返し、ツール(
|
||||
|
||||
### `response_model_exclude_unset`パラメータの使用 { #use-the-response-model-exclude-unset-parameter }
|
||||
|
||||
*パスオペレーションデコレータ*のパラメータ `response_model_exclude_unset=True` を設定できます:
|
||||
*path operation デコレータ*のパラメータ `response_model_exclude_unset=True` を設定できます:
|
||||
|
||||
{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
|
||||
|
||||
そうすると、デフォルト値はレスポンスに含まれず、実際に設定された値のみが含まれます。
|
||||
|
||||
そのため、ID `foo` のitemに対してその *パスオペレーション* へリクエストを送ると、レスポンスは以下のようになります(デフォルト値を含まない):
|
||||
そのため、ID `foo` のitemに対してその *path operation* へリクエストを送ると、レスポンスは以下のようになります(デフォルト値を含まない):
|
||||
|
||||
```JSON
|
||||
{
|
||||
@@ -304,7 +304,7 @@ FastAPIは十分に賢いので(実際には、Pydanticが十分に賢い)
|
||||
|
||||
### `response_model_include`と`response_model_exclude` { #response-model-include-and-response-model-exclude }
|
||||
|
||||
*パスオペレーションデコレータ*のパラメータ `response_model_include` と `response_model_exclude` も使用できます。
|
||||
*path operation デコレータ*のパラメータ `response_model_include` と `response_model_exclude` も使用できます。
|
||||
|
||||
これらは、含める(残りを省略する)または除外する(残りを含む)属性名を持つ `str` の `set` を受け取ります。
|
||||
|
||||
@@ -338,6 +338,6 @@ FastAPIは十分に賢いので(実際には、Pydanticが十分に賢い)
|
||||
|
||||
## まとめ { #recap }
|
||||
|
||||
*パスオペレーションデコレータ*のパラメータ `response_model` を使用してレスポンスモデルを定義し、とくにプライベートデータがフィルタリングされることを保証します。
|
||||
*path operation デコレータ*のパラメータ `response_model` を使用してレスポンスモデルを定義し、とくにプライベートデータがフィルタリングされることを保証します。
|
||||
|
||||
明示的に設定された値のみを返すには、`response_model_exclude_unset` を使用します。
|
||||
|
||||
@@ -80,13 +80,13 @@ Pydanticモデルで`Field()`を使う場合、追加の`examples`も宣言で
|
||||
|
||||
**JSON Schema**が`examples`をサポートする前から、OpenAPIは同じく`examples`という別のフィールドをサポートしていました。
|
||||
|
||||
この**OpenAPI固有**の`examples`は、OpenAPI仕様の別のセクションに入ります。各JSON Schemaの中ではなく、**各*パスオペレーション*の詳細**に入ります。
|
||||
この**OpenAPI固有**の`examples`は、OpenAPI仕様の別のセクションに入ります。各JSON Schemaの中ではなく、**各*path operation*の詳細**に入ります。
|
||||
|
||||
そしてSwagger UIは、この特定の`examples`フィールドを以前からサポートしています。そのため、これを使って**ドキュメントUIに異なる例を表示**できます。
|
||||
|
||||
このOpenAPI固有フィールド`examples`の形は**複数の例**(`list`ではなく)を持つ`dict`であり、それぞれに追加情報が含まれ、その追加情報は**OpenAPI**にも追加されます。
|
||||
|
||||
これはOpenAPIに含まれる各JSON Schemaの中には入らず、外側の、*パスオペレーション*に直接入ります。
|
||||
これはOpenAPIに含まれる各JSON Schemaの中には入らず、外側の、*path operation*に直接入ります。
|
||||
|
||||
### `openapi_examples`パラメータの使用 { #using-the-openapi-examples-parameter }
|
||||
|
||||
@@ -185,7 +185,7 @@ Pydanticモデル内で、`schema_extra`または`Field(examples=["something"])`
|
||||
|
||||
そしてそのPydanticモデルの**JSON Schema**はAPIの**OpenAPI**に含まれ、ドキュメントUIで使用されます。
|
||||
|
||||
FastAPI 0.99.0より前のバージョン(0.99.0以上は新しいOpenAPI 3.1.0を使用)では、他のユーティリティ(`Query()`、`Body()`など)で`example`または`examples`を使っても、それらの例はそのデータを説明するJSON Schema(OpenAPI独自版のJSON Schemaでさえ)には追加されず、OpenAPI内の*パスオペレーション*宣言に直接追加されていました(JSON Schemaを使用するOpenAPIの部分の外側)。
|
||||
FastAPI 0.99.0より前のバージョン(0.99.0以上は新しいOpenAPI 3.1.0を使用)では、他のユーティリティ(`Query()`、`Body()`など)で`example`または`examples`を使っても、それらの例はそのデータを説明するJSON Schema(OpenAPI独自版のJSON Schemaでさえ)には追加されず、OpenAPI内の*path operation*宣言に直接追加されていました(JSON Schemaを使用するOpenAPIの部分の外側)。
|
||||
|
||||
しかし、FastAPI 0.99.0以上ではOpenAPI 3.1.0を使用し、それはJSON Schema 2020-12とSwagger UI 5.0.0以上を使うため、すべてがより一貫し、例はJSON Schemaに含まれます。
|
||||
|
||||
|
||||
@@ -64,7 +64,7 @@ $ fastapi dev main.py
|
||||
|
||||
すでにピカピカの新しい「Authorize」ボタンがあります。
|
||||
|
||||
そして、あなたの*パスオペレーション*には、右上にクリックできる小さな鍵アイコンがあります。
|
||||
そして、あなたの*path operation*には、右上にクリックできる小さな鍵アイコンがあります。
|
||||
|
||||
///
|
||||
|
||||
@@ -144,9 +144,9 @@ OAuth2は、バックエンドやAPIがユーザーを認証するサーバー
|
||||
|
||||
///
|
||||
|
||||
このパラメーターはエンドポイント/ *パスオペレーション*を作成しません。しかし、URL`/token`はクライアントがトークンを取得するために使用するものであると宣言します。この情報は OpenAPI やインタラクティブな API ドキュメントシステムで使われます。
|
||||
このパラメーターはエンドポイント/ *path operation*を作成しません。しかし、URL`/token`はクライアントがトークンを取得するために使用するものであると宣言します。この情報は OpenAPI やインタラクティブな API ドキュメントシステムで使われます。
|
||||
|
||||
実際のパスオペレーションもすぐに作ります。
|
||||
実際の path operation もすぐに作ります。
|
||||
|
||||
/// info | 情報
|
||||
|
||||
@@ -172,7 +172,7 @@ oauth2_scheme(some, parameters)
|
||||
|
||||
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
|
||||
|
||||
この依存関係は、*パスオペレーション関数*のパラメーター`token`に代入される`str`を提供します。
|
||||
この依存関係は、*path operation 関数*のパラメーター`token`に代入される`str`を提供します。
|
||||
|
||||
**FastAPI**は、この依存関係を使用してOpenAPIスキーマ (および自動APIドキュメント) で「セキュリティスキーム」を定義できることを知っています。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 現在のユーザーの取得 { #get-current-user }
|
||||
|
||||
一つ前の章では、(依存性注入システムに基づいた)セキュリティシステムは、 *パスオペレーション関数* に `str` として `token` を与えていました:
|
||||
一つ前の章では、(依存性注入システムに基づいた)セキュリティシステムは、 *path operation 関数* に `str` として `token` を与えていました:
|
||||
|
||||
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
|
||||
`get_current_user` は前に作成した `oauth2_scheme` と同じ依存関係を持ちます。
|
||||
|
||||
以前直接 *パスオペレーション* の中でしていたのと同じように、新しい依存関係である `get_current_user` はサブ依存関係である `oauth2_scheme` から `str` として `token` を受け取るようになります:
|
||||
以前直接 *path operation* の中でしていたのと同じように、新しい依存関係である `get_current_user` はサブ依存関係である `oauth2_scheme` から `str` として `token` を受け取るようになります:
|
||||
|
||||
{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
|
||||
## 現在のユーザーの注入 { #inject-the-current-user }
|
||||
|
||||
ですので、 `get_current_user` に対して同様に *パスオペレーション* の中で `Depends` を利用できます。
|
||||
ですので、 `get_current_user` に対して同様に *path operation* の中で `Depends` を利用できます。
|
||||
|
||||
{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
|
||||
|
||||
@@ -62,7 +62,7 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ
|
||||
|
||||
## 別のモデル { #other-models }
|
||||
|
||||
これで、*パスオペレーション関数* の中で現在のユーザーを直接取得し、`Depends` を使って、 **依存性注入** レベルでセキュリティメカニズムを処理できるようになりました。
|
||||
これで、*path operation 関数* の中で現在のユーザーを直接取得し、`Depends` を使って、 **依存性注入** レベルでセキュリティメカニズムを処理できるようになりました。
|
||||
|
||||
そして、セキュリティ要件のためにどんなモデルやデータでも利用することができます。(この場合は、 Pydanticモデルの `User`)
|
||||
|
||||
@@ -78,7 +78,7 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ
|
||||
|
||||
## コードサイズ { #code-size }
|
||||
|
||||
この例は冗長に見えるかもしれません。セキュリティとデータモデルユーティリティ関数および *パスオペレーション* が同じファイルに混在しているということを覚えておいてください。
|
||||
この例は冗長に見えるかもしれません。セキュリティとデータモデルユーティリティ関数および *path operation* が同じファイルに混在しているということを覚えておいてください。
|
||||
|
||||
しかし、ここに重要なポイントがあります。
|
||||
|
||||
@@ -86,20 +86,20 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ
|
||||
|
||||
そして、それは好きなだけ複雑にすることができます。それでも、一箇所に、一度だけ書くのです。すべての柔軟性を備えます。
|
||||
|
||||
しかし、同じセキュリティシステムを使って何千ものエンドポイント(*パスオペレーション*)を持つことができます。
|
||||
しかし、同じセキュリティシステムを使って何千ものエンドポイント(*path operation*)を持つことができます。
|
||||
|
||||
そして、それらエンドポイントのすべて(必要な、どの部分でも)がこうした依存関係や、あなたが作成する別の依存関係を再利用する利点を享受できるのです。
|
||||
|
||||
さらに、こうした何千もの *パスオペレーション* は、たった3行で表現できるのです:
|
||||
さらに、こうした何千もの *path operation* は、たった3行で表現できるのです:
|
||||
|
||||
{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
|
||||
|
||||
## まとめ { #recap }
|
||||
|
||||
これで、 *パスオペレーション関数* の中で直接現在のユーザーを取得できるようになりました。
|
||||
これで、 *path operation 関数* の中で直接現在のユーザーを取得できるようになりました。
|
||||
|
||||
既に半分のところまで来ています。
|
||||
|
||||
あとは、ユーザー/クライアントが実際に `username` と `password` を送信するための *パスオペレーション* を追加する必要があるだけです。
|
||||
あとは、ユーザー/クライアントが実際に `username` と `password` を送信するための *path operation* を追加する必要があるだけです。
|
||||
|
||||
次はそれを説明します。
|
||||
|
||||
@@ -164,7 +164,7 @@ JWTトークンの署名に使用するアルゴリズム`"HS256"`を指定し
|
||||
|
||||
{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *}
|
||||
|
||||
## `/token` *パスオペレーション* の更新 { #update-the-token-path-operation }
|
||||
## `/token` *path operation* の更新 { #update-the-token-path-operation }
|
||||
|
||||
トークンの有効期限を表す`timedelta`を作成します。
|
||||
|
||||
|
||||
@@ -113,7 +113,7 @@ FastAPIアプリケーションへのリクエストの送信とは別に、テ
|
||||
│ └── test_main.py
|
||||
```
|
||||
|
||||
ここで、**FastAPI** アプリがある `main.py` ファイルには、他のパスオペレーションがあります。
|
||||
ここで、**FastAPI** アプリがある `main.py` ファイルには、他の path operation があります。
|
||||
|
||||
エラーを返す可能性のある `GET` オペレーションがあります。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user