从 CloudScript 发出 Webhook 调用 - XBOX Game Development Documentation

CloudScript 中一个鲜为人知的功能是,你可以使用标准的表示层状态转移 (REST) 调用从中向任何 Web API 终结点发出 Webhook 调用。

我们建议尽可能使用较新的 CloudScript Functions 进行 Webhook 调用。

这允许游戏调用基本的信息服务,但也支持更复杂的场景(例如使用 OAuth),以保护与你所拥有的终结点之间的通信。本教程讨论从 CloudScript 发出 Webhook 调用,涵盖非安全和安全两种场景。

如果你需要将出站 CloudScript 调用所使用的 IP 地址加入允许列表,可以参阅开发者门户 API 功能页上的 “PlayFab static IP prefixes and addresses”(PlayFab 静态 IP 前缀和地址)部分。

作为一个 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 解决方案,这意味着使用你的客户端 ID 和密钥请求 Bearer Access 令牌。具体做法取决于你的 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;

因此,这种情况下的基本模式是:你使用应用程序的客户端 ID 和密钥,以便为该调用获取唯一的 Bearer Access 令牌,然后使用它来保护该调用。如你所见,所有这些调用都将使用 SSL 进行,以帮助防止中间人攻击。通过从 CloudScript 发出 HTTP 调用,你可以调用任何你游戏所需的其他 Web API。这使你能够将游戏功能扩展到超出 PlayFab 直接提供的范围,并让你可以选择创建和使用自己的自定义服务,或访问其他服务。由于这一切都发生在 CloudScript 内,因此它提供了一个具有服务器权威性的上下文来进行这些调用。这意味着它们将在你的 CloudScript 中受到必要的保护,以帮助防止玩家作弊或访问他们不应访问的功能和数据。