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

# API 存取原則

> 說明如何在 PlayFab 中使用 API 存取原則。

API 存取原則可控制對 API 資源的存取。有時，基於防作弊或其他安全性目的，遊戲需要允許或拒絕遊戲用戶端使用特定 API。您可以使用原則陳述式來控制存取，以指定一組在特定情況下套用的存取規則。

本主題討論如何使用 API 權限原則來建立適當的規則。

您也可以直接在 Game Manager 中管理遊戲的 API 存取原則。如需詳細資訊，請參閱 [Game Manager 中的 API 存取原則](/zh-TW/services/playfab/live-service-management/gamemanager/api-access-page-doc)。

<Info>
  本指南討論進階技術。如果套用不當，使用此功能可能會完全停用用戶端對遊戲的存取。
</Info>

## 原則控制與結構

遊戲使用 PlayFab Admin API 呼叫來擷取和更新存取原則。用來設定 API 存取原則的兩個特定呼叫是 [GetPolicy](xref:titleid.playfabapi.com.admin.authentication.getpolicy) 和 [UpdatePolicy](xref:titleid.playfabapi.com.admin.authentication.updatepolicy)。如需 Admin API 呼叫的詳細資訊，請參閱 [PlayFab API 參考](https://learn.microsoft.com/en-us/rest/api/services/services/playfab/admin/)。

若要使用 Admin API，您必須提供與遊戲相關聯的開發人員秘密金鑰。開發人員金鑰用於授權您的遊戲進行 Admin API 呼叫。如需擷取秘密金鑰的相關資訊，請參閱[秘密金鑰管理](/zh-TW/services/playfab/live-service-management/gamemanager/secret-key-management)。

每個原則都包含一份陳述式清單，作為一或多個 PlayFab 資源的規則。PlayFab 定義了一組允許所有原則的預設原則陳述式。如果您刪除這組原則陳述式而未加以取代，您的遊戲將無法呼叫 Client API。

預設的 PlayFab 原則陳述式：

```json theme={null}
    "Statements": [
        {
            "Resource": "pfrn:api--*",
            "Action": "*",
            "Effect": "Allow",
            "Principal": "*",
            "Comment": "The default allow all policy"
        }
    ]
```

每組權限陳述式都包含下列項目，如 [Authentication - Update Policy](xref:titleid.playfabapi.com.admin.authentication.updatepolicy#permissionstatement) 中所定義：

* Resource - 唯一識別一或多個 PlayFab 資源的字串。若要描述 API 資源，請使用下列慣例。`pfrn:api--/API-GROUP/API-CALL` 將 Client API 指定為 `API-GROUP`：`Client`、`Server` 或 `Admin`。將 `API-CALL` 取代為 API 名稱，例如 `ConfirmPurchase`、`LoginWithTwitch` 或 `ReportPlayer`。資源字串支援萬用字元。下列資源字串會比對任何資源。`pfrn:api--*`
* Action - 描述要對資源執行之作業的字串。使用 `*` 以比對任何作業。
* Effect - 指定規則定義的字串。使用 `Allow` 或 `Deny` 以允許或拒絕對資源的作業。
* Principal - 唯一識別使用者類別的字串。使用 `*` 以比對任何使用者。
* Comment - 使用者定義的字串，提供有關原則陳述式的更多資訊。
* ApiConditions - 定義進階規則條件的\_選用物件\_，例如加密和簽署標頭。

您可以修改原則，使用更詳細的權限陳述式，只允許您應用程式中所使用的 API 存取，藉此為應用程式設定強固的安全性規則。

下列範例示範如何限制 `DeleteCharacterFromUser` 呼叫：

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

## API 存取原則範例

下列程式碼範例示範原則的基本作業。此程式碼會執行下列動作：

* 擷取並記錄現有的**原則**。
* 更新原則。
* 再次擷取並記錄現有的**原則**。

```csharp theme={null}
public void Start() {
    PlayFabSettings.staticSettings.DeveloperSecretKey = "<insert key here>";
    PlayFabSettings.TitleId = "< insert title id here >";
    FetchApiPolicy(UpdateApiPolicy);
}

private void FetchApiPolicy(Action nextAction = null) {
    PlayFabAdminAPI.GetPolicy(new GetPolicyRequest() {
        PolicyName = "ApiPolicy"
    }, result => {
        Debug.Log(result.PolicyName);
        foreach (var statement in result.Statements)
        {
            Debug.Log("Action: "+ statement.Action);
            Debug.Log("Comment: "+ statement.Comment);
            if(statement.ApiConditions != null)
                Debug.Log("ApiCondition.HashSignatureOrEncryption: "+ statement.ApiConditions.HasSignatureOrEncryption);
            Debug.Log("Effect: "+ statement.Effect);
            Debug.Log("Principal: "+statement.Principal);
            Debug.Log("Resource: "+ statement.Resource);
        }

        if (nextAction != null) nextAction();

    },error=>Debug.LogError(error.GenerateErrorReport()));
}

private void UpdateApiPolicy() {
    PlayFabAdminAPI.UpdatePolicy(new UpdatePolicyRequest() {
        PolicyName = "ApiPolicy",
        OverwritePolicy = false, // Append to existing policy. Set to True, to overwrite.
        Statements = new List<PermissionStatement>() {
            new PermissionStatement() {
                Action = "*", // Statement effects Execute action
                ApiConditions = new ApiCondition() {
                    HasSignatureOrEncryption = Conditionals.False // Require no RSA encrypted payload or signed headers
                },
                Comment = "Do not allow clients to confirm purchase",
                Resource = "pfrn:api--/Client/ConfirmPurchase", // Resource name
                Effect = EffectType.Deny, // Do not allow,
                Principal = "*"
            }
        }
    }, result => {
        FetchApiPolicy();
    }, error => Debug.LogError(error.GenerateErrorReport()));
}
```

下圖顯示第一次執行程式碼後的輸出範例。如圖所示，原則由數個[權限陳述式](xref:titleid.playfabapi.com.admin.authentication.updatepolicy#permissionstatement)組成。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/playfab/api-references/images/game-manager-admin-api-get-update-policy-csharp-output.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=2cfa94f6daa0d6e7cda3041bbb8d04a4" alt="Game Manager - Admin API - 取得/更新原則 - C# 輸出" width="656" height="535" data-path="images/playfab/api-references/images/game-manager-admin-api-get-update-policy-csharp-output.png" />


## Related topics

- [Game Manager 中的 API 存取原則](/zh-TW/services/playfab/live-service-management/gamemanager/api-access-page-doc.md)
- [PlayFab API 的 Microsoft Entra ID 驗證](/zh-TW/services/playfab/identity/dev-identity/authentication/entra-id-api-authentication.md)
- [PlayFab 基礎](/zh-TW/services/playfab/get-started/index.md)
- [存取原則](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/access-policies/index.md)
- [存取原則概觀](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/access-policies/live-access-policies-overview.md)