Cloud Saveバリデータのカスタマイズを始める

Last updated on September 15, 2026

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

注記

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

Overview​

AccelByte Gaming Services（AGS）では、レコードを保存または取得できるかどうかを判断するカスタムクラウドセーブバリデータを実装できます。

この記事では、Extend Override appテンプレートを例として、カスタムクラウドセーブバリデータロジックを設定する手順を説明します。

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環境へのアクセス。
    • Base URL: <お使いの環境のドメイン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/cloudsave-validator-grpc-plugin-server-csharp.git

Set up, run, and test an Extend app​

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

Set up the Extend app​

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

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

    注記

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

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

    AB_BASE_URL=https://test.accelbyte.io     # AGS環境のBase URL
    AB_CLIENT_ID='xxxxxxxxxx'                 # Prerequisitesセクションで取得したClient ID
    AB_CLIENT_SECRET='xxxxxxxxxx'             # Prerequisitesセクションで取得したClient Secret
    AB_NAMESPACE='xxxxxxxxxx'                 # Prerequisitesセクションで取得したNamespace ID
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # アクセストークン検証の有効化/無効化
    注記

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

Build the Extend app​

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

make build

Run the Extend app​

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

docker compose up --build

Test the Extend app​

ローカル開発環境またはAGSでExtend appをテストできます。

Test in a local development environment​

important

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

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

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

    docker compose up --build

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

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

    a. 有効な payload の場合

    {
        "createdAt": {
            "nanos": 10,
            "seconds": "1693468029"
        },
        "isPublic": true,
        "key": "favorite_weapon",
        "namespace": "mynamespace",
        "payload": "eyJ1c2VySWQiOiAiMWUwNzZiY2VlNmQxNGM4NDlmZmIxMjFjMGUwMTM1YmUiLCAiZmF2b3VyaXRlV2VhcG9uVHlwZSI6ICJTV09SRCIsICJmYXZvdXJpdGVXZWFwb24iOiAiZXhjYWxpYnVyIn0=",  // {"userId": "1e076bcee6d14c849ffb121c0e0135be", "favoriteWeaponType": "SWORD", "favoriteWeapon": "excalibur"} をbase64でエンコードしたもの
        "setBy": "SERVER",
        "updatedAt": {
            "nanos": 10,
            "seconds": "1693468275"
        },
        "userId": "1e076bcee6d14c849ffb121c0e0135be"
    }

    レスポンスには以下のように isSuccess: true が含まれます。

    {
        "isSuccess": true,
        "key": "favorite_weapon",
        "userId": "1e076bcee6d14c849ffb121c0e0135be"
    }

    b. 無効な payload の場合

    {
        "createdAt": {
            "nanos": 10,
            "seconds": "1693468029"
        },
        "isPublic": true,
        "key": "favorite_weapon",
        "namespace": "mynamespace",
        "payload": "eyJmb28iOiJiYXIifQ==",  // {"foo":"bar"} をbase64でエンコードしたもの
        "setBy": "SERVER",
        "updatedAt": {
            "nanos": 10,
            "seconds": "1693468275"
        },
        "userId": "1e076bcee6d14c849ffb121c0e0135be"
    }

    レスポンスには以下のように isSuccess: false が含まれます。

    {
        "isSuccess": false,
        "key": "favorite_weapon",
        "userId": "1e076bcee6d14c849ffb121c0e0135be",
        "error": {
            "errorCode": 1,
            "errorMessage": "favorite weapon cannot be empty; favorite weapon type cannot be empty; user ID cannot be empty"
        }
    }

Test with AGS​

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

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

    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サーバーポート（TCP）をインターネットに公開するために、他のローカルトンネルサービスや別の方法を使用することもできます。

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

    1. サイドバーメニューから、Online > Cloud Save > Customization に移動します。

    2. まだ設定を追加していない場合は、Add Configuration をクリックします。

    3. Locally hosted for testing purpose オプションを選択します。前の手順で取得したトンネル転送URLを入力し、Save をクリックします。

      Cloud Saveのオーバーライド可能な設定を追加するモーダルを示す画像

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

    • AGS Private Cloudのお客様の場合:
      • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:PLUGINS [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:USER:*:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
      • NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [DELETE]
    • AGS Public Cloudのお客様の場合:
      • Cloud Save > Custom Configuration（Read、Create、Update、Delete）
      • Cloud Save > Game Records（Read、Create、Update、Delete）
      • Cloud Save > Player Records（Read、Create、Update、Delete）
      • IAM > Users（Delete）
    important
    • Client ID と Client Secret のコピーを保管しておいてください。
    • この手順で作成するOAuthクライアントは、Prerequisitesセクションで説明したものとは別のものです。次のステップのCLIデモappで必要になります。

  5. Extend appのフローをシミュレートするために、Postmanコレクション（demo/cloudsave-validator-demo.postman_collection.json）をインポートします。Extend appフローの実行中は、このappのコンソールログに注目してください。コレクション内のすべてのリクエストを実行すると、少なくとも1つの gRPC Server メソッドが呼び出されるはずです。

    important
    • 前の手順で作成した Client ID と Client Secret を含む、Postman Collection Overview（および/またはGlobal Environment）に必要な環境変数を設定することを忘れないでください。
    • ローカルでホストしているExtend Appをローカルトンネルサービスで公開する場合は、環境変数 GRPC_SERVER_URL（例: 9.tcp.ap.ngrok.io:99999 や xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx）を設定する必要があります。また、Extend AppをAccelByte Gaming Servicesにデプロイした場合は EXTEND_APP_NAME を設定する必要があります。

Deploy in AGS​

AGSでExtend appをデプロイするには、Admin Portalで以下の手順が必要です。

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

Create the Extend app​

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

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イメージリポジトリアクセス（Read）
      • Extend > App（Read）

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

    • <project-dir> がExtend appのプロジェクトディレクトリを指していることを確認してください
    • <namespace> と <app-name> の値は、Extend appの App Detail ページで確認できます
    • 適切なイメージタグ（例: v0.0.1）を使用してください
    # AGS環境のBase 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 appプロジェクトとは別のターミナルおよび異なる作業ディレクトリで実行することをお勧めします。これにより、extend-helper-cliがExtend app用の環境変数を誤って使用してしまうことを防げます。
    • 以下のエラーが発生した場合は、解決手順についてトラブルシューティング: 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 appをデプロイする前に、Extend appが必要とする環境変数を設定する必要があります。app詳細ページで、Extend appをローカルで実行・テストする際に使用した値と同じ値で以下の環境変数を設定します。

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
warning

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

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

Deploy the Extend app​

Extend appをデプロイするには、Deploy Latest Image をクリックします。app状態が RUNNING に更新されるまで待ちます。これはExtend appが正常にデプロイされたことを示します。

Set AGS to use the Extend app​

Admin Portalで、Cloud Saveのカスタマイズを更新します。Overridden by セクションに移動して既存の設定を編集します。

オーバーライドされた詳細を含むExtend Appの詳細ページを示す画像

AccelByte hosted オプションを選択し、Extend appのいずれかを選択します。完了するには Save をクリックします。

app設定を編集するモーダルを示す画像

Next step​

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

に最終更新
On this page