Extend Helper CLI

Last updated on July 14, 2026

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

概要

Extend Helper CLIを使用すると、AccelByte Gaming Services（AGS）プラットフォーム上でExtendアプリコンテナを作成、デプロイ、管理でき、開発ワークフローを効率化できます。

この記事では、開発環境でExtendアプリを管理するために、Extend Helper CLIをインストールして使用する方法について説明します。

前提条件

Docker（Docker Desktop 4.30以降 / Docker Engine v23.0以降）
- Linuxの場合:
  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
```
AGS環境へのアクセス。Base URL を控えておいてください。
- AGS Public Cloudの例: https://spaceshooter.prod.gamingservices.accelbyte.io
- AGS Private Cloudの例: https://dev.customer.accelbyte.io
次の権限を持つconfidentialクライアントタイプで OAuthクライアントを作成します。Client ID と Client Secret を書き留めておいてください。
- AGS Private Cloudの場合、次の権限を追加します。
  1. ADMIN:NAMESPACE:{namespace}:EXTEND:APP [CREATE, READ, UPDATE, DELETE]
  2. ADMIN:NAMESPACE:{namespace}:EXTEND:DEPLOYMENT [CREATE]
  3. ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
  4. ADMIN:NAMESPACE:{namespace}:EXTEND:SECRET [CREATE, READ, UPDATE]
  5. ADMIN:NAMESPACE:{namespace}:EXTEND:VARIABLE [CREATE, READ, UPDATE]
- AGS Public Cloudの場合、次の権限グループにチェックを入れます。
  1. Extend > App Management: Read、Create、Update、Delete
  2. Extend > Configuration Secret Management: Read、Create、Update
  3. Extend > Configuration Variable Management: Read、Create、Update
  4. Extend > Deployment Management: Create
  5. Extend > Extend app image repository access: Read
警告
AGS Public Cloudユーザー向け: 上記に記載されている権限のみを持つ、Extend Helper CLI専用のOAuthクライアントを作成してください。権限が多すぎるOAuthクライアントを使用すると、CLIからのHTTPリクエストが 「Request Header or Cookie Too Large」 エラーによりサーバーから拒否されることがあります。

インストール

Extend Helper CLI GitHub ページにアクセスし、お使いのオペレーティングシステム用の最新の実行ファイルをダウンロードします。
ダウンロードが完了したら、ターミナルから直接実行ファイルを実行できます。
実行ファイルに実行権限を追加する必要がある場合があります。
- Linuxの場合:
```
chmod +x extend-helper-cli-<variant>
```
- macOSの場合:
```
chmod +x extend-helper-cli-<variant>
```
  chmod +x を実行した後でもOSによってブロックされる場合があり、セキュリティ設定を上書きする必要があります。トラブルシューティング情報については、Appleの Macユーザガイドを参照してください。
- Windowsの場合:
```
icalcs extend-helper-cli-<variant> /grant <your-username>:F
```

セットアップ

extend-helper-cli を使用するには、AGS環境用の環境変数を設定する必要があります。これは、.env ファイルを作成する方法、または変数を直接エクスポートする方法のいずれかで行うことができます。

オプション1: `.env` ファイルを使用する

extend-helper-cli 実行ファイルと同じディレクトリに、.env という名前のファイルを作成します。
次の行を .env ファイルに追加し、プレースホルダーの値を実際の認証情報に置き換えます。
```
AB_BASE_URL=<your_base_url>
AB_CLIENT_ID=<your_client_id>
AB_CLIENT_SECRET=<your_client_secret>
```

オプション2: 環境変数をエクスポートする

ターミナルから値を直接エクスポートします。

export AB_BASE_URL=<your_base_url>
export AB_CLIENT_ID=<your_client_id>
export AB_CLIENT_SECRET=<your_client_secret>

環境変数が設定されると、extend-helper-cli を使用する準備が整います。

使用方法

Extend Helper CLIで使用可能なコマンドを表示するには、次のコマンドを実行します。

extend-helper-cli help

Extend Helper CLIのヘルプ情報:

NAME:
   extend-helper-cli - AccelByte Docker Image Upload Helper CLI Tool (Default Base URL: https://dev.customer.accelbyte.io)

USAGE:
   extend-helper-cli [global options] command [command options] [arguments...]

COMMANDS:
   dockerlogin    Generate docker login credentials.
   image-upload   Build and upload a docker image.
   get-app-info   Get app information.
   <more...>
   help, h        Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

Extendアプリの作成

create-app コマンドを使用してExtendアプリを作成します。

extend-helper-cli create-app --namespace <my-game-namespace> --app <my-extend-app> --scenario service-extension --confirm

サンプルレスポンス

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "",
  "appRepoUrl": "",
  "basePath": "xxx-xxxx-xxxx",
  "CPU": {
    "cpuLimit": 1550,
    "requestCPU": 1000
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "deletedAt": "",
  "deploymentCreatedAt": "",
  "deploymentId": "",
  "deploymentImageTag": "",
  "memory": {
    "memoryLimit": 3300,
    "requestMemory": 350
  },
  "message": "",
  "replica": {
    "maxReplica": 10,
    "minReplica": 1,
    "replicaLimit": 60
  },
  "scenario": "service-extension",
  "servicePublicURL": "https://xxxx.accelbyte.io/xxx-xxxx-xxxx",
  "serviceURL": "",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

--wait を --wait-interval <seconds>（デフォルト: 10）および --wait-limit <seconds>（デフォルト: 300）と併用すると、アプリがイメージのアップロードやデプロイの準備が整うまで待機できます。

extend-helper-cli create-app --namespace <my-game-namespace> --app <my-extend-app> --scenario service-extension --confirm --wait

Extendアプリ情報の取得

get-app-info コマンドを使用して、特定のExtendアプリの情報を取得します。

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app>

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "arn:aws:ecr:xxxxxxxxx:xxxxxxxxxxxx:xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appRepoUrl": "xxxx.xxxx.xxxx.xxxxxxxxx.xxxx.xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appStatus": "app-undeployed",
  "app_release_status": "U",
  "basePath": "xxx-xxxx-xxxx",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "scenario": "service-extension",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

特定のフィールドのみを照会したい場合は、--path を使用し、有効な JSONポインタを渡します。

例えば、appName のみを取得する場合:

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app> --path /appName

別の例として、appRepoUrl のみを取得する場合:

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app> --path /appRepoUrl

Extendアプリコンテナイメージをプッシュするための認証情報の取得

dockerlogin コマンドを使用して、Extendアプリコンテナイメージをプッシュするために必要な認証情報を取得します。

extend-helper-cli dockerlogin --namespace <my-game-namespace> --app <my-extend-app> --login

サンプルレスポンス

INFO[0000] signing in to https://dev.accelbyte.io 
INFO[0001] getting docker credentials...                
WARNING! Your password will be stored unencrypted in /home/xyz-abc/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

警告

この認証情報は、特定のゲームネームスペースとExtendアプリでのみ使用できます。 別のゲームネームスペースやExtendアプリを使用する場合は、このコマンドを再度実行する必要があります。

Extendアプリコンテナイメージのプッシュ

image-upload コマンドを使用すると、Extendアプリコンテナイメージをビルドし、タグ付けして、Extendアプリコンテナレジストリにプッシュできます。

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>

--login フラグを使用すると、事前に dockerlogin を自動的に実行できるため、別途実行する必要がなくなります。

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>
    --login

アップロードが失敗した場合は、--retry-limit を --retry-interval <seconds>（デフォルト: 1.0）および --retry-rate <seconds>（デフォルト: 2.0）と併用して再試行できます。

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>
    --retry-limit 3

Extendアプリの環境変数とシークレットの作成・更新

update-var コマンドを使用して、Extendアプリの環境変数を新規作成または既存のものを変更します。

extend-helper-cli update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100

update-secret コマンドを使用して、Extendアプリの環境シークレットを新規作成または既存のものを変更します。

extend-helper-cli update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>

--force を追加すると、変数やシークレットがまだ存在しない場合に、コマンドを強制的に作成させることもできます。

環境変数の場合:

extend-helper-cli update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100
    --wait

環境シークレットの場合:

extend-helper-cli update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>
    --wait

Extendアプリのデプロイ

deploy-app コマンドを使用して、Extendアプリのデプロイを作成します。

extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag v1.0.0

サンプルレスポンス

{
  "deploymentId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

--wait（および --wait-interval <duration-in-seconds:10>、--wait-limit <duration-in-seconds:300>）を追加して、アプリのデプロイが完了するまで待機することもできます。

extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag v1.0.0 --wait

Extendアプリの起動と停止

start-app または stop-app コマンドを使用して、Extendアプリを起動または停止します。

extend-helper-cli start-app --namespace <my-game-namespace> --app <my-extend-app>

extend-helper-cli stop-app --namespace <my-game-namespace> --app <my-extend-app>

--wait を --wait-interval <seconds>（デフォルト: 10）および --wait-limit <seconds>（デフォルト: 300）と併用すると、アプリの起動または停止の準備が整うまで待機できます。

待機時間を指定してExtendアプリを起動する場合:

extend-helper-cli start-app --namespace <my-game-namespace> --app <my-extend-app>
    --wait

待機時間を指定してExtendアプリを停止する場合:

extend-helper-cli stop-app --namespace <my-game-namespace> --app <my-extend-app>
    --wait

Extendアプリの削除

delete-app コマンドを使用して、Extendアプリを削除します。

extend-helper-cli delete-app --namespace <my-game-namespace> --app <my-extend-app> --confirm

--wait を --wait-interval <seconds>（デフォルト: 10）および --wait-limit <seconds>（デフォルト: 300）と併用すると、アプリの削除準備が整うまで待機できます。

extend-helper-cli delete-app --namespace <my-game-namespace> --app <my-extend-app> --confirm
    --wait

トラブルシューティング

このセクションでは、Extendアプリを開発する際に発生する可能性のある問題のトラブルシューティング情報について説明します。

Dockerログインが失敗する

Extend Helper CLIを使用してExtendアプリコンテナイメージをAGSにプッシュする際、extend-helper-cli dockerlogin ... コマンドが次のエラーを返します。

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

この問題は、トークンサイズが多くの認証情報マネージャーが処理できる範囲を超えていることが原因である可能性があります。詳細については、この問題に関するDockerのチケットを参照してください。

この問題の回避策は、お使いのオペレーティングシステムによって異なります。

Linux
Windows (WSL2)

$HOME/.docker/config.json から "credsStore": "desktop.exe" を削除します。
extend-helper-cli dockerlogin ... コマンドを再度実行します。

Windowsファイルシステムで:
- %USERPROFILE%\.docker\config.json から "credsStore": "desktop.exe" を削除します。
- C:\Program Files\Docker\Docker\resources\bin にある次のファイルの名前を変更します。
  - docker-credential-desktop.exe を docker-credential-desktop.exe.old に
  - docker-credential-wincred.exe を docker-credential-wincred.exe.old に
WSL2ファイルシステムで:
- $HOME/.docker/config.json から "credsStore": "desktop.exe" を削除します。
extend-helper-cli dockerlogin ... コマンドを再度実行します。

注記

この回避策は定期的に適用する必要がある場合があります。この記事の更新日時点で、Dockerには再起動時に config.json ファイル内の "credsStore": "desktop" が復元されるという既知の問題があります。詳細については、この問題に関するDockerのチケットを参照してください。

概要​

前提条件​

インストール​

セットアップ​

オプション1: .env ファイルを使用する​

オプション2: 環境変数をエクスポートする​

使用方法​

Extendアプリの作成​

Extendアプリ情報の取得​

Extendアプリコンテナイメージをプッシュするための認証情報の取得​

Extendアプリコンテナイメージのプッシュ​

Extendアプリの環境変数とシークレットの作成・更新​

Extendアプリのデプロイ​

Extendアプリの起動と停止​

Extendアプリの削除​

トラブルシューティング​

Dockerログインが失敗する​

概要

前提条件

インストール

セットアップ

オプション1: `.env` ファイルを使用する

オプション2: 環境変数をエクスポートする

使用方法

Extendアプリの作成

Extendアプリ情報の取得

Extendアプリコンテナイメージをプッシュするための認証情報の取得

Extendアプリコンテナイメージのプッシュ

Extendアプリの環境変数とシークレットの作成・更新

Extendアプリのデプロイ

Extendアプリの起動と停止

Extendアプリの削除

トラブルシューティング

Dockerログインが失敗する