跳转到主要内容
xbox context 保存卖家、PlayFab 游戏、XBOX 游戏和沙盒的默认值,这样你就不必在每个命令中都传递它们。本页还介绍了在你未传递这些值时,命令从何处获取它们。上下文是本地的:这些命令不会更改 Partner Center 或 PlayFab 中的任何内容。

命令

键

键是它所填充的选项的名称: 其他选项均不接受已保存的值或变量。 title-id 是十六进制的 XBOX 游戏 ID(例如 1234ABCD),而不是 PlayFab 游戏 ID。xbl 命令使用它来查找游戏的服务配置标识符 (SCID),当你传递 --scid 时则忽略它。请参阅游戏定位。

命令如何使用已保存的值

当命令接受这些选项之一时,它使用找到的第一个值:
  1. 命令行上的选项,例如 --seller-id。
  2. 该选项的 XBOX_ 变量,例如 XBOX_SELLER_ID。空白变量视为未设置。
  3. 在所选配置文件中使用 context set 保存的值。
来自变量或已保存上下文的值与键入的值一样会经过检查,错误会指明值的来源,例如 XBOX_SELLER_ID: --seller-id must be a positive numeric value. 如果没有任何来源提供命令所需的值,命令会说明如何设置一个值。卖家为可选项的命令(xbl 和 test-account)会使用你唯一获得授权的卖家。 进行更改的命令会将其填充的每个值及其来源写入 stderr,即使使用了 --confirm 也是如此。使用 --verbose 时,每个命令都会这样做:
已知问题介绍了两个问题,这些问题会导致 game 和 sandbox 命令使用的卖家与按此方式选择的卖家不同。

配置文件

配置文件是一组命名的已保存值,例如一个用于测试游戏,一个用于生产环境。命令使用 --profile 指定的配置文件;如果未指定,则使用 XBOX_PROFILE 指定的配置文件;否则使用 default。
若要在某个 shell 中为每个命令使用一个配置文件,请设置 XBOX_PROFILE:
列出你的配置文件:
删除配置文件及其中保存的每个值:
  • 将第一个值保存到配置文件时会创建该配置文件。名称由字母、数字和连字符组成,最多 64 个字符,不区分大小写。
  • 不存在的配置文件(例如拼写错误的配置文件)会导致失败,而不是回退到 default。
  • 配置文件不会从 default 借用值。
  • XBOX_ 变量仍然优先于配置文件。当某个变量优先于 --profile 指定的配置文件时,命令会给出提示,即使它不做任何更改:
  • CLI 不会在命令之间记住配置文件,因此选择一个配置文件绝不会改变另一个终端或代理使用的内容。

值的保存位置

已保存的值位于 CLI 状态目录中的 context.json 中: 每个值都属于保存它的帐户,因此其他帐户不会使用它。auth logout 会保留已保存的值,以同一帐户重新登录即可恢复这些值。

参数和选项

行为

get 返回已登录的 account、profile,以及由 key 和 value 组成的 values 数组,未保存的键对应 null。它显示的是已保存的内容,而不是命令将使用的内容;若要查看后者,请使用 --verbose 运行该命令。在未登录状态下,get 不显示任何值,并说明如何登录。 set、unset 和 profile 命令需要已登录的帐户。set 不会向服务检查该值,因此你无法使用的卖家会在第一个发送它的命令上失败。 服务主体没有已保存的上下文。在服务主体模式下,需要登录的命令会拒绝 --profile 和 XBOX_PROFILE,并且除 key list 之外的每个 context 命令都会失败。请改为通过各值的选项或 XBOX_ 变量传递每个值。请参阅自动化(服务主体)身份验证。

并非来自命令行的值

已保存的上下文由你的操作系统用户运行的每个终端和代理共享,而环境变量不会出现在命令行上。因此,除了指明其填充的每个值之外:
  • 目标为上下文值本身的操作必须在命令行上提供该值。/Admin/DeleteTitle 会删除游戏,playfab api-policy set --overwrite 会替换其整个 API 访问策略,因此它们都会拒绝来自已保存上下文或变量的游戏,并打印应改为运行的命令:
    打印的命令会省略内联的 --body 或 --statements 值,因为请求正文可能包含机密。请将该值放回 <body> 或 <statements> 的位置。
  • 如果在使用已保存值的命令运行期间(例如在等待确认时)有其他帐户登录,该命令会在发送任何内容之前停止。请再次运行它。
有关确认规则,请参阅安全性和破坏性操作。

表格输出

每个上下文命令都接受 --output table:

示例

列出可以保存的键:
保存卖家和 PlayFab 游戏,并检查已保存的内容:
运行使用已保存值的命令,并查看游戏的来源:
删除一个已保存的值:
删除所选配置文件中保存的每个值:
有关设置的信息,请参阅配置;上下文不会更改这些设置。
最后修改于 2026年11月19日