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

Depends()

依存関係は、主にcallableを受け取る特別な関数Depends()で処理されます。

参照とパラメータはこちらです。

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

from fastapi import Depends

fastapi.Depends

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

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

単一の「依存可能な」callable（関数など）を受け取ります。

直接呼び出さないでください。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	「依存可能な」callable（関数など）。 直接呼び出さないでください。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()を使用できます。

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

from fastapi import Security

fastapi.Security

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

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

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

単一の「依存可能な」callable（関数など）を受け取ります。

直接呼び出さないでください。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	「依存可能な」callable（関数など）。 直接呼び出さないでください。FastAPIがあなたのために呼び出します。オブジェクトを直接渡すだけです。 TYPE: Optional[Callable[..., Any]] DEFAULT: None
scopes	このSecurity依存関係を使用する*パス操作*に必要な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)