DevKit Agent
DevKit Agent は、動作としてはシンプルなステート マシンです。10 秒ごと、またはジョブの処理直後に、エージェントはサーバーに 1 つのジョブを要求するハートビートを送信します。ジョブは直ちに処理され、次回のハートビートで activeJobId が返送されます。ジョブが処理されていない場合、activeJobID はすべてゼロの GUID になります。 ハートビート間隔は、KitHeartbeatResponse の heartbeatInterval プロパティを使用して調整できます。以降のハートビートはその間隔で送信されますが、サーバーで再度変更されるか、エージェントが再起動するとリセットされます。コンソールの再起動後、間隔は既定値の 10 秒にリセットされます。エージェントは最後に処理した jobID を超える状態を保存しませんが、開始日時とコンソールの稼働時間を報告します。
独自サービスを持ち込む
DevKit Agent は、独自のサービスを持ち込む前提で設計されています。コンソール上の構成設定によって、エージェントにサービスの URI が提供されます。サーバーはエージェントからのハートビート要求を待ち受け、ハートビート メッセージを検査してエージェントに実行させる次の適切なジョブを判断し、ジョブをエージェントに送信します。サーバーが制御を持ち、エージェントは意図されたワークフローに干渉する論理操作を実行しません。 Microsoft Game Development Kit (GDK) には DevKitAgentAPI.yaml が付属しています。これは、DevKit Agent とサーバー間の契約を記述する OpenApi v3.0.3 準拠のドキュメントです。このドキュメントでは、サポートされているパス（例: /KitHeartbeat）およびコンポーネント スキーマ（例: ExecuteCommandJob、KitHeartbeatResponse、FileUpload など）が詳しく説明されています。 2023 年 6 月の GDK 以降、このファイルは %SDK_ROOT%\toolKit\include\DevKitAgentAPI.yaml にインストールされます。エージェントは、OpenAPI 契約に準拠するあらゆるサービス実装とインターフェイスします。 OpenAPI 契約の詳細については、次を参照してください。- https://spec.openapis.org/oas/v3.0.3.html
- https://openapi-generator.tech/docs/usage
- https://openapi-generator.tech/docs/generators/
- Swagger / OpenAPI を使用した ASP.NET Core Web API ドキュメント
エージェントのハートビート要求
以下は、executeCommandJob 後のハートビート要求の例（JSON 形式）です。ハートビートには、エージェントの詳細（スキーマ バージョン、稼働時間など）、コンソール（ipAddress、runningApplication など）、およびエージェントのジョブ ステータス（activeJobId、lastProcessedJobResult など）が含まれます。完全なスキーマを確認するには、DevKitAgentAPI.yaml を Swagger などのさまざまなジェネレーターに読み込むことができます。ジョブ
ジョブは、エージェントが処理する単一の操作です。現在、4 種類のジョブがあります。- executeCommandJob: コンソール上でコマンドを実行します。wd* コマンドのすべてが実行可能です。wd* コンソール コマンド ライン ツールの詳細については、こちら を参照してください。
- downloadFilesJob: ファイルを取得するソース URL。この URL は任意で、ハートビート呼び出しと同じ構成済み認証を提供します。呼び出しは GET で行われ、SSL の使用は必須ではありません。
- uploadFilesJob: ファイルのアップロード先の宛先 URL。この URL は任意で、ハートビート呼び出しと同じ構成済み認証を提供します。呼び出しは POST または PUT で行われ、SSL の使用は必須ではありません。
- cancelCurrentJob: このジョブは、エージェントに現在実行中のジョブをキャンセルするよう指示します。
> - Execute Command ジョブで WaitForExit を false に設定すると、Fire-and-Forget 型の実行が強制されます。LastProcessedJobResult プロパティには出力や終了コードが設定されず、エージェントは直ちに次のジョブを要求します。
セキュリティと認証
エージェントを使用する際、本番サービス向けの安全で認証された通信と、開発時の便宜性を両立するシステムを設計しました。 エージェントは HTTPS 経由でのサーバーとの通信を必要とし、Xtoken を使用してサーバーで認証します。そのため、エージェント URI を Partner Center で証明書利用者 (Relying Party) として構成する必要があります。- HTTPS により、デバイスは信頼されたサービスと通信していることを認識できますが、HTTPS ではサービス側でデバイスが信頼されていることは分かりません。
- Xtoken は、開発機を一意に識別するために、サービスが Developer Device ID (ddi) クレームでデバイスを認証できるようにするために使用します。
XBOX-AGENT-XTOKEN ヘッダーでサーバーに渡します。サーバーはトークンの署名を復号して検証することで、エージェントを認証します。サーバーは新しいジョブで応答するか、要求を無視できます。 証明書利用者の構成のオプションとして、Developer Device ID (ddi) と呼ばれる新しいクレームが追加されました。この新しいクレームは、サービスにハートビートを送信しているデバイスが期待されるものであることを保証するために使用するように設計されています。ddi クレームは Partner Center で構成されている任意の証明書利用者で利用可能ですが、このクレームは XBOX 開発機で実行されている場合にのみ設定され、Retail では null を返します。ddi はデバイスの XBOX Live Device ID を返し、開発機の XBOX Live Device ID は xbdiaginfo または Retail シェルの設定から確認できます。
上記は本番デプロイのベスト プラクティスであり、DevKit エージェントとサービスでは自己署名証明書を使用できます。完全に信頼チェーンされた証明書は必要ありません。また、開発時に既知の開発機と作業する場合、サーバー側で ddi を検査する必要はありません。
XToken の詳細については、https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav を参照してください。