> ## 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.

# API 策略

> 读取和更新游戏的 API 访问策略,该策略控制哪些调用方可以使用哪些 PlayFab API。

读取和更新游戏的 API 访问策略,即控制哪些调用方可以使用哪些 PlayFab API 的语句。错误的策略可能会将所有玩家锁定在游戏之外。你需要对该游戏拥有 **Admin** 权限;请参阅
[PlayFab 身份验证的工作原理](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#how-playfab-authentication-works)。

| 命令 | PlayFab API 路径 | 说明 |
| - | - | - |
| `playfab api-policy get` | `/Admin/GetPolicy` | 获取策略的语句和版本。 |
| `playfab api-policy set` | `/Admin/UpdatePolicy` | 向策略添加语句,或替换策略。 |

`api-policy` 命令不接受 `--output table`。

| 选项 | 命令 | 必需 | 说明 |
| - | - | - | - |
| `--policy-name` | `get`、`set` | 否 | 策略。默认为 `ApiPolicy`。 |
| `--statements` | `set` | 二者之一 | 语句,以内联 JSON 数组的形式提供。 |
| `--statements-file` | `set` | 二者之一 | 以 JSON 数组形式包含语句的文件。 |
| `--policy-version` | `set` | 是 | 策略的当前版本,由 `get` 返回。如果策略在此之后已更改,PlayFab 会拒绝更新。 |
| `--overwrite` | `set` | 否 | 替换策略中的每个语句,而不是向其中添加语句。请参阅[替换策略](#replace-the-policy)。 |

## 添加语句

读取当前策略及其版本:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api-policy get
```

将要添加的语句放入文件中。此 `policy.json` 拒绝所有调用方使用 Server API 的
`DeleteCharacterFromUser`:

```json theme={null}
[
  {
    "Resource": "pfrn:api--/Server/DeleteCharacterFromUser",
    "Action": "*",
    "Effect": "Deny",
    "Principal": "*",
    "Comment": "Disable server character delete"
  }
]
```

* `Resource` 是 `pfrn:api--` 加上 API 路径,或者是表示所有 API 的 `pfrn:api--*`。
* `Action` 为 `*`,这是 PlayFab 接受的唯一值。
* `Effect` 为 `Allow` 或 `Deny`。
* `Principal` 为 `*` 时匹配所有调用方。
* `Comment` 是可选文本,供你自己记录。
* `ApiConditions` 是可选的,用于设置条件,例如
  `{ "HasSignatureOrEncryption": "True" }`,该条件接受 `Any`、`True` 或 `False`。

字段名称不区分大小写。无法识别的字段(例如拼写错误的
`ApiConditions`)会导致错误,因为丢弃该字段可能会扩大语句所允许的范围。
PlayFab 的 [API 访问策略](https://learn.microsoft.com/gaming/playfab/api-references/api-access-policy)
页面介绍了每个字段,并展示了允许所有 API 的默认策略。

然后添加语句,并传递 `get` 返回的版本:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api-policy set --policy-version 3 --statements-file policy.json
```

## 替换策略

> [!CAUTION]
>
> `--overwrite` 会使用你传递的语句替换整个策略,并丢弃你未包含的每个语句。CLI 无法还原以前的策略,因此请先保存 `get` 的输出。

`--overwrite` 需要 `--confirm`,并且需要在同一命令中使用 `--playfab-title-id` 指定游戏。即使使用了
`--confirm`,它也会拒绝来自 `XBOX_PLAYFAB_TITLE_ID` 或已保存上下文的游戏,并输出应改为运行的命令:

```text theme={null}
$ xbox playfab api-policy set --policy-version 3 --statements-file policy.json --overwrite --confirm
Using --playfab-title-id ABC123 from saved context.
'/Admin/UpdatePolicy' with --overwrite 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-policy set --policy-version 3 --statements-file policy.json --overwrite --confirm
```


## Related topics

- [验证 API 策略](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/admin/authentication/validate-api-policy.md)
- [Economy v2 设置概览](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy-v2/settings.md)
- [玩家加密服务](https://docs.xbox.com/zh-CN/services/playfab/identity/player-identity/encryption/player-encryption-services.md)
- [API 访问策略](https://docs.xbox.com/zh-CN/services/playfab/api-references/api-access-policy.md)
- [Game Manager 中的 API 访问策略](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/gamemanager/api-access-page-doc.md)
