Skip to main content
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 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 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:

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).

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.

Análisis del código

ExecuteCloudScriptRequest es el tipo de solicitud para cualquier llamada a PlayFabClientAPI.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.

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, 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. Además, todas las funciones de controlador reciben dos parámetros, que se detallan a continuación. 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.

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 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.
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 para conocer los parámetros necesarios y las estructuras de objetos. El siguiente ejemplo procede del interior de un posible controlador de CloudScript.

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. Game Manager - PlayStream - acciones de eventos
  1. 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.
    Game Manager - PlayStream - guardar acción
  2. 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.
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. Obtenga más información sobre cómo usar la depuración local para CloudScript con 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.
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.
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. Game Manager - PlayStream - depurador
Al seleccionarlo, se mostrará el JSON sin procesar del evento, que se detalla para cada evento aquí. 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. Game Manager - PlayStream - registro de eventos JSON
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.
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.
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 contiene un ExecuteCloudScriptResult que incluye un campo ScriptExecutionError. Adaptando el último ejemplo de la sección de registro, podríamos usarlo como se muestra a continuación.
En caso de que se produjera algún error, este código lo mostraría en el registro.
Última modificación el 28 de agosto de 2026