> ## 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 权限策略来创建相应的规则。

你也可以直接在游戏管理器中管理游戏的 API 访问策略。有关详细信息，请参阅[游戏管理器中的 API 访问策略](/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 调用。有关检索密钥的信息，请参阅[密钥管理](/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"
        }
    ]
```

正如[身份验证 - 更新策略](xref:titleid.playfabapi.com.admin.authentication.updatepolicy#permissionstatement)中所定义，每组权限语句包含以下项：

* Resource - 唯一标识一个或多个 PlayFab 资源的字符串。若要描述 API 资源，请使用下面所示的约定。`pfrn:api--/API-GROUP/API-CALL` 将 `API-GROUP` 指定为 Client API：`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 访问策略示例

以下代码示例演示对策略的基本操作。该代码执行以下操作：

* 检索并记录现有的 **Policy**。
* 更新策略。
* 再次检索并记录现有的 **Policy**。

```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="游戏管理器 - Admin API - Get-Update Policy - 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-CN/services/playfab/live-service-management/gamemanager/api-access-page-doc.md)
- [用于 PlayFab API 的 Microsoft Entra ID 身份验证](/zh-CN/services/playfab/identity/dev-identity/authentication/entra-id-api-authentication.md)
- [PlayFab 基础](/zh-CN/services/playfab/get-started/index.md)
- [访问策略](/zh-CN/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/access-policies/index.md)
- [访问策略概述](/zh-CN/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/access-policies/live-access-policies-overview.md)