Realizar llamadas de webhook desde CloudScript - XBOX Game Development Documentation

Una de las características menos conocidas de CloudScript es que puede realizar llamadas de webhook desde él a cualquier punto de conexión de API web, mediante llamadas estándar de transferencia de estado representacional (REST).

Le recomendamos realizar las llamadas de webhook mediante las más recientes funciones de CloudScript cuando sea posible.

Esto permite que los títulos realicen llamadas a servicios informativos básicos, pero también habilita escenarios más complejos (como el uso de OAuth), para proteger la comunicación con un punto de conexión de su propiedad. Este tutorial trata sobre cómo realizar llamadas de webhook desde CloudScript, tanto para escenarios no seguros como seguros.

Puede consultar la sección ‘PlayFab static IP prefixes and addresses’ de la página API Features en el portal para desarrolladores si necesita incluir en la lista de permitidos las direcciones IP usadas para las llamadas salientes de CloudScript.

Al tratarse de una llamada REST, la estructura de una llamada de webhook desde CloudScript es sencilla. Los elementos que se deben especificar son:

El punto de conexión de la dirección URL.
El método REST (post, get, put o delete).
Cualquier encabezado necesario.
El tipo de contenido (normalmente application/JSON).
El propio contenido (cuerpo).

Por ejemplo, una llamada básica a una API web para obtener el número de versión de su lógica del lado servidor podría ser similar al ejemplo que se proporciona a continuación.

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

El cuerpo de la respuesta se devuelve en forma de cadena, de modo que pueda usarlo posteriormente en el resto del script. En este caso, dado que consultábamos la versión, podría escribir la respuesta en el log como en el ejemplo que se proporciona aquí.

// CloudScript
log.info(responseString);

La respuesta devuelta al cliente al final de la ejecución del CloudScript podría ser similar al ejemplo que se proporciona a continuación.

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

Sin embargo, si necesita comunicarse con un servicio seguro, primero deberá intercambiar credenciales con ese servicio para establecer la identidad. Para una solución OAuth, eso significa solicitar un token de acceso de portador (Bearer), usando su identificador de cliente y su secreto. Esto varía según su implementación específica de OAuth, pero su llamada podría ser similar al siguiente ejemplo.

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

Si la respuesta es correcta, entonces podría analizar el bearer_access_token de la respuesta de esta manera (de nuevo, esto depende de los detalles específicos de su implementación de OAuth, pero se trata de un patrón bastante común para esta forma de autenticación).

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

Esto le permitiría entonces llamar a su funcionalidad protegida con OAuth proporcionando el 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;

Así pues, el patrón básico en este caso consiste en usar el identificador de cliente y el secreto de su aplicación para obtener el token de acceso de portador único para la llamada, y luego usarlo para proteger esa llamada. Como puede ver, todas estas llamadas se realizarían mediante SSL, con el fin de ayudar a evitar ataques de intermediario (“man-in-the-middle”). Mediante las llamadas HTTP desde CloudScript, puede realizar llamadas a cualquier otra API web que necesite para su título. Esto le permite extender la funcionalidad de su título incluso más allá de lo que PlayFab ofrece directamente, dándole la opción de crear y usar sus propios servicios personalizados, o de acceder a otros. Dado que todo esto ocurre dentro de CloudScript, proporciona un contexto autoritativo del servidor en el que realizar esas llamadas. Esto significa que tendrán las protecciones necesarias en su CloudScript para ayudar a evitar que los jugadores hagan trampas o accedan a características y datos que no deberían.