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://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)中。作业
作业是由代理处理的单个操作。目前共有四种作业类型:- executeCommandJob:在主机上执行命令。可用于执行完整的 wd* 命令集。有关 wd* 主机命令行工具的详细信息,请参阅此处。
- downloadFilesJob:用于检索文件的源 URL。此 URL 可以是任意的,并采用与心跳调用相同的已配置身份验证。调用通过 GET 完成,且不要求使用 SSL。
- uploadFilesJob:用于上传文件的目标 URL。此 URL 可以是任意的,并采用与心跳调用相同的已配置身份验证。调用通过 POST 或 PUT 完成,且不要求使用 SSL。
- cancelCurrentJob:此作业指示代理取消当前正在运行的作业。
> - 将 Execute Command 作业上的 WaitForExit 设置为 false 可强制执行“即发即忘”执行。LastProcessedJobResult 属性将不会填充任何输出或退出代码,并且代理将立即请求下一个作业。
安全和身份验证
在使用代理时,我们设计了一个既能为生产服务实现安全和已认证通信,又能在开发过程中提供便利的系统。 代理要求通过 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。