> ## 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-TW/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 路徑，或以 `pfrn:api--*` 代表每個 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-TW/services/playfab/api-references/rest/admin/authentication/validate-api-policy.md)
- [Economy v2 設定概觀](https://docs.xbox.com/zh-TW/services/playfab/economy-monetization/economy-v2/settings.md)
- [玩家加密服務](https://docs.xbox.com/zh-TW/services/playfab/identity/player-identity/encryption/player-encryption-services.md)
- [API 存取原則](https://docs.xbox.com/zh-TW/services/playfab/api-references/api-access-policy.md)
- [Game Manager 中的 API 存取原則](https://docs.xbox.com/zh-TW/services/playfab/live-service-management/gamemanager/api-access-page-doc.md)
