> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Escribir CloudScript personalizado
> Escriba funciones de JavaScript de CloudScript de PlayFab personalizadas a las que se pueda llamar desde clientes de Unity, reglas de PlayStream y tareas programadas, con ejemplos de helloWorld.
CloudScript es una de las características más versátiles de PlayFab. Permite que el código de cliente solicite la ejecución de cualquier tipo de funcionalidad personalizada del lado servidor que pueda implementar, y puede usarse con prácticamente *cualquier cosa*. Además de las solicitudes de ejecución explícitas desde el código de cliente o de servidor, CloudScript puede ejecutarse en respuesta a eventos de PlayStream (mediante la creación de una *regla*) o como parte de una tarea programada.
[CloudScript con Azure Functions](/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart) mejora lo que hizo grande a CloudScript, con más lenguajes admitidos y mejores flujos de trabajo de depuración.
Este tutorial trata sobre la escritura de su código de CloudScript. Consulte el [inicio rápido de CloudScript](/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) para obtener ayuda con la carga de sus archivos de CloudScript en su título.
Este tutorial muestra ejemplos de código de Unity, pero CloudScript funciona de manera similar en todos los SDK.
Requisitos previos para este tutorial:
* [Entorno de **Unity** configurado con el **SDK de Unity** de PlayFab](/services/playfab/sdks/unity3d/quickstart)
* El identificador del título está establecido en el objeto `PlayFabSharedSettings`.
* El proyecto puede iniciar sesión correctamente con un usuario.
## Introducción: helloWorld
Nuestro ejemplo `helloWorld` funciona en un título completamente nuevo, sin modificaciones en Game Manager. El archivo de CloudScript predeterminado de un título nuevo incluye un controlador llamado `helloWorld`. Utiliza algunas características básicas: parámetros de entrada, registro, currentPlayerId y parámetros de devolución.
El siguiente ejemplo muestra el código de la función `helloWorld` predeterminada (sin los comentarios).
```javascript theme={null}
// CloudScript (JavaScript)
handlers.helloWorld = function (args, context) {
var message = "Hello " + currentPlayerId + "!";
log.info(message);
var inputValue = null;
if (args && args.hasOwnProperty("inputValue"))
inputValue = args.inputValue;
log.debug("helloWorld:", { input: inputValue });
return { messageValue: message };
}
```
### Análisis del código
El objeto handler está predefinido en el entorno de CloudScript de PlayFab. Debe agregar todas sus funciones de CloudScript a este objeto.
* `helloWorld` es una función disponible para su título y sus SDK, porque está definida en el objeto handler.
* `args` es un objeto arbitrario que proviene del autor de la llamada. Se analiza a partir de JSON y puede contener cualquier dato con cualquier formato.
Consulte **FunctionParameter** en la sección siguiente.
Debe tratar este objeto con confianza cero. Un cliente pirateado o un usuario malintencionado puede proporcionar aquí *cualquier* información en *cualquier* formato.
* `Context` es un parámetro avanzado. En este ejemplo, es *null*. Este parámetro está controlado por el servidor y es seguro.
* `currentPlayerId` es una variable global, que se establece en el PlayFabId del jugador que solicita esta llamada. Este parámetro está controlado por el servidor y es seguro. **Nota:** al usar la API ExecuteEntityCloudScript, este parámetro es null a menos que la entidad tenga un MasterPlayerID en su cadena de entidades.
* `log.info`: `log` es un objeto global. Se usa principalmente para depurar su CloudScript. El objeto `log` expone los métodos siguientes: `info`, `debug` y `error`. Hay más detalles más adelante en este tutorial.
* `return`: cualquier objeto que devuelva se serializa como JSON y se devuelve al autor de la llamada. Puede devolver cualquier objeto serializable en JSON con los datos que desee.
Es su responsabilidad si su CloudScript devuelve datos secretos a sus clientes. Un cliente pirateado o un usuario malintencionado puede examinar los datos devueltos, *incluso* si no los muestra al usuario durante el juego normal.
## Ejecución de funciones de CloudScript desde un cliente de juego de Unity
Llamar a una función de CloudScript desde un cliente es sencillo. Primero debe crear un `ExecuteCloudScriptRequest` y establecer la propiedad `ActionId` en el nombre de la función de CloudScript que desea ejecutar (en este caso sería `helloWorld`) y, después, enviar el objeto a PlayFab mediante nuestra API.
Solo puede llamar a los métodos de CloudScript adjuntos al objeto handlers de JavaScript.
Para ejecutar métodos de CloudScript, necesitará las siguientes líneas de código en su cliente.
```csharp theme={null}
// Build the request object and access the API
private static void StartCloudHelloWorld()
{
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest()
{
FunctionName = "helloWorld", // Arbitrary function name (must exist in your uploaded cloud.js file)
FunctionParameter = new { inputValue = "YOUR NAME" }, // The parameter provided to your function
GeneratePlayStreamEvent = true, // Optional - Shows this event in PlayStream
}, OnCloudHelloWorld, OnErrorShared);
}
// OnCloudHelloWorld defined in the next code block
```
### Análisis del código
[ExecuteCloudScriptRequest](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptrequest) es el tipo de solicitud para cualquier llamada a [PlayFabClientAPI.ExecuteCloudScript](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript).
* `ExecuteCloudScriptRequest.FunctionName` es una cadena. El valor debe coincidir con el nombre de la función definida en CloudScript. En este caso, `helloWorld`.
* `ExecuteCloudScriptRequest.FunctionParameter` puede ser cualquier objeto que se pueda serializar en JSON. Se convierte en el primer parámetro args de la función `helloWorld` (consulte args en la sección anterior).
* `ExecuteCloudScriptRequest.GeneratePlayStreamEvent` es opcional. Si es true, se publica un evento en PlayStream, que puede ver en Game Manager o utilizar para otros desencadenadores de PlayStream.
Según el lenguaje, la parte final de la línea `ExecuteCloudScript` implica realizar la solicitud al servidor de CloudScript de PlayFab, y la parte de control de *Result* y *Error*, específica del lenguaje.
Por ejemplo, en Unity, JavaScript o AS3, el control de Error y Result se proporciona mediante funciones de devolución de llamada.
El siguiente es un ejemplo de métodos de control de errores.
```csharp theme={null}
private static void OnCloudHelloWorld(ExecuteCloudScriptResult result) {
// CloudScript returns arbitrary results, so you have to evaluate them one step and one parameter at a time
Debug.Log(JsonWrapper.SerializeObject(result.FunctionResult));
JsonObject jsonResult = (JsonObject)result.FunctionResult;
object messageValue;
jsonResult.TryGetValue("messageValue", out messageValue); // note how "messageValue" directly corresponds to the JSON values set in CloudScript
Debug.Log((string)messageValue);
}
private static void OnErrorShared(PlayFabError error)
{
Debug.Log(error.GenerateErrorReport());
}
```
## Información general intermedia: variables globales y argumentos avanzados
CloudScript es un conjunto de funciones de JavaScript compiladas con V8 y hospedadas en los servidores de PlayFab. Tiene acceso a cualquier API de servidor enumerada en la [documentación de referencia de la API de PlayFab](/services/playfab/api-references), junto con un *registrador (logger)*, el identificador de PlayFab del jugador que realiza la solicitud de CloudScript y cualquier información incluida con la solicitud, todo ello en forma de objetos preestablecidos.
Las propias funciones de CloudScript son propiedades de un objeto handlers global. La siguiente tabla muestra una lista completa de estas variables predefinidas.
| Nombre | Uso |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **server** | Tiene acceso a todas las llamadas API del lado servidor enumeradas en la [documentación de referencia de la API de PlayFab](/services/playfab/api-references). Se pueden llamar (de forma sincrónica) así: `var result = server.AuthenticateUserTicket(request);` |
| **http** | Realiza solicitudes HTTP sincrónicas, así: `http.request(url, method, content, contentType, headers, logRequestAndResponse)`. El objeto `headers` contiene propiedades correspondientes a varios encabezados y sus valores. `logRequestAndResponse` es un valor booleano que determina si el título debe registrar cualquier error de la solicitud como parte de la respuesta. |
| **log** | Crea instrucciones de registro y las agrega a la respuesta. Los registros tienen tres niveles: `log.info()`, `log.debug()` y `log.error()`. Los tres niveles toman una cadena de mensaje, junto con un objeto opcional que contiene datos adicionales para incluir con el registro. Por ejemplo, `log.info('hello!', { time: new Date() });` |
| **currentPlayerId** | Identificador de PlayFab del jugador que desencadenó la llamada de CloudScript. |
| **handlers** | Objeto global que contiene todas las funciones de CloudScript de su título. Se pueden agregar o llamar funciones mediante este objeto. Por ejemplo, `handlers.pop = function() {};`, `handlers.pop();`. |
| **script** | Objeto global que contiene `Revision` y `titleId`. `Revision` representa el **número de revisión** del CloudScript que se está ejecutando actualmente y `titleId` representa el identificador del título actual. |
Además, todas las funciones de controlador reciben dos parámetros, que se detallan a continuación.
| Nombre | Uso |
| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **args** | Primer parámetro de una función de controlador. Una representación de objeto del campo `FunctionParameter` de una solicitud `ExecuteCloudscript`. |
| **context** | Segundo parámetro de una función de controlador. Información adicional sobre la solicitud cuando la desencadena una acción de evento de PlayStream, incluidos los [datos del evento](/services/playfab/api-references/events) que desencadenó la acción (context.playStreamEvent) y los [datos de perfil](xref:titleid.playfabapi.com.client.accountmanagement.getplayerprofile#playerprofilemodel) del jugador asociado a ella. (context.playerProfile) |
Se puede llamar a las funciones de CloudScript mediante la API `ExecuteCloudScript` o mediante una acción de evento de PlayStream preestablecida.
Puede encontrar todos los detalles sobre la respuesta a `ExecuteCloudScript` en [ExecuteCloudScriptResult](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptresult).
## Intermedio: FunctionParameter y args
En la sección anterior, describimos cómo rellenar `request.FunctionParameter` y ver esa información en el parámetro `args`. El [inicio rápido de CloudScript](/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) muestra cómo cargar un nuevo CloudScript.
Combinando ambos, podemos proporcionar otro ejemplo de cómo pasar argumentos del cliente a CloudScript. Tome el ejemplo anterior y modifique el código de CloudScript y su código de cliente como se muestra a continuación.
```javascript theme={null}
handlers.helloWorld = function (args) {
// ALWAYS validate args parameter passed in from clients (Better than we do here)
var message = "Hello " + args.name + "!"; // Utilize the name parameter sent from client
log.info(message);
return { messageValue: message };
}
```
```csharp theme={null}
// Build the request object and access the API
private static void StartCloudHelloWorld()
{
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest()
{
FunctionName = "helloWorld", // Arbitrary function name (must exist in your uploaded cloud.js file)
FunctionParameter = new { name = "YOUR NAME" }, // The parameter provided to your function
GeneratePlayStreamEvent = true, // Optional - Shows this event in PlayStream
}, OnCloudHelloWorld, OnErrorShared);
}
private static void OnCloudHelloWorld(ExecuteCloudScriptResult result) {
// CloudScript returns arbitrary results, so you have to evaluate them one step and one parameter at a time
Debug.Log(JsonWrapper.SerializeObject(result.FunctionResult));
JsonObject jsonResult = (JsonObject)result.FunctionResult;
object messageValue;
jsonResult.TryGetValue("messageValue", out messageValue); // note how "messageValue" directly corresponds to the JSON values set in CloudScript
Debug.Log((string)messageValue);
}
private static void OnErrorShared(PlayFabError error)
{
Debug.Log(error.GenerateErrorReport());
}
```
Después de realizar estos cambios, ahora puede enviar y recibir datos fácilmente entre CloudScript y sus clientes.
Es importante señalar que cualquier dato procedente de sus clientes es susceptible de piratería y explotación.
Siempre querrá validar los parámetros de entrada *antes* de actualizar su back-end. El proceso para validar los parámetros de entrada variará de un título a otro, pero la validación más básica comprobará que las entradas estén dentro de los intervalos y períodos aceptables.
## Intermedio: llamar a las API de servidor
Como se mencionó anteriormente, dentro de los métodos de CloudScript, tiene acceso al conjunto completo de llamadas API de servidor. Esto permite que su código en la nube actúe como un servidor dedicado.
Tareas comunes de servidor:
* Actualizar estadísticas y datos de los jugadores.
* Conceder artículos y moneda.
* Generar datos de juego aleatoriamente.
* Calcular de forma segura los resultados de las batallas y más...
Consulte las API de servidor enumeradas en nuestra [documentación de referencia de la API de PlayFab](/services/playfab/api-references) para conocer los parámetros necesarios y las estructuras de objetos.
El siguiente ejemplo procede del interior de un posible controlador de CloudScript.
```javascript theme={null}
// CloudScript (JavaScript)
//See: JSON.parse, JSON.stringify, parseInt and other built-in javascript helper functions for manipulating data
var currentState; // here we are calculating the current player's game state
// here we are fetching the "SaveState" key from PlayFab,
var playerData = server.GetUserReadOnlyData({"PlayFabId" : currentPlayerId, "Keys" : ["SaveState"]});
var previousState = {}; //if we return a matching key-value pair, then we can proceed otherwise we will need to create a new record.
if(playerData.Data.hasOwnProperty("SaveState"))
{
previousState = playerData.Data["SaveState"];
}
var writeToServer = {};
writeToServer["SaveState"] = previousState + currentState; // pseudo Code showing that the previous state is updated to the current state
var result = server.UpdateUserReadOnlyData({"PlayFabId" : currentPlayerId, "Data" : writeToServer, "Permission":"Public" });
if(result)
{
log.info(result);
}
else
{
log.error(result);
}
```
## Avanzado: acción de evento de PlayStream
Una función de CloudScript se puede configurar para que se ejecute en respuesta a un evento de PlayStream.
1. En cualquier explorador:
* Visite **Game Manager de PlayFab**.
* Busque su **título**.
* En **Build**, en la barra lateral, vaya a la pestaña **Automation**.
* Vaya a la pestaña **Rules**.
La página tendrá un aspecto similar al del ejemplo que se proporciona a continuación.
2. Use el botón **New Rule** para crear una nueva regla.
* Asigne un nombre a la nueva **regla**.
* Seleccione un **tipo de evento** que se usará como desencadenador de una condición o una acción.
* Para que la **regla** desencadene una función de CloudScript, agregue una **acción** con el botón de esa sección.
* Después, seleccione la opción en el menú desplegable **Type**.
* Seleccione la función **helloWorld** en el menú desplegable **Cloud Script Function**.
* Seleccione el botón **Save action**.
3. Esta **regla** ahora está configurada para desencadenarse con cualquier evento del tipo seleccionado. Para probarla:
* Marque la casilla **Publish results as PlayStream Event**.
* Guarde la **acción**.
* Después, desencadene un evento.
* En el **PlayStream Monitor**, debería aparecer un nuevo evento correspondiente a la ejecución de CloudScript que contenga la información adecuada.
* Para obtener más información sobre cómo comprobar un evento de PlayStream en el depurador, consulte la sección siguiente [Avanzado: depuración de CloudScript](#advanced-debugging-cloudscript).
Las acciones de eventos solo pueden usar la revisión activa al llamar a funciones de CloudScript. Si no encuentra la función **helloWorld** en la lista desplegable, esta es la razón más probable.
## Avanzado: depuración de CloudScript
La depuración es mucho más fácil con [CloudScript con Azure Functions](/services/playfab/live-service-management/service-gateway/automation/cloudscript-af). Obtenga más información sobre cómo usar la [depuración local para CloudScript con Azure Functions.](/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/local-debugging-for-cloudscript-using-azure-functions)
### Registro
Una de las herramientas más importantes para depurar código es el *registro*. Nuestro CloudScript proporciona una utilidad para realizar esta función.
Esta adopta la forma del objeto `log`, que puede registrar cualquier mensaje deseado mediante los métodos `Info`, `Debug` y `Error`.
Además, el objeto HTTP registrará cualquier error que encuentre al realizar solicitudes si se establece el parámetro `logRequestAndResponse`. Aunque configurar estos registros es sencillo, acceder a ellos requiere *un poco* de destreza.
Este es un ejemplo de una función de CloudScript que usa los 4 tipos de registros.
```javascript theme={null}
handlers.logTest = function(args, context) {
log.info("This is a log statement!");
log.debug("This is a debug statement.");
log.error("This is... an error statement?");
// the last parameter indicates we want logging on errors
http.request('https://httpbin.org/status/404', 'post', '', 'text/plain', null, true);
};
```
Para ejecutar este ejemplo, agregue esta función a su revisión activa antes de continuar.
Se puede llamar a la función `logTest` mediante `ExecuteCloudScript` como se muestra a continuación.
```csharp theme={null}
// Invoke this on start of your application
void Login() {
PlayFabClientAPI.LoginWithCustomID(new LoginWithCustomIDRequest {
CreateAccount = true,
CustomId = "Starter"
}, result => RunLogTest(), null);
}
void RunLogTest() {
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest {
FunctionName = "logTest",
// duplicates the response of the request to PlayStream
GeneratePlayStreamEvent = true
}, null, null);
}
// Logs evaluated in next code block
```
Establecer `GeneratePlayStreamEvent` hace que la llamada a la función de CloudScript genere un evento de PlayStream, que incluye el contenido de la respuesta. Para encontrar el contenido de un evento de PlayStream:
* Vaya a la página principal de **Game Manager** de su **título** o a su pestaña **PlayStream**.
* El **PlayStream Debugger** mostrará los eventos a medida que lleguen.
* Cuando lleguen, seleccione el pequeño icono azul de **información** en la esquina superior derecha del evento, como se muestra a continuación.
Al seleccionarlo, se mostrará el JSON sin procesar del evento, que se detalla para cada evento [aquí](/services/playfab/api-references/events). Puede ver un ejemplo de este JSON en el ejemplo siguiente.
* Si agregamos el MonoBehavior `LogScript` a la escena, ejecutar el juego producirá esto en PlayStream.
El resultado de una llamada a `ExecuteCloudScript` incluye un campo llamado `Logs`, que es una lista de objetos de registro generados por la función de CloudScript.
Puede ver las tres llamadas de registro, así como el registro de la solicitud HTTP no válida. El registro de la solicitud HTTP también hace uso del campo `Data`, a diferencia de las llamadas de registro.
Este campo es un objeto de JavaScript que se puede rellenar con cualquier información relevante para la instrucción de registro. Las llamadas a log también pueden hacer uso de este campo, mediante el segundo parámetro, como se indica a continuación.
```javascript theme={null}
handlers.logTest = function(args, context) {
log.info("This is a log statement!", { what: "Here on business." });
log.debug("This is a debug statement.", { who: "I am a doctor, sir" });
log.error("This is... an error statement?", { why: "I'm here to fix the plumbing. Probably.", errCode: 123 });
};
```
Todas estas llamadas rellenarán el campo `Data` del resultado con su segundo parámetro.
Dado que los registros se incluyen en el resultado, el código del lado cliente puede responder a las instrucciones de registro. El error de la función `logTest` es forzado, pero el código de cliente se puede adaptar para responder a él.
```csharp theme={null}
void RunLogTest()
{
PlayFabClientAPI.ExecuteCloudScript(
new ExecuteCloudScriptRequest
{
FunctionName = "logTest",
// handy for logs because the response will be duplicated on PlayStream
GeneratePlayStreamEvent = true
},
result =>
{
var error123Present = false;
foreach (var log in result.Logs)
{
if (log.Level != "Error") continue;
var errData = (JsonObject) log.Data;
object errCode;
var errCodePresent = errData.TryGetValue("errCode", out errCode);
if (errCodePresent && (ulong) errCode == 123) error123Present = true;
}
if (error123Present)
Debug.Log("There was a bad, bad error!");
else
Debug.Log("Nice weather we're having.");
}, null);
}
```
Si se ejecuta este código, la salida debería indicar la presencia del error. Las respuestas realistas a los errores podrían ser mostrar el error en la interfaz de usuario o guardar un valor en un archivo de registro.
## Avanzado: errores
En el desarrollo, los errores de CloudScript a menudo no se desencadenarán manualmente, como en el caso de `log.error`.
Afortunadamente, la respuesta a [ExecuteCloudScript](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript) contiene un [ExecuteCloudScriptResult](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptresult) que incluye un campo [ScriptExecutionError](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#scriptexecutionerror). Adaptando el último ejemplo de la sección de registro, podríamos usarlo como se muestra a continuación.
```csharp theme={null}
void RunLogTest() {
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest {
FunctionName = "logTest",
// handy for logs because the response will be duplicated on PlayStream
GeneratePlayStreamEvent = true
}, result => {
if(result.Error != null) {
Debug.Log(string.Format("There was error in the CloudScript function {0}:\n Error Code: {1}\n Message: {2}"
, result.FunctionName, result.Error.Error, result.Error.Message));
}
},
null);
}
```
En caso de que se produjera algún error, este código lo mostraría en el registro.
## Related topics
- [Inicio rápido de CloudScript](/es/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart.md)
- [Características de ES6 en CloudScript](/es/services/playfab/live-service-management/service-gateway/automation/cloudscript/es6-features-in-cloudscript.md)
- [Control de errores en CloudScript](/es/services/playfab/live-service-management/service-gateway/automation/cloudscript/handling-errors-in-cloudscript.md)
- [CloudScript de PlayFab con Azure Functions](/es/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/index.md)
- [Realizar llamadas de webhook desde CloudScript](/es/services/playfab/live-service-management/service-gateway/automation/cloudscript/making-webhook-calls-from-cloudscript.md)