イベントハンドラの使用を開始する

Last updated on September 15, 2026

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

注記

AGS CLI は AGS 向けの統一コマンドラインツールであり、Extend と AMS のツールも含まれるようになりました。このページの手順は現在も有効です。統合ツールの詳細は AGS CLI のドキュメント を参照してください。

Overview​

この記事では、Extend Event Handler アプリのセットアップ方法について説明します。ここでは、Extend Event Handler アプリのテンプレートを使用します。このテンプレートは、AccelByte Gaming Services (AGS) の UserLogin イベントと UserThirdPartyLoggedIn イベントをリッスンし、ユーザーがログインしたときにゲーム内アイテムを付与します。

Prerequisites​

  1. 以下のツールがインストールされた Windows 11 WSL2/Linux Ubuntu 22.04 または macOS 14+ の環境。

    a. Bash

    • Windows WSL2 または Linux Ubuntu の場合:

      bash --version

      GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
      ...

    • macOS の場合:

      bash --version

      GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
      ...

    b. Make

    • Windows WSL2 または Linux Ubuntu の場合:

      Ubuntu リポジトリからインストールするには、sudo apt update && sudo apt install make を実行します。

      make --version

      GNU Make 4.3
      ...

    • macOS の場合:

      make --version

      GNU Make 3.81
      ...

    c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)

    • Linux Ubuntu の場合:

      1. Ubuntu リポジトリからインストールするには、sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。
      2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。
      3. 変更を有効にするため、ログアウトしてから再度ログインします。

    • Windows または macOS の場合:

      Windows または macOS 用の Docker Desktop のインストールに関する Docker のドキュメントに従ってください。

      docker version

      ...
      Server: Docker Desktop
         Engine:
         Version:          24.0.5
      ...

    d. .NET 8 SDK

    • Linux Ubuntu の場合:

      Ubuntu リポジトリからインストールするには、sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0 を実行します。

    • Windows または macOS の場合:

      Windows または macOS への .NET のインストールに関する Microsoft のドキュメントに従ってください。

      dotnet --version

      8.0.119

    e. Postman

    • こちらから入手できるバイナリを使用してください。

    f. extend-helper-cli

    • こちらから入手できるバイナリを使用してください。

  1. AGS Admin Portal 環境へのアクセス。

    • ベース URL: <お使いの環境のドメイン URL>
      • AGS Public Cloud カスタマーの例: https://spaceshooter.prod.gamingservices.accelbyte.io
      • AGS Private Cloud カスタマーの例: https://dev.customer.accelbyte.io
    • まだお持ちでない場合は、ゲームネームスペースを作成してください。ネームスペース ID をメモしておいてください。
    • 以下の権限を含む confidential クライアントタイプの OAuth クライアントを作成してください。
      • AGS Private Cloud カスタマーの場合:
        • ADMIN:NAMESPACE:{namespace}:USER:*:FULFILLMENT [CREATE]
      • AGS Public Cloud カスタマーの場合:
        • Platform Store -> Fulfillment (Create) Client ID と Client Secret を保管しておいてください。

  2. ストアと付与するゲーム内アイテムをセットアップします。

    1. ネームスペースに新しいストアを作成して公開します。既存のストアがある場合はそれを使用することもできます。ストアの作成と公開の詳細については、ストアとエンタイトルメントを参照してください。

      AGS Admin Portal 内のストア

    2. ストアの作成と公開が完了したら、ユーザーがログインしたときに付与したい、公開済みストア内のゲーム内 Item ID をメモしておいてください。

      AGS Admin Portal 内の公開済みアイテム

Clone the app template​

git clone https://github.com/AccelByte/extend-event-handler-csharp.git

Set up, run, and test an Extend app​

このセクションでは、Extend アプリのセットアップ、ビルド、実行、およびテストの方法について説明します。

Set up the Extend app​

このアプリを実行できるようにするには、以下のセットアップ手順に従ってください。

  1. .env.template ファイルの内容をコピーして、docker compose の .env ファイルを作成します。

    注記

    ホスト OS の環境変数は、.env ファイルの変数よりも優先されます。.env ファイル内の変数が正しく反映されない場合は、同じ名前のホスト OS の環境変数が存在するかどうかを確認してください。詳細については、docker compose の環境変数の優先順位に関する Docker のドキュメントを参照してください。

  2. 以下のように、.env ファイルに必要な環境変数を入力します。

    AB_BASE_URL=https://test.accelbyte.io     # AGS 環境のベース URL
    AB_CLIENT_ID='xxxxxxxxxx'                 # 前提条件セクションで取得した Client ID
    AB_CLIENT_SECRET='xxxxxxxxxx'             # 前提条件セクションで取得した Client Secret
    AB_NAMESPACE='xxxxxxxxxx'                 # 前提条件セクションで取得した Namespace ID
    ITEM_ID_TO_GRANT='xxxxxxxxxx'             # 事前にメモした公開済みストアのゲーム内アイテム ID

Build the Extend app​

このアプリをビルドするには、以下のコマンドを実行します。

make build

Run the Extend app​

このアプリをコンテナ内で（ビルドして）実行するには、以下のコマンドを実行します。

docker compose up --build

Test the Extend app​

このアプリは、Postman を使用してローカルでテストできます。

  1. 以下のコマンドを使用してこのアプリを実行します。

    docker compose up --build

  2. Postman を開き、新しい gRPC request を作成し、URL に localhost:6565 を入力します。

    Postman の新しい grpc リクエスト

  3. UserLogin イベントに注目しているため、UserAuthenticationUserLoggedInService/OnMessage メソッドを選択します。

    Postman の新しい grpc リクエスト

  4. 以下のサンプル Kafka イベント JSON をコピーして貼り付け、少なくとも namespace と userId を有効な値に置き換え、Invoke をクリックして、gRPC サーバーに UserLogin イベントを送信します。

    {
      "payload": {
         "user_account": {
            "user_id": "string",
            "email_address": "string",
            "country": "string",
            "namespace": "string"
         },
         "user_authentication": {
            "platform_id": "string",
            "refresh": true
         }
      },
      "id": "string",
      "version": 0,
      "name": "string",
      "namespace": "string",
      "parent_namespace": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "client_id": "string",
      "user_id": "string",
      "trace_id": "string",
      "session_id": "string"
    }

  5. 成功すると、以下のようなレスポンスが表示され、このテストで使用しているユーザーにゲーム内アイテムが付与されていることも確認できます。

    Postman の新しい grpc リクエスト

    付与されたエンタイトルメント

  6. UserThirdPartyLoggedIn イベントでも同様の手順を行うには、UserAuthenticationUserThirdPartyLoggedInService/OnMessage を選択し、以下のサンプル Kafka イベント JSON を使用します。ここでも、少なくとも namespace と userId の有効な値が必要です。

    {
       "payload": {
          "userAccount": {
             "userId": "string",
             "emailAddress": "string",
             "userName": "string",
             "country": "string",
             "namespace": "string",
             "platformId": "string",
             "displayName": "string"
          },
          "userAuthentication": {
             "platformId": "string",
             "refresh": true,
             "platformUserId": "string",
             "simultaneousPlatformId": "string",
             "simultaneousPlatformUserId": "string"
          },
          "loginLocation": {
             "country": "string",
             "state": "string",
             "city": "string"
          }
       },
       "id": "string",
       "version": 0,
       "name": "string",
       "namespace": "string",
       "parentNamespace": "string",
       "timestamp": "2019-08-24T14:15:22Z",
       "clientId": "string",
       "userId": "string",
       "traceId": "string",
       "sessionId": "string"
    }

Deploy in AGS​

Create the Extend app​

  1. AGS Admin Portal で、Extend Event Handler アプリを作成したい namespace に移動します。

  2. サイドバーメニューで Extend にカーソルを合わせ、Event Handler をクリックします。Create New をクリックして、新しい Extend Event Handler アプリを作成します。

  3. アプリ作成ページで、App Name と Description を入力します。必要に応じてリソース設定を調整できます。その後、Create をクリックします。

Upload the Extend app​

  1. extend-helper-cli 用の IAM クライアントをセットアップします。クライアントタイプ confidential の IAM クライアントを作成し、以下に示す必要な権限を割り当てます。Client ID と Client Secret のコピーを保管しておいてください。

    • AGS Private Cloud カスタマーの場合:
      • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
      • ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ]
    • AGS Public Cloud カスタマーの場合:
      • Extend > Extend app image repository access (Read)
      • Extend > App (Read)

  2. 必要な環境変数をエクスポートし、extend-helper-cli を使用して Extend アプリのコンテナイメージをビルドして AGS にアップロードします。

    • <project-dir> が Extend アプリのプロジェクトディレクトリを指していることを確認してください
    • <namespace> と <app-name> の値は、Extend アプリの App Detail ページで確認できます
    • 適切なイメージタグを使用してください（例: v0.0.1）
    # AGS 環境のベース URL（例: https://spaceshooter.prod.gamingservices.accelbyte.io、https://dev.accelbyte.io など）
    export AB_BASE_URL='https://xxxxxxxxxx'
    # extend-helper-cli 用の OAuth クライアントの Client ID（ステップ 1 から）
    export AB_CLIENT_ID='xxxxxxxxxx'     
    # extend-helper-cli 用の OAuth クライアントの Client Secret（ステップ 1 から）
    export AB_CLIENT_SECRET='xxxxxxxxxx'

    ./extend-helper-cli-linux_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1
    important
    • 上記のコマンドは、Extend アプリのプロジェクトとは別のターミナルおよび異なる作業ディレクトリで実行することをお勧めします。これにより、extend-helper-cli が誤って Extend アプリ用の環境変数を使用してしまうことを防止できます。
    • 以下のエラーが発生した場合は、解決方法についてトラブルシューティング: Docker のログインに失敗するを参照してください。 
      Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

    イメージが正常にアップロードされると、Image Version History ページに v0.0.1 のバージョンを持つイメージが表示されます。

    AGS Admin Portal 内のイメージ履歴

Configure the Extend app​

アップロードした Extend アプリをデプロイする前に、Extend アプリが必要とする環境変数を設定する必要があります。アプリの詳細ページで、Extend アプリをローカルで実行およびテストする際に使用したものと同じ値を持つ以下の環境変数を設定します。

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
  • ITEM_ID_TO_GRANT

Deploy the Extend app​

Extend アプリをデプロイするには、Deploy Latest Image をクリックします。アプリのステータスが RUNNING に更新されるまで待ちます。これは、Extend アプリが正常にデプロイされたことを示します。

Test the deployed Extend app​

ネームスペース内に新しいユーザーを作成し、そのユーザーでログインします。Admin Portal のそのユーザーのエンタイトルメントページで Item ID が付与されているかを確認します。

付与されたエンタイトルメント

Next steps​

に最終更新
On this page