API 存取原則 - XBOX Game Development Documentation

API 存取原則可控制對 API 資源的存取。有時，基於防作弊或其他安全性目的，遊戲需要允許或拒絕遊戲用戶端使用特定 API。您可以使用原則陳述式來控制存取，以指定一組在特定情況下套用的存取規則。本主題討論如何使用 API 權限原則來建立適當的規則。您也可以直接在 Game Manager 中管理遊戲的 API 存取原則。如需詳細資訊，請參閱 Game Manager 中的 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"
        }
    ]

每組權限陳述式都包含下列項目，如 Authentication - Update Policy 中所定義：

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 呼叫：

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

API 存取原則範例

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

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

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 存取原則範例