> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# XBOX 開発キットを管理する DevKit Agent
> すべての XBOX 開発キットに搭載された DevKit Agent が、OpenAPI を介してサービスをポーリングし、コンソール構成、タイトル実行、ファイル操作のジョブを実行する仕組みを解説します。
DevKit Agent は、すべての XBOX 開発機で実行されるプロセスです。このプロセスにより、ローカルおよびリモート シナリオ向けにホスト型サービスから開発機を管理できます。エージェントは、構成されたサービスに対して、定期的かつ構成可能な間隔でハートビート要求を送信し、サービスはコンソール上で実行されるジョブを発行できます。ジョブは、ファイル管理およびコンソール管理シナリオのアトミック操作です。一般的なシナリオには、[こちら](/tools/tools-console/console_commandlinetools/consolecommandlinetools) で説明されている wd\* ツールを使用したコンソールの構成、タイトルの実行、およびファイル コピー操作が含まれます。
## 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://spec.openapis.org/oas/v3.0.3.html)
* [https://openapi-generator.tech/docs/usage](https://openapi-generator.tech/docs/usage)
* [https://openapi-generator.tech/docs/generators/](https://openapi-generator.tech/docs/generators/)
* [Swagger / OpenAPI を使用した ASP.NET Core Web API ドキュメント](https://learn.microsoft.com/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-7.0)
## エージェントのハートビート要求
以下は、executeCommandJob 後のハートビート要求の例（JSON 形式）です。ハートビートには、エージェントの詳細（スキーマ バージョン、稼働時間など）、コンソール（ipAddress、runningApplication など）、およびエージェントのジョブ ステータス（activeJobId、lastProcessedJobResult など）が含まれます。完全なスキーマを確認するには、DevKitAgentAPI.yaml を Swagger などのさまざまなジェネレーターに読み込むことができます。
```{ theme={null}
"agentSchemaVersion": "2023.10.0",
"kit": {
"hostname": "DevKit01",
"ipAddress": "172.200.0.1",
"osVersion": "10.0.25398.2258 (xb_flt_2309zn.230918-2000)",
"runningApplicationId": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App",
"runningApplication": {
"displayName": "Example Game",
"fullName": "41336PublisherName.ExampleGame",
"aumids": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App"
},
"uptime": 1234567890,
"deviceType": "ScarlettDevkit"
},
"activeJobId": "85a5cb10-cee1-4eac-865d-978746090428",
"lastProcessedJobResult": {
"id": "235a5dfb10-lbb5-4bad-725d-978746083564",
"executeCommandJobResult": {
"commandOutput": "Here are some \"quotes\"",
"exitCode": 1,
"processId": 1337,
"job": {
"commandLine": "cmd.exe /C ECHO Here are some \\\"quotes.\\\"",
"workingDirectory": "d:\\",
"commandLineIsScript": true,
"waitForExit": true,
"willReboot": true
}
},
"jobType": "executeCommandJob"
},
"agentStartTime": "2023-04-07T23:47:13.434Z",
"currentDateTime": "2023-05-09T23:47:13.434Z"
}
```
## ジョブ
ジョブは、エージェントが処理する単一の操作です。現在、4 種類のジョブがあります。
* **executeCommandJob**: コンソール上でコマンドを実行します。wd\* コマンドのすべてが実行可能です。wd\* コンソール コマンド ライン ツールの詳細については、[こちら](/tools/tools-console/console_commandlinetools/consolecommandlinetools) を参照してください。
* **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) クレームでデバイスを認証できるようにするために使用します。
エージェントは、生成された Xtoken をハートビート要求の `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](https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav) を参照してください。
## DevKit Agent の構成
コンソールに 2 つの構成値を設定します: サーバーの URI (DevkitAgentServiceUri) と証明書利用者 (DevKitAgentRelyingParty) です。
これらの値を設定するには、Microsoft Game Development Kit (GDK) コマンド ラインを開き、対象のコンソールに接続してから、次のコマンドを実行します。
```
C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=https://myserver.mydomain.com
DevKitAgentServiceUri: https://myserver.mydomain.com
C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentRelyingParty=rp://myagentRP.mydomain.com
DevKitAgentRelyingParty: rp://myagentRP.mydomain.com
```
### エージェントの起動と停止
エージェントは、DevKitAgentServiceUri 構成設定の有無に基づいて自動的に起動および停止します。エージェントを停止するには、XBOX コマンド プロンプトから次のコマンドを実行します。
```
C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=""
```
または、エージェント サーバー経由で相当する wdConfig コマンドを送信します。
```
wdconfig DevKitAgentServiceUri=""
```
## 関連項目
[コンソール コマンドライン ツール](/tools/tools-console/console_commandlinetools/consolecommandlinetools)
## Related topics
- [用語集](/ja-jp/publishing/game-publishing/glossary.md)
- [ストリーミング用に XBOX 開発キットをセットアップする](/ja-jp/build/core-features/common/game-streaming/game-streaming-setup-xbox-developer-kit.md)
- [マルチプレイヤー テストにおける XBOX Manager のベスト プラクティス](/ja-jp/tools/tools-console/xbom/manager-tool-multiplayer.md)
- [開発キット専用 API リファレンス](/ja-jp/reference/devkit/atoc-devkit-reference.md)
- [XBOX 開発キットでのネットワーク ストレス テスト](/ja-jp/build/console-features/networking/tools/netstress-networking.md)