パーミッションの基礎

Last updated on September 28, 2026

注釈：本資料はAI技術を用いて翻訳されています。

Introduction​

パーミッションは、AccelByte Gaming Service (AGS) のリソースを使用するユーザーおよびアプリケーションにアクセス権を提供します。パーミッションは認可システムの基盤であり、以下の要素で構成されています。

  1. パーミッション要件: ほとんどの AGS API エンドポイントはパーミッションを必要とします。

    注記

    API エンドポイントのドキュメントには、各エンドポイントでシステムが要求するパーミッションが記載されています。

  2. パーミッションの付与: Admin Portal を使用すると、IAM クライアント経由でアプリケーションにパーミッションを割り当てたり、ロール経由でユーザーにパーミッションを割り当てたりできます。

この記事では、AGS のパーミッションとその用途について詳しく説明します。また、IAM クライアントやロールを通じてユーザーに割り当てられるパーミッションを示す関連ガイドへのリンクも提供します。

Syntax​

パーミッションは、パーミッションリソース と パーミッションアクション で構成されます。

Permission Resource​

AccelByte Gaming Services (AGS) では RESTful API 設計を採用しています。RESTful API では、主要なデータ表現は リソース です。AGS では、パーミッションリソースはコロンで区切られた複数のトークンを含む文字列です。これには、パーミッションが適用されるネームスペースやユーザーなどの詳細情報、および保護対象オブジェクトの名前を含めることができます。

Permission Action​

パーミッションアクションは、そのパーミッションによってユーザーまたはアプリケーションがリソースに対して何を行えるかを示します。アクションには Create、Read、Update、Delete があります。

Permission Requirement​

AGS エンドポイントのパーミッションを定義する際は、上記の一般的な構文に従ってください。例えば、以下は AGS エンドポイントのパーミッション要件のテンプレートで、4 つの個別のトークンを含んでいます。

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

  • ADMIN: パーミッションが管理リソース用であることを示す任意のトークンです。これは ADMIN エンドポイントのパーミッションにのみ付与するべきであり、以下のシナリオで使用されます。

    • IAM クライアントが認可する、AGS とアプリケーション間の信頼された内部 API 呼び出し。
    • 適切なロールを持つ Admin ユーザーが、Admin Portal（または他の適切な外部ツール）を使用して呼び出しを実行できる。

    例えば、ロール情報を検索するために使用するエンドポイントでは、ユーザーに admin パーミッションが必要です。

    EndpointPermissionDescription
    GET /iam/v3/admin/rolesADMIN:ROLE [READ]ロールはネームスペースやユーザーに属さないプラットフォームレベルのオブジェクトであるため、このパーミッションには NAMESPACE:{namespace} や USER:{userId} は含まれません。
    • パブリックエンドポイントは常に非 admin パーミッションを使用します。有効なアクセストークンを持つ承認済みのユーザーアカウントであれば、これらのエンドポイントを呼び出すことができます。

  • NAMESPACE:{namespace}: このオプションのトークンは、IAM クライアント、Store などのリソースが要求するように、リソースがネームスペースレベルに属する場合にのみ使用します。これは、パーミッションが適用されるネームスペースを示します。構文は文字列 NAMESPACE: の後にネームスペース名のプレースホルダー {namespace} が続きます。例えば、特定のネームスペース内で IAM クライアントを作成するエンドポイントでは、ユーザーに admin パーミッションが必要です。

    EndpointPermissionDescription
    POST /iam/v3/admin/namespaces/{namespace}/clientsADMIN:NAMESPACE:{namespace}:CLIENT [CREATE]リクエストが POST /iam/v3/admin/namespaces/accelbyte/clients 経由でリソースにアクセスしようとする場合、パーミッションは ADMIN:NAMESPACE:accelbyte:CLIENT [CREATE] になります。IAM クライアントはネームスペースレベルに属しますが、ユーザー固有のリソースではないため、パーミッションに User:userId は含まれません。

  • USER:{userId}: このオプションのトークンは、ユーザー固有のリソースにのみ使用します。このトークンは NAMESPACE:{namespace} と似ており、パーミッションが適用されるユーザーを表します。構文は USER: の後にユーザー ID のプレースホルダー {userId} が続きます。例えば、特定のネームスペース内の特定のユーザーに属するエンタイトルメントを検索するために使用するエンドポイントには、以下の admin パーミッションが必要です。

    EndpointPermissionDescription
    GET /admin/namespaces/{namespace}/users/{userId}/entitlementsADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT [READ]リクエストが GET /admin/namespaces/accelbyte/users/1234/entitlements 経由でリソースにアクセスしようとする場合、実際に必要なパーミッションは ADMIN:NAMESPACE:accelbyte:USER:1234:ENTITLEMENT [READ] になります。

  • OBJECTNAME: この必須トークンは、PROFILE や CURRENCY などの保護対象リソースオブジェクトを表します。例えば、以下はネームスペース内の通貨を検索するエンドポイントの admin パーミッションです。

    EndpointPermissionDescription
    GET /admin/namespace/{namespace}/currenciesADMIN:NAMESPACE:{namespace}:CURRENCY [READ]パーミッションリソースはコロンで区切って複数のオブジェクト名を含めることができますが、これは推奨されません。

Permission Grant​

IAM クライアントにパーミッションを付与するには、必要な事前定義パーミッションをトグルします。詳細については、IAM クライアントの作成とIAM クライアントパーミッションの追加と編集を参照してください。

Custom permissions​

Extend Service Extensionを使用してカスタム API を作成し、プレイヤーやゲームサーバーにそれへのアクセスを許可したい場合は、IAM クライアントまたはデフォルトのユーザーロールにカスタムパーミッションを追加することもできます。

  • AGS Public Cloud: カスタムパーミッションは、CUSTOM: プレフィックスを付けた事前定義の形式に従う必要があります。これにより、AGS の組み込みパーミッションやスタジオ間アクセスとの競合を防ぎます。詳細については、Public Cloud のカスタムパーミッションを参照してください。
  • AGS Private Cloud: カスタムパーミッションに CUSTOM: プレフィックスは不要です。Granted permission syntaxの構文に従う任意のパーミッションリソースを使用できます。

Granted permission syntax​

以下は、4 つの個別のトークンを含む付与済みパーミッションのテンプレートです。

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

  • ADMIN: これは ADMIN エンドポイントのパーミッション要件と同じです。管理リソースのパーミッションにはこれを前置する必要があります。例えば、ロールの CRUD（Create、Read、Update、Delete）に対する admin パーミッションです。

    PermissionDescription
    ADMIN:ROLE [CREATE] | [READ] | [UPDATE] | [DELETE]アクション間のロジックはビット単位の OR (|) です。

  • NAMESPACE:{namespace}: 任意項目です。リソースがネームスペースレベルに属する場合にのみ使用します。

    構文は NAMESPACE: の後に、ネームスペース名のプレースホルダー {namespace}、*(ワイルドカード)、または特定のネームスペース名が続きます。

    • {namespace}: この値は、バックエンドに対してユーザーまたはアプリケーションに付与されたネームスペースへ動的に解決するよう指示します。つまり、そのネームスペースに対応するパーミッションを持つクライアントおよびユーザーは、特定のネームスペース内のリソースのみを使用できます。例えば、以下は、システムがユーザーアカウントやアプリケーションに付与するネームスペース内で IAM クライアントを作成するためのアクセスを許可するパーミッションです。

      PermissionDescription
      ADMIN:NAMESPACE:{namespace}:CLIENT [CREATE]システムはアスタリスク (*) をワイルドカードとして解釈し、すべてのネームスペースでそのリソースへのアクセスを許可します。例えば、以下は任意のネームスペースで IAM クライアントを作成するためのアクセスを許可するパーミッションです: ADMIN:NAMESPACE:*:CLIENT

    • 特定のネームスペース名: ネームスペースを指定する場合（例: NAMESPACE:namespace_A）、システムはその特定のネームスペース内のリソースに対してのみパーミッションを付与します。スーパー管理者はこれを利用して、特定のゲームネームスペースのリソースに限定した管理アクセス権をカスタマーサポートユーザーに付与する方法を提供できます。

      PermissionDescription
      ADMIN:NAMESPACE:namespace_A:CLIENT [CREATE]このパーミッションは、特定のネームスペース（namespace_A）内でのみ IAM クライアントを作成するアクセスを許可します。

  • USER:userId: これは任意項目であり、ユーザー固有のリソースにのみ使用してください。

    構文は USER: の後に、ユーザー ID のプレースホルダー {userId} またはワイルドカードのアスタリスクが続きます。

    • {userId}: この値は、バックエンドに対してログイン中のユーザーの ID に動的にバインドし、{userId} を実際のユーザー ID に置き換えるよう指示します。つまり、対応するパーミッションを付与されたクライアントおよびユーザーは、特定のユーザーに属するリソースを使用できます。例えば、以下は任意のネームスペースでログイン中のユーザーのエンタイトルメントを検索するアクセスを許可するパーミッションです。

      PermissionDescription
      ADMIN:NAMESPACE:*:USER:{userId}:ENTITLEMENT [READ]システムはアスタリスク (*) をワイルドカードとして解釈し、任意のユーザーに属するリソースへのアクセスを許可します。例えば、以下は任意のネームスペースで任意のユーザーのエンタイトルメントを検索するアクセスを許可するパーミッションです: ADMIN:NAMESPACE:*:USER:*:ENTITLEMENT [READ]。

  • OBJECTNAME: これは ADMIN エンドポイントのパーミッション要件とほぼ同じです。ここでの構文は、特定のオブジェクト名またはワイルドカードのアスタリスクのいずれかです。

    • 特定のオブジェクト名: 保護対象リソースオブジェクトを表します。例えば、以下は特定のネームスペース内の特定のユーザーに属するプロフィールを検索するアクセスを許可するパーミッションです。

      PermissionDescription
      ADMIN:NAMESPACE:{namespace}:USER:{userId}:PROFILE [READ]すべてのリソースオブジェクトへのアクセスを許可したい場合は、オブジェクト名をワイルドカード (*) のアスタリスクに置き換えます。例えば、以下は任意のネームスペースでログイン中のユーザーのすべての情報を検索するアクセスを許可するパーミッションです: ADMIN:NAMESPACE:*:USER:{userId}:* [READ]

Troubleshooting​

このセクションでは、サービスを使用する際に発生する可能性のあるエラーや問題を一覧で示します。

各 AGS エンドポイントに必要なパーミッションを確認する方法​

各エンドポイントに必要なパーミッションが記載されているAPI エンドポイントのドキュメントを参照してください。

パーミッションに関連するエラーを解決する方法​

Resources セクションのエラーと例外を確認してください。

What's next?​

ユーザーロールの管理方法とIAM クライアントの管理方法を学びましょう。

に最終更新
On this page