API 访问策略 - XBOX Game Development Documentation

API 访问策略控制对 API 资源的访问。有时，出于反作弊或其他安全目的，游戏需要允许或拒绝游戏客户端调用某些 API。你可以使用策略语句来控制访问，从而指定一组在特定情况下应用的访问规则。本主题讨论如何使用 API 权限策略来创建相应的规则。你也可以直接在游戏管理器中管理游戏的 API 访问策略。有关详细信息，请参阅游戏管理器中的 API 访问策略。

本指南讨论高级技术。如果应用不当，可能会使用此功能完全禁用客户端对游戏的访问。

策略控制和结构

游戏使用 PlayFab Admin API 调用来检索和更新访问策略。用于设置 API 访问策略的两个具体调用为 GetPolicy 和 UpdatePolicy。有关 Admin API 调用的详细信息，请参阅 PlayFab API 参考。若要使用 Admin API，你必须提供与游戏关联的开发者密钥。开发者密钥用于授权你的游戏进行 Admin API 调用。有关检索密钥的信息，请参阅密钥管理。每个策略都包含一个语句列表，这些语句作为一个或多个 PlayFab 资源的规则。PlayFab 定义了一组默认策略语句，允许所有策略。如果在不替换该组语句的情况下删除它，你的游戏将无法调用 Client API。默认的 PlayFab 策略语句：

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

正如身份验证 - 更新策略中所定义，每组权限语句包含以下项：

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 调用：

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

API 访问策略示例

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

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

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()));
}

下图显示了首次运行代码后的输出示例。如图所示，该策略由多个权限语句组成。

​策略控制和结构

​API 访问策略示例

策略控制和结构

API 访问策略示例