依存関係 - Depends() と Security()

Depends()

依存関係は、主に呼び出し可能オブジェクトを取る特殊な関数Depends()で処理されます。

ここに、その参照とパラメータがあります。

fastapiから直接インポートできます。

from fastapi import Depends

fastapi.Depends

Depends(dependency=None, *, use_cache=True)

FastAPIの依存関係を宣言します。

単一の「依存可能」な呼び出し可能オブジェクト（関数のようなもの）を取ります。

それを直接呼び出さないでください。FastAPIがあなたのために呼び出します。

詳細はFastAPIドキュメントの依存関係で確認してください。

例

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons

パラメータ	説明
dependency	「依存可能」な呼び出し可能オブジェクト（関数のようなもの）。 それを直接呼び出さないでください。FastAPIがあなたのために呼び出すので、オブジェクトを直接渡してください。 TYPE: Optional[Callable[..., Any]] DEFAULT: None
use_cache	デフォルトでは、リクエスト内で依存関係が初めて呼び出された後、そのリクエストの残りの部分で依存関係が再度宣言された場合（たとえば、依存関係が複数の依存関係によって必要とされる場合）、その値はリクエストの残りの部分で再利用されます。 この動作を無効にし、同じリクエスト内で依存関係が（複数回宣言された場合に）再度呼び出されるようにするには、use_cacheをFalseに設定します。 TYPE: bool DEFAULT: True

fastapi/param_functions.py のソースコード

def Depends(  # noqa: N802
    dependency: Annotated[
        Optional[Callable[..., Any]],
        Doc(
            """
            A "dependable" callable (like a function).

            Don't call it directly, FastAPI will call it for you, just pass the object
            directly.
            """
        ),
    ] = None,
    *,
    use_cache: Annotated[
        bool,
        Doc(
            """
            By default, after a dependency is called the first time in a request, if
            the dependency is declared again for the rest of the request (for example
            if the dependency is needed by several dependencies), the value will be
            re-used for the rest of the request.

            Set `use_cache` to `False` to disable this behavior and ensure the
            dependency is called again (if declared more than once) in the same request.
            """
        ),
    ] = True,
) -> Any:
    """
    Declare a FastAPI dependency.

    It takes a single "dependable" callable (like a function).

    Don't call it directly, FastAPI will call it for you.

    Read more about it in the
    [FastAPI docs for Dependencies](https://fastapi.dokyumento.jp/tutorial/dependencies/).

    **Example**

    ```python
    from typing import Annotated

    from fastapi import Depends, FastAPI

    app = FastAPI()


    async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
        return {"q": q, "skip": skip, "limit": limit}


    @app.get("/items/")
    async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
        return commons
    ```
    """
    return params.Depends(dependency=dependency, use_cache=use_cache)

Security()

多くのシナリオでは、Depends()を使用して、依存関係でセキュリティ（認可、認証など）を処理できます。

しかし、OAuth2スコープも宣言したい場合は、Depends()の代わりにSecurity()を使用できます。

fastapiからSecurity()を直接インポートできます。

from fastapi import Security

fastapi.Security

Security(dependency=None, *, scopes=None, use_cache=True)

FastAPIのセキュリティ依存関係を宣言します。

通常の依存関係との唯一の違いは、OpenAPIおよび自動UIドキュメント（デフォルトでは/docs）と統合されるOAuth2スコープを宣言できることです。

単一の「依存可能」な呼び出し可能オブジェクト（関数のようなもの）を取ります。

それを直接呼び出さないでください。FastAPIがあなたのために呼び出します。

詳細はFastAPIドキュメントのセキュリティおよびFastAPIドキュメントのOAuth2スコープで確認してください。

例

from typing import Annotated

from fastapi import Security, FastAPI

from .db import User
from .security import get_current_active_user

app = FastAPI()

@app.get("/users/me/items/")
async def read_own_items(
    current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])]
):
    return [{"item_id": "Foo", "owner": current_user.username}]

パラメータ	説明
dependency	「依存可能」な呼び出し可能オブジェクト（関数のようなもの）。 それを直接呼び出さないでください。FastAPIがあなたのために呼び出すので、オブジェクトを直接渡してください。 TYPE: Optional[Callable[..., Any]] DEFAULT: None
scopes	このセキュリティ依存関係を使用するパスオペレーションに必要なOAuth2スコープ。 「スコープ」という用語はOAuth2仕様に由来し、意図的に曖昧で解釈可能であるようです。通常は権限を指し、場合によっては役割を指します。 これらのスコープはOpenAPI（および/docsのAPIドキュメント）と統合されます。そのため、OpenAPI仕様で表示されます。 TYPE: Optional[Sequence[str]] DEFAULT: None
use_cache	デフォルトでは、リクエスト内で依存関係が初めて呼び出された後、そのリクエストの残りの部分で依存関係が再度宣言された場合（たとえば、依存関係が複数の依存関係によって必要とされる場合）、その値はリクエストの残りの部分で再利用されます。 この動作を無効にし、同じリクエスト内で依存関係が（複数回宣言された場合に）再度呼び出されるようにするには、use_cacheをFalseに設定します。 TYPE: bool DEFAULT: True

fastapi/param_functions.py のソースコード

def Security(  # noqa: N802
    dependency: Annotated[
        Optional[Callable[..., Any]],
        Doc(
            """
            A "dependable" callable (like a function).

            Don't call it directly, FastAPI will call it for you, just pass the object
            directly.
            """
        ),
    ] = None,
    *,
    scopes: Annotated[
        Optional[Sequence[str]],
        Doc(
            """
            OAuth2 scopes required for the *path operation* that uses this Security
            dependency.

            The term "scope" comes from the OAuth2 specification, it seems to be
            intentionally vague and interpretable. It normally refers to permissions,
            in cases to roles.

            These scopes are integrated with OpenAPI (and the API docs at `/docs`).
            So they are visible in the OpenAPI specification.
            )
            """
        ),
    ] = None,
    use_cache: Annotated[
        bool,
        Doc(
            """
            By default, after a dependency is called the first time in a request, if
            the dependency is declared again for the rest of the request (for example
            if the dependency is needed by several dependencies), the value will be
            re-used for the rest of the request.

            Set `use_cache` to `False` to disable this behavior and ensure the
            dependency is called again (if declared more than once) in the same request.
            """
        ),
    ] = True,
) -> Any:
    """
    Declare a FastAPI Security dependency.

    The only difference with a regular dependency is that it can declare OAuth2
    scopes that will be integrated with OpenAPI and the automatic UI docs (by default
    at `/docs`).

    It takes a single "dependable" callable (like a function).

    Don't call it directly, FastAPI will call it for you.

    Read more about it in the
    [FastAPI docs for Security](https://fastapi.dokyumento.jp/tutorial/security/) and
    in the
    [FastAPI docs for OAuth2 scopes](https://fastapi.dokyumento.jp/advanced/security/oauth2-scopes/).

    **Example**

    ```python
    from typing import Annotated

    from fastapi import Security, FastAPI

    from .db import User
    from .security import get_current_active_user

    app = FastAPI()

    @app.get("/users/me/items/")
    async def read_own_items(
        current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])]
    ):
        return [{"item_id": "Foo", "owner": current_user.username}]
    ```
    """
    return params.Security(dependency=dependency, scopes=scopes, use_cache=use_cache)