認証

認証に使用しなければならない方法は、Multiplay Hosting サービス間で若干異なります。

サービス認証タイプ
Unity Services ゲートウェイ
https://services.api.unity.com
サービスアカウントキーを使用した Basic 認証。
Unity ゲームゲートウェイ
https://multiplay.services.api.unity.com
トークン交換の Bearer トークン。

Multiplay Hosting リソースを変更する管理 API 呼び出しは、Unity Services ゲートウェイ を使用します。

割り当てや割り当て解除など、ゲームライフサイクル API 呼び出しは、Unity ゲームゲートウェイ を使用します。

サーバー認証

サーバー認証はサーバーに関連付けられており、Multiplay Hosting マシン上で実行するときに取得できます。

これは Gaming Gateway で使用できます。

Multiplay Hosting トークンは以下の方法で取得できます。

  • スクリプティング API と Authentication パッケージ
  • ローカルリクエストを介して手動で

スクリプティング API と Authentication パッケージ

Authentication パッケージから以下の呼び出しを使用:

await ServerAuthenticationService.Instance.SignInFromServerAsync();
var token = ServerAuthenticationService.Instance.AccessToken;

サービスアカウントを使用して認証することもできます。

await ServerAuthenticationService.Instance.SignInWithServiceAccountAsync(apiKeyIdentifier, apiKeySecret);

ノート: サービスアカウントが、使用可能な環境を調べるには Unity 環境閲覧者ロールが必要です。

サービスアカウント を参照してください。

手動でのトークンの取得

トークンはローカルリクエストを介して手動で取得することもできます。

curl -X GET http://localhost:8086/v4/token

リクエストでは以下の形式のレスポンスが返されます。

{"token":"<BEARER_TOKEN>", "error":""}

サービスアカウント

すべての API 認証ではサービスアカウントが必要です。

実行しようとするリクエストに適したロールを保持するサービスアカウントがない場合は、サービスアカウントの作成 を参照してください。

サービスアカウントと認証は主に管理権限用です。サーバー認証 は信頼できるゲームサービスの代わりです。

Unity Services ゲートウェイ

Unity Services ゲートウェイ (USG) を使用して、管理 API (ビルド、ビルド設定、フリート、他の Multiplay Hosting リソースなどの管理) を認証します。

Basic 認証を使用して、API 呼び出しを認証します。

Authorization: Basic <base64(keyID:keySecret)>

つまり、キー ID秘密鍵 をコロンで区切った文字列を作成してから、それを base64 でエンコードします。

多くの HTTP ライブラリおよびツールには、Basic 認証のサポートが組み込まれています。このケースでは、キー ID をユーザー名、秘密鍵 をパスワードとして使用できます。

例 (ビルドのリスト)

以下に示すのは、ヘッダーを作成し、それをビルドをリストする curl リクエストで使用する例です。

キー ID秘密鍵
9250f578-9ff1-4b75-afcc-7eca1e94db565d7f1a66-f29d-45c8-a6aa-a84242aa805f

キー ID秘密鍵 をコロンで区切った文字列を作成してから、それを base64 でエンコードします。

こうすると以下の値が生成されます。

OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg==

これを以下のように承認ヘッダーで使用できます。

curl -X GET 'https://services.api.unity.com/multiplay/builds/v1/projects/<projectID>/environments/<environmentID>/builds \
--header 'Authorization: Basic OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg=='

このエンドポイントの詳細と使用されるパラメーター (projectIDenvironmentID など) については、ゲームサーバー API のドキュメント を参照してください。

Unity ゲームゲートウェイ

Unity ゲームゲートウェイは、認証に Bearer トークンを使用します。Bearer トークンを取得するには、最初にサービスアカウントを使用して、Unity ゲームゲートウェイに期限付きトークンをリクエストする必要があります。

  1. アクセストークンを取得するためのトークン交換。詳細については、認証 API のドキュメント を参照してください。
  2. Bearer 認証でアクセストークンを使用して、Unity ゲームゲートウェイエンドポイントにリクエストを行います。
  3. 推奨される有効な事例はトークンの再利用です。ただし、1 時間後に期限が切れるため、期限が切れる前に更新する必要があります。

アクセストークンは RFC 7519 に準拠する JWT であるため、どの JWT ライブラリで解釈しても正確な期限を抽出できます。

例 (割り当てのリスト):

この例では、割り当てをリストするエンドポイントに対してリクエストを行う方法を示します。これは 2 つのステップで構成されます。

  1. アクセストークンを取得するためのトークン交換。詳細については、認証 API のドキュメント を参照してください。
  2. Bearer 認証でアクセストークンを使用して、割り当てをリストするエンドポイントにリクエストを行います。
# Get the token from the token exchange endpoint
curl -X POST 'https://services.api.unity.com/auth/v1/token-exchange?projectId=<projectID>&environmentId=<environmentID>' \
--header 'Authorization: Basic  <base64(keyID:keySecret)>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "scopes": []
}'

レスポンスを受け取ります。

{
    "accessToken": <accessToken>
}

Unity ゲームゲートウェイサービスへの後続のリクエストでは、文字列 accessToken を Bearer 認証で使用できます。例えば、割り当てをリストするには、以下のようになります。

# Make the list allocations request
curl -X GET 'https://multiplay.services.api.unity.com/v1/allocations/projects/<projectID>/environments/<environmentID>/fleets/<fleetID>/allocations \
--header 'Authorization: Bearer <accessToken>'

このエンドポイントの詳細と使用されるパラメーター (projectIDenvironmentIDfleetID など) については、ゲームサーバー API のドキュメント を参照してください。