跳转到主要内容
XBOX CLI (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,可以在单行中仅获取有效负载:
失败的调用会以非零代码退出,并将其错误写入 stderr。使用 --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 参考面向人员介绍了相同的操作。
CLI 使用用户的 Microsoft Entra ID 凭据进行调用,而不是使用游戏机密密钥或游戏实体令牌,因此需要玩家 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 响应可能包含玩家、物品清单或经济系统数据。对代理记录的任何内容进行编辑、保留和访问控制,由代理的所有者负责。

另请参阅

最后修改于 2026年11月19日