Service Extension アプリを使い始める

Last updated on July 15, 2026

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

Overview​

この記事では、Extend Service Extension アプリのセットアップ方法について説明します。ここでは、Extend Service Extension アプリテンプレートを使用します。このアプリテンプレートには、ギルドの進行状況データを作成・取得する 2 つのエンドポイントを持つカスタムギルドサービスの例が含まれています。

前提条件​

  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:ROLE [READ]
        • ADMIN:NAMESPACE:{namespace}:NAMESPACE [READ]
        • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
      • AGS Public Cloud 顧客の場合:
        • IAM > Roles (Read)
        • Basic > Namespace (Read)
        • Cloud Save > Game Records (Create, Read, Update, and Delete)

      Client ID と Client Secret を保管しておいてください。

アプリテンプレートをクローンする​

git clone https://github.com/AccelByte/extend-service-extension-csharp

Extend アプリのセットアップ、実行、テスト​

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

Extend アプリをセットアップする​

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

  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'                 # 前提条件セクションからのネームスペース ID
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # アクセストークン検証の有効化または無効化
    BASE_PATH='/guild'                        # アプリで使用されるベースパス
    注記
    • このアプリでは、PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで true です。false に設定すると、gRPC server は AccelByte Gaming Services のアクセストークンなしで呼び出すことができます。このオプションは開発目的のみに提供されています。本番環境では gRPC server のアクセストークン検証を有効にすることを推奨します。
    • BASE_PATH に設定する環境変数によって、ローカル開発時のサービス URL は異なり、次の形式に従います: http://localhost:8000/<base_path>。

Extend アプリをビルドする​

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

make build

Extend アプリを実行する​

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

docker compose up --build

さらに、コンテナ外でプロジェクトを実行することも可能です。

プロジェクトのトップレベルディレクトリで、以下のコマンドを使用して gRPC サーバーを実行します。

cd src
dotnet run

次に、別のターミナルで、同じくプロジェクトのトップレベルディレクトリで、以下のコマンドを使用して gRPC ゲートウェイを実行します。

make run_gateway
注記

Windows ファイルシステムで Visual Studio を使用して開発している場合は、ソリューション src/plugin-arch-service-extension-grpc-server.sln を開き、以下に示すようにデバッグプロパティを設定することで環境変数を構成し、gRPC サーバーを実行することもできます。スタートアッププロジェクトとして AccelByte.PluginArch.ServiceExtension.Demo.Server を必ず設定してください。

VS2022 debug properties

モーダルが表示されたら、以下に示すように環境変数の設定を開始できます。モーダルを閉じて変更を適用・保存してください。

VS2022 edit env vars

Extend アプリをテストする​

PLUGIN_GRPC_SERVER_AUTH_ENABLED が true の場合、REST API エンドポイントを呼び出すためにアクセストークンが必要になります。curl を使用してクライアントクレデンシャルトークンを取得します:

注記

以下のコマンドは bash 構文を使用しており、bash シェル（Linux、macOS、または Windows WSL2、いずれも前提条件として既に記載）が必要です。PowerShell または CMD では動作しません。

ACCESS_TOKEN=$(curl -s -X POST "${AB_BASE_URL}/iam/v3/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "${AB_CLIENT_ID}:${AB_CLIENT_SECRET}" \
  -d "grant_type=client_credentials" | jq -r .access_token)
注記

IAM クライアントに以下の権限があることを確認してください:

  • AGS Private Cloud 顧客の場合:
    • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
  • AGS Public Cloud 顧客の場合:
    • Cloud Save > Game Records (Create, Read, Update, and Delete)

オプション 1: Curl を使用する​

注記

<accessToken> を上記で取得したトークンに、<your-namespace> をあなたのネームスペース ID に置き換えてください。デフォルトの BASE_PATH=/guild の場合、ベース URL は http://localhost:8000/guild です。

CreateOrUpdateGuildProgress エンドポイントをテストします。

$ curl -X 'POST' \
  'http://localhost:8000/<base_path>/v1/admin/namespace/<your-namespace>/progress' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "guildProgress": {
    "guildId": "123456789",
    "namespace": "<your-namespace>",
    "objectives": {
      "target1": 0
    }
  }
}'

次に、GetGuildProgress エンドポイントをテストします。

$ curl -X 'GET' \
  'http://localhost:8000/<base_path>/v1/admin/namespace/<your-namespace>/progress/123456789' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <accessToken>'

レスポンスに更新されたギルドの進行状況が表示されます。

オプション 2: Swagger UI を使用する​

http://localhost:8000/<base_path>/apidocs/（末尾のスラッシュが必要です）で自動生成された Swagger UI を開きます。デフォルトの BASE_PATH=/guild の場合、これは http://localhost:8000/guild/apidocs/ になります。

PLUGIN_GRPC_SERVER_AUTH_ENABLED が true の場合、Authorize ボタンをクリックして、上記で取得したアクセストークンで認証してください。

Guild service swagger interface

表示されたポップアップで、Bearer (apiKey) の Value フィールドに Bearer <accessToken> と入力します。次に、Authorize ボタンをクリックします。

Guild service swagger authorization

最後に、CreateOrUpdateGuildProgress エンドポイントと GetGuildProgress エンドポイントのテストを進めます。

important

ローカルでテストする場合は、Swagger UI の Schemes オプションで HTTPS ではなく HTTP が選択されていることを確認してください。 そうしないと、エンドポイントをテストする際にネットワーク転送エラーが発生します。

AGS にデプロイする​

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

  1. Extend アプリを作成する。
  2. Extend アプリをアップロードする。
  3. Extend アプリを設定する。
  4. Extend アプリをデプロイする。

Extend アプリを作成する​

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

Extend アプリをアップロードする​

  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 のイメージが表示されます。

    image history in AGS Admin Portal

Extend アプリを設定する​

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

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
warning

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

リリース v2024.02.13 以降、Extend Service Extension アプリテンプレートの 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 が追加されていました。

Extend アプリをデプロイする​

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

デプロイされた Extend アプリをテストする​

<Service URL>/apidocs で Swagger UI を開きます。Service URL を使用するか、Extend アプリの詳細ページで Open API Documentation ボタンをクリックします。

Image shows the Service Extension URL

important

デプロイされた Extend アプリをテストする場合は、Swagger UI の Schemes オプションで HTTP ではなく HTTPS が選択されていることを確認してください。 そうしないと、エンドポイントをテストする際にネットワーク転送エラーが発生します。

次のステップ​

Extend Service Extension アプリテンプレートを変更して、独自のエンドポイントを実装しましょう。詳細については、独自の Extend Service Extension アプリを作成するを参照してください。

に最終更新
On this page