CloudScript から Webhook 呼び出しを行う - XBOX Game Development Documentation

CloudScript のあまり知られていない機能の 1 つは、標準的な Representational State Transfer (REST) 呼び出しを使用して、任意の Web API エンドポイントに Webhook 呼び出しを行える点です。

可能であれば、より新しい CloudScript Functions を使用して Webhook 呼び出しを行うことをお勧めします。

これにより、タイトルは基本的な情報サービスに対して呼び出しを行えるだけでなく、より複雑なシナリオ (OAuth の使用など) を実現し、自分が所有するエンドポイントとの通信を保護することも可能になります。このチュートリアルでは、非セキュア および セキュア な両方のシナリオについて、CloudScript からの Webhook 呼び出しについて説明します。

アウトバウンドの CloudScript 呼び出しに使用される IP アドレスを許可リストに追加する必要がある場合は、Developer Portal の 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
    }
}

しかし、通信する必要のある セキュア なサービスがある場合は、まずそのサービスと資格情報を交換して ID を確立する必要があります。 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 内でプレイヤーの不正行為や、アクセスすべきでない機能やデータへのアクセスを防ぐために必要な保護が備わっているということです。