> ## 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\* 工具(如[此处](/tools/tools-console/console_commandlinetools/consolecommandlinetools)所述)进行的文件复制操作。

## DevKit Agent

DevKit Agent 在运行时是一个简单的状态机。每 10 秒或在处理完作业后立即,代理会发送心跳以请求服务器下发一个作业。收到后立即处理该作业,并在下一次心跳中将 activeJobId 发送回去。如果没有正在处理的作业,activeJobID 为全零 GUID。

可通过 KitHeartbeatResponse 上的 heartbeatInterval 属性调整心跳间隔。后续心跳将按该间隔发送,除非在服务器上再次更改,或代理重启。任何主机重启后,间隔将重置为默认值 10 秒。

<Note>代理除了最后处理的 jobID 之外不存储其状态,但它会报告启动时的日期和时间以及主机的正常运行时间。</Note>

## 使用您自己的服务

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**:在主机上执行命令。可用于执行完整的 <b>wd\*</b> 命令集。有关 wd\* 主机命令行工具的详细信息,请参阅[此处](/tools/tools-console/console_commandlinetools/consolecommandlinetools)。
* **downloadFilesJob**:用于检索文件的源 URL。此 URL 可以是任意的,并采用与心跳调用相同的已配置身份验证。调用通过 GET 完成,且不要求使用 SSL。
* **uploadFilesJob**:用于上传文件的目标 URL。此 URL 可以是任意的,并采用与心跳调用相同的已配置身份验证。调用通过 POST 或 PUT 完成,且不要求使用 SSL。
* **cancelCurrentJob**:此作业指示代理取消当前正在运行的作业。

<Note>> - 将 Execute Command 作业上的 WaitForExit 设置为 false 可强制执行“即发即忘”执行。LastProcessedJobResult 属性将不会填充任何输出或退出代码,并且代理将立即请求下一个作业。</Note>

## 安全和身份验证

在使用代理时,我们设计了一个既能为生产服务实现安全和已认证通信,又能在开发过程中提供便利的系统。

代理要求通过 HTTPS 与服务器通信,并使用 Xtoken 与服务器进行身份验证。因此,需要在合作伙伴中心将代理 URI 配置为信赖方。

* HTTPS 让设备知道它正在与受信任的服务通信,但 HTTPS 不能让服务知道设备是受信任的。
* 使用 Xtoken 是为了让服务能够通过开发者设备 ID (ddi) 声明对设备进行身份验证,以唯一标识该开发套件。

代理在心跳请求的 `XBOX-AGENT-XTOKEN` 标头中向服务器传递生成的 Xtoken。然后,服务器会解密并验证令牌的签名以对代理进行身份验证。之后,服务器可以以新的作业作为响应,也可以忽略该请求。已为您的信赖方配置添加了一个作为选项的新声明,称为开发者设备 ID (ddi)。此新声明旨在用于确保正在向您服务发送心跳的设备是预期的设备。ddi 声明可用于合作伙伴中心中配置的任何信赖方,但请注意,此声明只有在运行于 XBOX 开发套件时才会被填充,在零售模式下将返回 null。ddi 将返回设备的 XBOX Live 设备 ID,您可以从 xbdiaginfo 或零售版界面的“设置”中获取开发套件的 XBOX Live 设备 ID。

以上是您生产部署的最佳实践,自签名证书可用于 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=""
```

## 另请参阅

[主机命令行工具](/tools/tools-console/console_commandlinetools/consolecommandlinetools)