ルートボックスロールのカスタマイゼーションを開始する

Last updated on September 15, 2026

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

注記

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

Overview​

AccelByte Gaming Services (AGS) では、プレイヤーがルートボックスを開封する際のさまざまな要件に応じて、カスタムロジックを実装できます。

この記事では、Extend Override アプリテンプレートを例に、カスタムのルートボックスロールロジックを設定する手順を説明します。

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

    • Postman から利用可能なバイナリを使用してください。

    f. extend-helper-cli

    g. TCP フォワーディング機能を持つローカルトンネルサービス。例:

  1. AGS Admin Portal 環境へのアクセス。
    • ベース URL: <your environment's domain URL>
      • AGS Public Cloud カスタマーの例: https://spaceshooter.prod.gamingservices.accelbyte.io
      • AGS Private Cloud カスタマーの例: https://dev.customer.accelbyte.io
    • まだ持っていない場合は、ゲームネームスペースを作成します。ネームスペース ID を控えておきます。
    • confidential クライアントタイプで OAuth クライアントを作成します。Client ID と Client Secret を保管しておきます。

Clone the app template​

git clone https://github.com/AccelByte/lootbox-roll-function-grpc-plugin-server-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     # Base URL of AGS environment
    AB_CLIENT_ID='xxxxxxxxxx'                 # Client ID from the Prerequisites section
    AB_CLIENT_SECRET='xxxxxxxxxx'             # Client Secret from the Prerequisites section
    AB_NAMESPACE='xxxxxxxxxx'                 # Namespace ID from the Prerequisites section
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # Enable or disable access token validation
    注記

    このアプリでは、PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで true です。false に設定すると、AccelByte Gaming Services のアクセストークンなしで gRPC server を呼び出すことができます。このオプションは開発目的のみで提供されています。本番環境では gRPC server のアクセストークン検証を有効にすることをお勧めします。

Build the Extend app​

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

make build

Run the Extend app​

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

docker compose up --build

Test the Extend app​

Extend アプリは、ローカル開発環境または AGS を使ってテストできます。

Test in a local development environment​

important

テストを行う前に、PLUGIN_GRPC_SERVER_AUTH_ENABLED が false に設定されていることを確認してください。設定されていない場合、gRPC リクエストは gRPC server によって拒否されます。

このアプリのカスタム関数は、Postman を使用してローカルでテストできます。Postman を使って Extend アプリをテストするには、以下の手順に従います。

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

    docker compose up --build

  2. Postman で新しい gRPC リクエストを作成し、サーバー URL として localhost:6565 を入力します。詳細については、Postman の gRPC サポートに関するガイドを参照してください。

  3. 続けて LootBox/RollLootBoxRewards メソッドを選択し、以下のサンプルメッセージで呼び出します。

    {
       "userId": "b52a2364226d436285c1b8786bc9cbd1",
       "namespace": "accelbyte",
       "quantity": 10,
       "itemInfo": {
          "itemId": "8a0b8bda28c845f6938cc57540af452e",
          "itemSku": "SKU3170",
          "rewardCount": 2,
          "lootBoxRewards": [
                {
                   "name": "Foods",
                   "type": "REWARD",
                   "weight": 5,
                   "odds": 0,
                   "items": [
                      {
                            "itemId": "8b6016d243264c0f90031600313b8a37",
                            "itemSku": "SKU4650",
                            "count": 5
                      }                 
                   ]
                },
                {
                   "name": "Beverages",
                   "type": "REWARD",
                   "weight": 4,
                   "odds": 0,
                   "items": [
                      {
                            "itemId": "dd81bbc3d9fd413daecfd0d0e53fc095",
                            "itemSku": "SKU1939",
                            "count": 13
                      }            
                   ]
                },
                {
                   "name": "Specials",
                   "type": "REWARD",
                   "weight": 1,
                   "odds": 0,
                   "items": [
                      {
                            "itemId": "3318d5fe505a4891b6b5a70586b294ca",
                            "itemSku": "SKU1739",
                            "count": 21
                      }
                   ]
                }
          ]
       }
    }

    成功すると、レスポンスにロールされたリワードが表示されます。

    {
       "rewards": [
          {
             "itemId": "8b6016d243264c0f90031600313b8a37",
             "itemSku": "SKU4650",
             "count": 5
          },
          ...      
       ]
    }

Test with AGS​

ローカルで実行されているアプリを AGS でテストするには、gRPC server がインターネットに接続されている必要があります。パブリック IP を用意せずにこれを行うには、ローカルトンネルサービスを使用できます。

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

    docker compose up --build

  2. ローカル開発環境の gRPC server の TCP ポート 6565 をインターネットに公開します。最も簡単な方法は、ローカルトンネルサービスプロバイダーを使用することです。

    • ngrok にサインインし、ngrok ダッシュボードから authtoken を取得してローカル環境に設定します。 そして、gRPC server を公開するには、以下のコマンドを使用します。

      ngrok tcp 6565

    • または、pinggy を使用して、ssh コマンドラインのみで簡単なトンネルを設定することもできます。 その場合、gRPC server を公開するには、以下のコマンドを使用します。

      ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:6565 tcp@a.pinggy.io

    トンネルのフォワーディング URL（例: http://0.tcp.ap.ngrok.io:xxxxx や tcp://xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx）を控えておいてください。

    備考

    gRPC server ポート（TCP）をインターネットに公開するために、他のローカルトンネルサービスや別の方法を使用することもできます。

  3. Admin Portal で、この設定に対応する正しいネームスペースに移動し、以下の手順を行います。

    1. サイドバーメニューで、Online > Store & Catalog > Customization > Loot Box Roll に移動します。
    2. 表示された Customization ページで、Add Configuration ボタンをクリックします。
    3. Add Configuration のポップアップで、Locally hosted (for testing purpose) オプションを選択し、手順3のトンネルフォワーディング URL を入力します。その後、Create をクリックします。

  4. confidential クライアントタイプで、以下の権限を含む OAuth クライアントを作成します。

    • AGS Private Cloud カスタマーの場合:
      • ADMIN:NAMESPACE:{namespace}:PLUGIN:CATALOG [READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:STORE [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:CATEGORY [CREATE]
      • ADMIN:NAMESPACE:{namespace}:CURRENCY [READ,CREATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:ITEM [READ,CREATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:USER:*:ENTITLEMENT [READ,CREATE,UPDATE,DELETE]
    • AGS Public Cloud カスタマーの場合:
      • Platform Store > Service Plugin Config (Read, Update, Delete)
      • Platform Store > Store (Read, Create, Update, Delete)
      • Platform Store > Category (Create)
      • Platform Store > Currency (Read, Create, Delete)
      • Platform Store > Item (Read, Create, Delete)
      • Platform Store > Entitlement (Read, Create, Update, Delete)
    important
    • Client ID と Client Secret のコピーを保管してください。
    • この手順で作成した OAuth クライアントは、Prerequisites セクションで言及したものとは異なります。これは、次の手順の Postman コレクションが gRPC Server の URL を登録し、テストユーザーの作成・削除を行うために必要です。

  5. 前の手順の Client ID と Client Secret を使用して環境を設定するために、Postman コレクション（demo/lootbox-roll-function-demo.postman_collection.json）の概要にある手順に従ってください。Extend アプリのフローが実行されている際は、このアプリのコンソールログに注意してください。コレクション内のすべてのリクエストを実行すると、少なくとも1つの gRPC Server メソッドが呼び出されるはずです。

Deploy in AGS​

AGS で Extend アプリをデプロイするには、Admin Portal で以下の手順を行います。

  1. Extend アプリを作成する。
  2. Extend アプリをアップロードする。
  3. Extend アプリを設定する。
  4. Extend アプリをデプロイする。
  5. AGS が Extend アプリを使用するように設定する。

Create the Extend app​

  1. AGS Admin Portal で、Extend Override アプリを作成したいネームスペースに移動します。
  2. サイドバーメニューの ADD-ONS の下にある Extend > Override に移動します。
  3. Overridable Features ページで、+ Create New ボタンをクリックします。
  4. Create App フォームで、Extend アプリの名前と説明（任意）を入力します。
  5. Create をクリックします。新しい Extend アプリが Overridable Features のアプリ一覧に追加されます。

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）
    # Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
    export AB_BASE_URL='https://xxxxxxxxxx'
    # Client ID of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_ID='xxxxxxxxxx'     
    # Client Secret of OAuth Client for extend-helper-cli (from step 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 のイメージが表示されます。

    image history in AGS Admin Portal

Configure the Extend app​

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

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
warning

Extend Override アプリがリリース v2024.02.13 より前のテンプレートに基づいている場合は、PLUGIN_GRPC_SERVER_AUTH_ENABLED 環境変数を必ず true に設定してください。設定しない場合、Extend アプリのアクセストークン検証が無効になり、有効なアクセストークンがなくても Extend アプリにアクセスできる可能性があります。

リリース v2024.02.13 以降、Extend Override アプリテンプレートの PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで true に設定されています。アクセストークン検証は、PLUGIN_GRPC_SERVER_AUTH_ENABLED が明示的に false に設定されている場合にのみ無効化できます。これに合わせて、Admin Portal から作成されるすべての新しい Extend アプリでは、PLUGIN_GRPC_SERVER_AUTH_ENABLED 環境変数はデフォルトでは設定されません。以前は、Admin Portal から作成されたすべての新しい Extend アプリに PLUGIN_GRPC_SERVER_AUTH_ENABLED=false が追加されていました。

Deploy the Extend app​

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

Set AGS to use the Extend app​

Admin Portal で、Online > Store & Catalog > Customization > Loot Box Roll に移動します。Overridden by セクションの編集（鉛筆）ボタンをクリックして、既存の設定を編集します。

click to edit the overridden by option

AccelByte hosted オプションを選択し、今デプロイした Extend アプリを選択します。Save をクリックして完了します。

choose an AccelByte hosted extend apps

Next step​

Extend Override アプリテンプレートを変更して、独自のカスタムロジックを実装してください。詳細については、こちらを参照してください。

に最終更新
On this page