> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 上下文

> 保存默认值(例如卖家和 PlayFab 游戏),供后续命令使用;如果需要多组值,可保存在命名配置文件中。

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

## 命令

| 命令 | 说明 |
| - | - |
| `context get` | 显示已保存的值。 |
| `context set` | 保存一个值。 |
| `context unset` | 删除已保存的值。 |
| `context key list` | 列出可以保存的键以及使用每个键的命令。无需登录。 |
| `context profile list` | 列出你的配置文件,从 `default` 开始。 |
| `context profile delete` | 删除命名配置文件及其中保存的每个值。 |

## 键

键是它所填充的选项的名称:

| 键 | 选项 | 变量 | 使用者 |
| - | - | - | - |
| `playfab-title-id` | `--playfab-title-id` | `XBOX_PLAYFAB_TITLE_ID` | [`playfab`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab) 命令 |
| `sandbox-id` | `--sandbox-id` | `XBOX_SANDBOX_ID` | [`xbl`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl) `config status` 和 `config publish` |
| `seller-id` | `--seller-id` | `XBOX_SELLER_ID` | [`audience`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/audience)、[`game`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/game)、[`package`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/package)、[`playtest`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playtest)、[`sandbox`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/sandbox)、[`test-account`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/test-account) 和 [`xbl`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl) 命令 |
| `title-id` | `--title-id` | `XBOX_TITLE_ID` | [`xbl`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl#title-targeting) `config list`、`config status`、`config publish`,以及沙盒范围的 `config download` 和 `config save` |

其他选项均不接受已保存的值或变量。

`title-id` 是十六进制的 XBOX 游戏 ID(例如 `1234ABCD`),而不是 PlayFab 游戏 ID。`xbl` 命令使用它来查找游戏的服务配置标识符 (SCID),当你传递 `--scid` 时则忽略它。请参阅[游戏定位](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl.md#title-targeting)。

## 命令如何使用已保存的值

当命令接受这些选项之一时,它使用找到的第一个值:

1. 命令行上的选项,例如 `--seller-id`。
2. 该选项的 `XBOX_` 变量,例如 `XBOX_SELLER_ID`。空白变量视为未设置。
3. 在所选[配置文件](#profiles)中使用 `context set` 保存的值。

```bash theme={null}
xbox context set playfab-title-id ABC123
xbox playfab title-data get                                # uses ABC123
XBOX_PLAYFAB_TITLE_ID=DEF456 xbox playfab title-data get   # uses DEF456
xbox --playfab-title-id GHI789 playfab title-data get      # uses GHI789
```

来自变量或已保存上下文的值与键入的值一样会经过检查,错误会指明值的来源,例如 `XBOX_SELLER_ID: --seller-id must be a positive numeric value.` 如果没有任何来源提供命令所需的值,命令会说明如何设置一个值。卖家为可选项的命令(`xbl` 和 `test-account`)会使用你唯一获得授权的卖家。

进行更改的命令会将其填充的每个值及其来源写入 stderr,即使使用了 `--confirm` 也是如此。使用 `--verbose` 时,每个命令都会这样做:

```text theme={null}
Using --playfab-title-id ABC123 from saved context.
```

[已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md)介绍了两个问题,这些问题会导致 `game` 和 `sandbox` 命令使用的卖家与按此方式选择的卖家不同。

## 配置文件

配置文件是一组命名的已保存值,例如一个用于测试游戏,一个用于生产环境。命令使用 `--profile` 指定的配置文件;如果未指定,则使用 `XBOX_PROFILE` 指定的配置文件;否则使用 `default`。

```bash theme={null}
xbox --profile test context set playfab-title-id TEST1   # creates "test"
xbox --profile test playfab title-data get               # uses TEST1
xbox playfab title-data get                              # uses the default profile
```

若要在某个 shell 中为每个命令使用一个配置文件,请设置 `XBOX_PROFILE`:

```bash theme={null}
export XBOX_PROFILE=test
```

列出你的配置文件:

```bash theme={null}
xbox context profile list
```

删除配置文件及其中保存的每个值:

```bash theme={null}
xbox context profile delete test
```

* 将第一个值保存到配置文件时会创建该配置文件。名称由字母、数字和连字符组成,最多 64 个字符,不区分大小写。

* 不存在的配置文件(例如拼写错误的配置文件)会导致失败,而不是回退到 `default`。

* 配置文件不会从 `default` 借用值。

* `XBOX_` 变量仍然优先于配置文件。当某个变量优先于 `--profile` 指定的配置文件时,命令会给出提示,即使它不做任何更改:

  ```text theme={null}
  Using --playfab-title-id PROD1 from XBOX_PLAYFAB_TITLE_ID, not profile test.
  ```

* CLI 不会在命令之间记住配置文件,因此选择一个配置文件绝不会改变另一个终端或代理使用的内容。

## 值的保存位置

已保存的值位于 CLI 状态目录中的 `context.json` 中:

| 操作系统 | 目录 |
| - | - |
| Windows | `%LOCALAPPDATA%\XboxDevCLI` |
| macOS | `~/Library/Application Support/XboxDevCLI` |
| Linux | `$XDG_DATA_HOME/XboxDevCLI`,默认为 `~/.local/share/XboxDevCLI` |

每个值都属于保存它的帐户,因此其他帐户不会使用它。`auth logout` 会保留已保存的值,以同一帐户重新登录即可恢复这些值。

## 参数和选项

| 参数或选项 | 命令 | 说明 |
| - | - | - |
| `<key> <value>` | `set` | 要保存的键及其值。该值必须对键的选项有效:`seller-id` 为正数(请参阅 [`xbox seller list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/seller)),`playfab-title-id` 由字母和数字组成。 |
| `<key>...` | `unset` | 要删除的键。删除未保存的键也会成功。 |
| `<name>` | `profile delete` | 要删除的配置文件。无法删除 `default`。 |
| `--profile <name>` | 全部 | 使用此配置文件,而不是 `XBOX_PROFILE` 指定的配置文件或 `default`。这是一个[全局选项](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md)。 |
| `--all` | `unset` | 删除所选配置文件中保存的每个值。不能与键名结合使用。 |
| `--base-url <url>` | `get`、`set`、`unset` | 替代 `XboxPartner:BaseUrl` 设置。已保存的卖家值属于保存它们时所用的终结点。 |
| `--output <format>` | 全部 | `json`(默认)、`json-compact` 或 `table`。 |

## 行为

`get` 返回已登录的 `account`、`profile`,以及由 `key` 和 `value` 组成的 `values` 数组,未保存的键对应 `null`。它显示的是已保存的内容,而不是命令将使用的内容;若要查看后者,请使用 `--verbose` 运行该命令。在未登录状态下,`get` 不显示任何值,并说明如何登录。

`set`、`unset` 和 `profile` 命令需要已登录的帐户。`set` 不会向服务检查该值,因此你无法使用的卖家会在第一个发送它的命令上失败。

服务主体没有已保存的上下文。在服务主体模式下,需要登录的命令会拒绝 `--profile` 和 `XBOX_PROFILE`,并且除 `key list` 之外的每个 `context` 命令都会失败。请改为通过各值的选项或 `XBOX_` 变量传递每个值。请参阅[自动化(服务主体)身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

## 并非来自命令行的值

已保存的上下文由你的操作系统用户运行的每个终端和代理共享,而环境变量不会出现在命令行上。因此,除了指明其填充的每个值之外:

* 目标为上下文值本身的操作必须在命令行上提供该值。`/Admin/DeleteTitle` 会删除游戏,`playfab api-policy set --overwrite` 会替换其整个 API 访问策略,因此它们都会拒绝来自已保存上下文或变量的游戏,并打印应改为运行的命令:

  ```text theme={null}
  $ xbox playfab api /Admin/DeleteTitle --confirm
  Using --playfab-title-id ABC123 from saved context.
  '/Admin/DeleteTitle' acts on playfab-title-id ABC123, which comes from saved context.
  The target of a destructive operation must be named on the command line. To proceed, run:
    xbox --playfab-title-id ABC123 playfab api /Admin/DeleteTitle --confirm
  ```

  打印的命令会省略内联的 `--body` 或 `--statements` 值,因为请求正文可能包含机密。请将该值放回 `<body>` 或 `<statements>` 的位置。

* 如果在使用已保存值的命令运行期间(例如在等待确认时)有其他帐户登录,该命令会在发送任何内容之前停止。请再次运行它。

有关确认规则,请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

## 表格输出

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

| 命令 | 列 |
| - | - |
| `context get`、`set`、`unset` | `KEY`、`VALUE` |
| `context key list` | `KEY`、`USED BY` |
| `context profile list`、`profile delete` | `NAME` |

## 示例

列出可以保存的键:

```bash theme={null}
xbox context key list --output table
```

保存卖家和 PlayFab 游戏,并检查已保存的内容:

```bash theme={null}
xbox context set seller-id 1234567
xbox context set playfab-title-id ABC123
xbox context get --output table
```

运行使用已保存值的命令,并查看游戏的来源:

```bash theme={null}
xbox game list
xbox --verbose playfab title-data get
```

删除一个已保存的值:

```bash theme={null}
xbox context unset playfab-title-id
```

删除所选配置文件中保存的每个值:

```bash theme={null}
xbox context unset --all
```

有关设置的信息,请参阅[配置](https://docs.xbox.com/zh-CN/tools/xbox-cli/configuration.md);上下文不会更改这些设置。


## Related topics

- [制作游戏 - 上下文](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy-v2/tutorials/craftingGame/game-context.md)
- [使用 Azure Functions 的 PlayFab CloudScript 上下文模型](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/CloudScript-af-context.md)
- [向排行榜添加上下文数据](https://docs.xbox.com/zh-CN/services/playfab/community/leaderboards/metadata-leaderboards.md)
- [SHAPE_CONTEXTS](https://docs.xbox.com/zh-CN/reference/audio/acphal/structs/shape_contexts.md)
- [ACP_COMMAND_ENABLE_OR_DISABLE_XMA_CONTEXTS](https://docs.xbox.com/zh-CN/reference/audio/acphal/structs/acp_command_enable_or_disable_xma_contexts.md)
