Service Extension アプリを使い始める

Last updated on February 4, 2026

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

概要​

この記事では、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 Shared 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 Shared 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'                 # 前提条件セクションのNamespace ID
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # アクセストークン検証の有効化または無効化
    BASE_PATH='/guild'                        # アプリに使用されるベースパス
    注記
    • このアプリでは、PLUGIN_GRPC_SERVER_AUTH_ENABLEDはデフォルトでtrueです。falseに設定すると、gRPCサーバーはAccelByte Gaming Servicesのアクセストークンなしで呼び出すことができます。このオプションは開発目的でのみ提供されています。本番環境ではgRPCサーバーのアクセストークン検証を有効にすることを推奨します。
    • 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
注記

Visual StudioでWindowsファイルシステムで開発している場合は、ソリューション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エンドポイントにアクセスするにはクライアントユーザートークンまたはユーザーアクセストークンが必要です。その後、demoディレクトリにあるget-access-token.postman_collection.json Postmanコレクションを使用してアクセストークンを生成できます。PostmanコレクションをPostmanワークスペースにインポートし、以下の変数を含むPostman環境を作成します。

  • AB_BASE_URL 例：https://test.accelbyte.io
  • AB_CLIENT_ID confidential IAM OAuthクライアントID
  • AB_CLIENT_SECRET 対応するconfidential IAM OAuthクライアントシークレット
  • AB_USERNAME ユーザーのユーザー名またはメールアドレス（ユーザートークン用）
  • AB_PASSWORD 対応するユーザーパスワード（ユーザートークン用）

Postmanコレクション内で、get-client-access-tokenリクエストを使用してクライアントトークンを取得するか、get-user-access-tokenリクエストを使用してアクセストークンを取得します。

注記

クライアントアクセストークンを使用する場合は、IAMクライアントに以下の権限があることを確認してください：

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

ユーザーアクセストークンを使用する場合は、ユーザーアカウントが必要です。新しいユーザーを作成するか、既存のユーザーを使用できます。ユーザーが以下の権限を含むロールを持っていることを確認してください：

  • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]

オプション1：Curlを使用​

注記

<accessToken>をget-user-access-token.postman_collection.json Postmanコレクションから取得したユーザーアクセストークンに置き換えてください。

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を使用​

自動生成されたSwagger UIをhttp://localhost:8000/<base_path>/apidocsで開きます。

PLUGIN_GRPC_SERVER_AUTH_ENABLEDがtrueの場合は、Authorizeボタンをクリックしてユーザーアクセストークンを設定します。

Guild service swagger interface

表示されるポップアップで、Bearer (apiKey)のValueフィールドに**Bearer ユーザーのアクセストークン**と入力します。次に、Authorizeボタンをクリックします。

Guild service swagger authorization

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

important

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

AGSへのデプロイ​

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

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

Extendアプリの作成​

  1. AGS Admin Portalで、Extend Overrideアプリを作成したいネームスペースに移動します。
  2. サイドバーメニューのADD-ONSの下で、Extend > 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 Shared 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オプションでHTTPS（HTTPではなく）が選択されていることを確認してください。 そうしないと、エンドポイントのテスト時にネットワークトランスポートエラーが発生します。

次のステップ​

Extend Service Extensionアプリテンプレートを変更して、独自のエンドポイントを実装してください。詳細については、こちらを参照してください。

に最終更新
On this page