> ## 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 開發套件上執行的處理序。此處理序可讓您在本機與遠端情境中，從裝載的服務管理開發套件。代理程式會以固定且可設定的頻率向已設定的服務傳送活動訊號要求，而您的服務可以發出在主機上執行的工作。工作是用於檔案與主機管理情境的不可部分完成作業。常見情境包括主機設定、遊戲執行，以及使用 wd\* 工具的檔案複製作業，如[這裡](/zh-TW/tools/tools-console/console_commandlinetools/consolecommandlinetools)所述。
## DevKit Agent
DevKit Agent 的運作方式是一個簡單的狀態機。代理程式每 10 秒或在處理完工作後立即傳送活動訊號，向伺服器要求單一工作。接著會立即處理該工作，並在下一次活動訊號中傳回 activeJobId。如果沒有正在處理的工作，activeJobID 會是全為零的 GUID。
您可以使用 KitHeartbeatResponse 上的 heartbeatInterval 屬性調整活動訊號間隔。後續的活動訊號會以該間隔傳送，除非伺服器再次變更間隔或代理程式重新啟動。任何主機重新啟動後，間隔都會重設為預設值 10 秒。
除了最後處理的 jobID 之外，代理程式不會儲存其狀態，但會回報其啟動的日期與時間，以及主機的運作時間。
## 自備服務
DevKit Agent 的設計前提是由您自備服務。主機上的設定值會向代理程式提供您服務的 URI。您的伺服器會接聽來自代理程式的活動訊號要求、檢查活動訊號訊息以決定代理程式接下來要執行的適當工作，然後將工作傳送給代理程式。由您的伺服器掌控，代理程式不會執行任何干擾您預期工作流程的邏輯作業。
Microsoft Game Development Kit (GDK) 提供 DevKitAgentAPI.yaml。這是符合 OpenApi v3.0.3 的文件，描述 DevKit Agent 與您伺服器之間的合約。此文件詳細說明支援的路徑 (例如 /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"
}
```
## 工作
工作是代理程式要處理的單一作業。目前有四種工作類型：
* **executeCommandJob**：在主機上執行命令。可以執行完整的 wd\* 命令集。您可以在[這裡](/zh-TW/tools/tools-console/console_commandlinetools/consolecommandlinetools)找到 wd\* 主機命令列工具的詳細資訊。
* **downloadFilesJob**：擷取檔案的來源 URL。此 URL 可以任意指定，並提供與活動訊號呼叫相同的已設定驗證。呼叫是透過 GET 進行，不需要使用 SSL。
* **uploadFilesJob**：上傳檔案的目的地 URL。此 URL 可以任意指定，並提供與活動訊號呼叫相同的已設定驗證。呼叫是透過 POST 或 PUT 進行，不需要使用 SSL
* **cancelCurrentJob**：此工作會指示代理程式取消目前執行中的工作。
> - 在 Execute Command 工作上將 WaitForExit 設為 false，可強制以射後不理的方式執行。LastProcessedJobResult 屬性不會填入任何輸出或結束代碼，且代理程式會立即要求下一個工作。
## 安全性與驗證
使用代理程式時，我們設計了一個系統，可為生產服務提供安全且經過驗證的通訊，同時在開發期間提供便利性。
代理程式要求透過 HTTPS 與伺服器通訊，並使用 Xtoken 向伺服器驗證。因此，代理程式 URI 需要在 Partner Center 中設定為信賴憑證者。
* HTTPS 讓裝置知道它正在與受信任的服務通訊，但 HTTPS 無法讓服務知道裝置是否受信任。
* 使用 Xtoken 是為了讓服務能透過開發人員裝置識別碼 (ddi) 宣告驗證裝置，以唯一識別開發套件。
代理程式會在活動訊號要求的 `XBOX-AGENT-XTOKEN` 標頭中，將產生的 Xtoken 傳遞給伺服器。接著伺服器會解密並驗證權杖簽章，以驗證代理程式。伺服器接著可以回應新的工作或忽略該要求。我們新增了一個名為開發人員裝置識別碼 (ddi) 的新宣告，作為信賴憑證者設定的選項。此新宣告的用途是確保向您的服務傳送活動訊號的裝置是預期中的裝置。ddi 宣告可供 Partner Center 中設定的任何信賴憑證者使用，但請注意，此宣告只有在 XBOX 開發套件上執行時才會填入，在零售環境中會傳回 null。ddi 會傳回裝置的 XBOX Live 裝置識別碼，而您開發套件的 XBOX Live 裝置識別碼可以從 xbdiaginfo 或零售殼層的設定中取得。
以上是生產部署的最佳做法，DevKit Agent 與您的服務可以使用自我簽署憑證，不需要完整鏈結的憑證。此外，在開發期間使用已知的開發套件時，不需要在伺服器上檢查 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
在主機上設定兩個設定值：伺服器的 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=""
```
## 另請參閱
[主機命令列工具](/zh-TW/tools/tools-console/console_commandlinetools/consolecommandlinetools)
## Related topics
- [XBOX 主機上的 DevKit Agent 處理序](/zh-TW/tools/tools-console/devkitagent/index.md)
- [用於管理開發主機的 XBOX Manager 工具](/zh-TW/tools/tools-console/xbom/index.md)
- [僅限開發套件的 API 參考](/zh-TW/reference/devkit/atoc-devkit-reference.md)
- [GDK 名詞與縮寫詞彙表](/zh-TW/home/glossary.md)
- [在 XBOX 開發套件上擷取網路流量](/zh-TW/build/console-features/networking/tools/netcap-networking.md)