從 CloudScript 進行 Webhook 呼叫 - XBOX Game Development Documentation

CloudScript 一項較不為人知的功能，是您可以從中使用標準的表述性狀態傳輸 (REST) 呼叫，對任何 Web API 端點進行 Webhook 呼叫。

建議您盡可能使用較新的 CloudScript Functions 進行 Webhook 呼叫。

這可讓遊戲呼叫基本的資訊服務，但它也能實現更複雜的情境 (例如使用 OAuth)，以保護與您所擁有之端點的通訊。本教學課程討論從 CloudScript 進行 Webhook 呼叫，涵蓋不安全和安全兩種情境。

如果您需要將用於輸出 CloudScript 呼叫的 IP 位址加入允許清單，可以參考開發人員入口網站中 API Features 頁面的「PlayFab static IP prefixes and addresses」一節。

作為 REST 呼叫，從 CloudScript 進行的 Webhook 呼叫結構很簡單。需要指定的元素包括：

URL 端點。
REST 方法 (post、get、put 或 delete)。
任何必要的標頭。
內容類型 (最常見的是 application/JSON)。
內容本身 (本文)。

例如，取得伺服器端邏輯版本號碼的基本 Web API 呼叫可能類似下列範例。

// CloudScript
var url = "http://api.yoursite.com/playfab_call/GetVersion";
var method = "post";
var contentBody = "";
var contentType = "application/json";
var headers = {};
var responseString =  http.request(url,method,contentBody,contentType,headers);

回應的本文會以字串化形式傳回，讓您可以在指令碼的其餘部分接著使用它。在此案例中，由於我們查詢的是版本，您可以將回應寫出至 log，如下所示。

// CloudScript
log.info(responseString);

執行 CloudScript 結束時傳回給用戶端的回應可能類似下列範例。

//HTTP Response
{
    "code": 200,
    "status": "OK",
    "data":
    {
        "FunctionName": "MyScript",
        "Revision": 23,
        "FunctionResult": true,
        "Logs": [
        {
            "Level": "Info",
            "Message": "{\"version\": 3}"
        }],
        "ExecutionTimeSeconds": 0.4309841,
        "MemoryConsumedBytes": 29608,
        "APIRequestsIssued": 0,
        "HttpRequestsIssued": 1
    }
}

不過，如果您需要與安全的服務通訊，則首先需要與該服務交換認證以建立身分。對於 OAuth 解決方案，這表示要使用您的用戶端識別碼和秘密要求持有人存取權杖。這會因您特定的 OAuth 實作而異，但您的呼叫可能類似下列範例。

//CloudScript
var url = "https://api.yoursite.com/playfab_call/request_token";
var method = "post";
var contentBody = "grant_type=client_credentials";
var contentType = "application/x-www-form-urlencoded";
var headers = {};
headers["client_id"] = clientId;
headers["client_secret"] = clientSecret;

var tokenResponse =  http.request(url,method,contentBody,contentType,headers);

如果回應良好，您接著就可以像這樣從回應中剖析 bearer_access_token (同樣地，這確實取決於您 OAuth 實作的具體細節，但這是此類驗證相當常見的模式)。

//CloudScript
var parsedData = JSON.parse(tokenResponse);
var bearer_access_token = parsedData["access_token"];

接著，您就可以透過提供 bearer_access_token 來呼叫受 OAuth 保護的功能。

//CloudScript
var url = "https://api.yoursite.com/playfab_call/do_action";
var method = "post";
var contentBody = customActionBody;
var contentType = "application/json";
var headers = {};
headers["authorization"] = "Bearer " + bearer_access_token;

因此，此案例的基本模式是使用應用程式的用戶端識別碼和秘密，以取得呼叫用的唯一持有人存取權杖，然後使用它來保護該呼叫。如您所見，這些呼叫都會使用 SSL 進行，以協助防止中間人攻擊。使用 CloudScript 中的 HTTP 呼叫，您可以呼叫遊戲所需的任何其他 Web API。這可讓您將遊戲功能擴充到甚至超越 PlayFab 直接提供的範圍，讓您可以選擇建立和使用自己的自訂服務，或存取其他服務。由於這一切都發生在 CloudScript 內，因此它提供了進行這些呼叫的伺服器授權內容。這表示它們在您的 CloudScript 中會具有必要的保護，以協助防止玩家作弊，或存取他們不應存取的功能和資料。