Appels de webhooks depuis CloudScript - XBOX Game Development Documentation

L’une des fonctionnalités méconnues de CloudScript est la possibilité d’effectuer des appels de webhooks vers n’importe quel point de terminaison d’API web, à l’aide d’appels REST (Representational State Transfer) standard.

Nous vous recommandons d’effectuer les appels de webhooks à l’aide des fonctions CloudScript, plus récentes, lorsque cela est possible.

Cela permet aux titres d’appeler des services d’information de base, mais également de mettre en œuvre des scénarios plus complexes (comme l’utilisation d’OAuth) afin de sécuriser une communication avec un point de terminaison qui vous appartient. Ce tutoriel traite des appels de webhooks depuis CloudScript, pour des scénarios non sécurisés et sécurisés.

Si vous devez ajouter à une liste d’autorisation les adresses IP utilisées pour les appels CloudScript sortants, consultez la section « PlayFab static IP prefixes and addresses » de la page API Features du portail de développeur.

S’agissant d’un appel REST, la structure d’un appel de webhook depuis CloudScript est simple. Les éléments à spécifier sont les suivants :

Le point de terminaison URL.
La méthode REST (post, get, put ou delete).
Les en-têtes éventuellement requis.
Le type de contenu (le plus souvent application/JSON).
Le contenu lui-même (corps).

Par exemple, un appel d’API web de base visant à obtenir le numéro de version de votre logique côté serveur pourrait ressembler à l’exemple ci-dessous.

// 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);

Le corps de la réponse est retourné sous forme de chaîne, afin que vous puissiez l’utiliser ensuite dans le reste du script. Dans ce cas, comme nous demandions la version, vous pourriez écrire la réponse dans le log comme ici.

// CloudScript
log.info(responseString);

La réponse retournée au client à la fin de l’exécution du CloudScript pourrait ressembler à l’exemple ci-dessous.

//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
    }
}

Si, en revanche, vous devez communiquer avec un service sécurisé, vous devrez d’abord échanger des informations d’identification avec ce service pour établir votre identité. Pour une solution OAuth, cela signifie demander un jeton d’accès Bearer à l’aide de votre ID client et de votre secret. Cela varie selon votre implémentation OAuth spécifique, mais votre appel pourrait ressembler à l’exemple suivant.

//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);

Avec une réponse valide, vous pourriez ensuite extraire le bearer_access_token de la réponse comme suit (là encore, cela dépend des spécificités de votre implémentation OAuth, mais il s’agit d’un modèle assez courant pour cette forme d’authentification).

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

Vous pourriez alors appeler votre fonctionnalité sécurisée par OAuth en fournissant le bearer_access_token.

//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;

Le modèle de base consiste donc ici à utiliser l’ID client et le secret de votre application afin d’obtenir le jeton d’accès Bearer unique pour l’appel, puis à l’utiliser pour sécuriser cet appel. Comme vous pouvez le constater, ces appels seraient tous effectués au moyen de SSL, afin de contribuer à prévenir les attaques de l’intercepteur (man-in-the-middle). Grâce aux appels HTTP depuis CloudScript, vous pouvez appeler n’importe quelle autre API web dont votre titre a besoin. Vous pouvez ainsi étendre les fonctionnalités de votre titre au-delà de ce que PlayFab propose directement, avec la possibilité de créer et d’utiliser vos propres services personnalisés, ou d’accéder à d’autres services. Comme tout se déroule dans CloudScript, ces appels sont effectués dans un contexte faisant autorité côté serveur. Ils bénéficient donc des protections nécessaires dans votre CloudScript pour aider à empêcher les joueurs de tricher ou d’accéder à des fonctionnalités et des données auxquelles ils ne devraient pas avoir accès.