xbox) 既可供人员运行,也专为 AI 代理和脚本运行而构建。其命令采用显式参数,其数据命令写入 JSON,其错误会以非零退出代码输出到 stderr。本页面向代理以及设置代理的人员:介绍如何登录、选择命令的操作对象、读取其输出、找到正确的 API,以及在更改任何内容之前应询问哪些内容。
在更改任何内容之前
已登录的用户通常对生产游戏和卖家拥有管理员权限,而服务器端没有任何机制可以阻止错误的调用。安全性和破坏性操作列出了 CLI 会询问和不会询问的内容。其余部分由你负责:- 仅当 PlayFab 操作的名称以
Get、List或Search开头时,才将其视为只读操作。将其他所有操作以及每个创建、更改或删除内容的xbox命令视为生产更改。 - 在进行生产更改之前,向用户显示命令,并用一句话说明它会更改什么以及针对哪个游戏或卖家,包括该目标是否来自已保存的上下文。只有在用户同意后才能运行,即使你的运行时无需询问即可运行
xbox也是如此。用户的同意仅涵盖你显示的调用。 - 每次进行生产更改时,都将游戏或卖家作为标志传递。已保存的上下文由操作系统用户的每个会话共享,因此在用户同意和你进行调用之间,它可能会发生变化。
- 在运行
xbox pc sandbox set(它会为电脑上的所有人切换沙盒)之前,以及在运行xbox pc sandbox launch-apps(它会关闭 Microsoft Store 和 XBOX 应用)之前,请先询问。 - 请勿添加
--confirm(或--yes)来代替询问。CLI 无法分辨是谁添加的。 - 在请求使用
xbox xbl config publish发布到 RETAIL 之前,请使用--validate-only运行它,并向用户显示它列出的成就。然后将--configset设置为其 JSON 输出中的SourceVersion进行发布。RETAIL 中的成就无法删除;请参阅 RETAIL 发布添加的成就。 - 如果生产更改失败且其结果未知,则该更改可能已被应用。在重试之前,请读取受影响的状态;请参阅 中断的写入会报告其结果未知。
- 除非用户要求你更改,否则请勿改动已保存的上下文。
xbox context set、xbox context unset和xbox context profile delete会更改每个会话的默认值。
登录
auth status 会以代码 0 退出并报告 {"signedIn":false},因此请根据 signedIn 进行分支。非零退出代码表示它无法检查,错误会输出到 stderr。
除非已登录的用户对该游戏拥有 Admin 权限,否则 PlayFab 调用会失败。请参阅
身份验证。
选择游戏或卖家
将游戏或卖家作为标志传递,例如--playfab-title-id ABC123。如果未传递,命令会使用 XBOX_ 环境变量或通过 xbox context set 保存的值;有关哪个值优先,请参阅
上下文。运行 xbox context get --output json-compact 可查看已保存的内容,并且在调用任何实质性操作之前,先与用户确认一次游戏。
读取输出
结合使用--data-only 和 --output json-compact,可以在单行中仅获取有效负载:
--data-only 时,出错时 stdout 为空,因此请在分析 stdout 之前检查退出代码。
playfab file upload、download 和 delete 不会向 stdout 写入任何内容,并且其 stderr 消息可能会更改,因此请检查它们的退出代码。请参阅文件。
帮助会标记实验性命令,其接口可能会更改。请参阅
实验性命令。
速率限制
当 XBOX 服务返回 HTTP 429 时,请等待一段时间后再重试;CLI 不会替你重试。当服务指定了等待时间时,错误会说明需要等待多少秒,结构化错误也会以retryAfterSeconds 的形式携带该值。错误代码为 rate_limited 的 429 表示你在短时间内发送了过多请求,因此请降低速度。
查找正确的 PlayFab API
xbox playfab api <api-path> 可调用任何 PlayFab API 操作。路径为
/<Prefix>/<Operation>,例如 /MultiplayerServer/ListBuildSummariesV2,请求正文是该操作的 JSON 请求对象。PlayFab 记录了这两者:
- PlayFab Swagger 规范
是机器可读的。每个文件按路径列出其操作,以及操作的请求和响应架构和必填字段。这些文件以 PlayFab 的 API 组命名,而不是以路径的第一段命名,因此请在文件的
paths中搜索该操作:/Catalog和/Inventory位于Economy.swagger.json中,/Match、/Lobby和/MultiplayerServer位于Multiplayer.swagger.json中。每个操作的security字段指明其接受的凭据:SecretKey、EntityToken、SessionTicket,或者对于无需凭据的操作(例如玩家登录调用)为None。某些操作还会在其说明中列出允许的实体令牌类型。 - PlayFab REST API 参考面向人员介绍了相同的操作。
SessionTicket 的操作,或仅接受玩家或游戏服务器实体令牌的操作,都不会获得授权。调用失败时,其错误响应通常会指明问题所在,例如
InvalidParameter 或 MissingParameter。有关详细信息,请参阅 PlayFab API 集成。
在 Windows 上的 Git Bash 中,请为该命令设置 MSYS_NO_PATHCONV=1,否则 Git Bash 会在 CLI 收到 API 路径之前将其转换为 Windows 路径。请参阅
在 Windows 上从 Git Bash 运行。
避免机密出现在日志中
- 当请求正文可能包含机密时,请使用
--body-file而不是--body传递它,使其不会出现在 shell 历史记录和进程列表中。playfab mps certificate upload和playfab mps secret upload会拒绝--body,因为它们的正文始终包含机密。 - 不要将机密放在配置文件和环境变量中。
ClientId、TenantId和 OAuth 作用域是标识符,而不是机密。 - PlayFab 响应可能包含玩家、物品清单或经济系统数据。对代理记录的任何内容进行编辑、保留和访问控制,由代理的所有者负责。
