Pular para o conteúdo principal
O CloudScript é um dos recursos mais versáteis do PlayFab. Ele permite que o código do cliente solicite a execução de qualquer tipo de funcionalidade personalizada do lado do servidor que você possa implementar e pode ser usado com praticamente qualquer coisa. Além das solicitações de execução explícitas do código do cliente ou do servidor, o CloudScript pode ser executado em resposta a eventos do PlayStream (criando uma regra) ou como parte de uma tarefa agendada.
O CloudScript usando Azure Functions aprimora o que tornou o CloudScript excelente, com mais linguagens compatíveis e melhores fluxos de trabalho de depuração.
Este tutorial aborda a escrita do código do CloudScript. Consulte o Início rápido do CloudScript para obter ajuda com o upload dos seus arquivos do CloudScript para o título.
Este tutorial demonstra exemplos de código do Unity, mas o CloudScript funciona de forma semelhante em todos os SDKs.
Pré-requisitos deste tutorial:

Introdução: helloWorld

Nosso exemplo helloWorld funciona em um título totalmente novo, sem modificações no Game Manager. O arquivo do CloudScript padrão de um novo título inclui um manipulador chamado helloWorld. Ele utiliza alguns recursos básicos: parâmetros de entrada, registro em log, currentPlayerId e parâmetros de retorno. O exemplo a seguir mostra o código da função helloWorld padrão (sem os comentários).

Desconstruir o código

O objeto handler é predefinido no ambiente do CloudScript do PlayFab. Você deve adicionar todas as suas funções do CloudScript a esse objeto.
  • helloWorld é uma função disponibilizada para seu título e seus SDKs, pois está definida no objeto handler.
  • args é um objeto arbitrário que vem do chamador. Ele é analisado a partir de JSON e pode conter quaisquer dados formatados de qualquer forma.
Consulte FunctionParameter na próxima seção.
Você deve tratar esse objeto com confiança zero. Um cliente hackeado ou um usuário mal-intencionado pode fornecer qualquer informação aqui em qualquer formato.
  • Context é um parâmetro avançado. Neste exemplo, ele é null. Esse parâmetro é controlado pelo servidor e seguro.
  • currentPlayerId é uma variável global, definida como o PlayFabId do jogador que está solicitando essa chamada. Esse parâmetro é controlado pelo servidor e seguro. Observação: ao usar a API ExecuteEntityCloudScript, esse parâmetro é nulo, a menos que a entidade tenha um MasterPlayerID em sua cadeia de entidades.
  • log.info: log é um objeto global. Ele é usado principalmente para depurar seu CloudScript. O objeto log expõe os seguintes métodos: info, debug e error. Há mais detalhes mais adiante neste tutorial.
  • return: qualquer objeto que você retornar será serializado como JSON e retornado ao chamador. Você pode retornar qualquer objeto serializável em JSON com os dados que desejar.
Você é responsável caso seu CloudScript retorne dados secretos aos seus clientes. Um cliente hackeado ou um usuário mal-intencionado pode examinar os dados retornados, mesmo que você não os exiba ao usuário durante o jogo normal.

Executar funções do CloudScript a partir de um cliente de jogo do Unity

Chamar uma função do CloudScript a partir de um cliente é simples. Primeiro, você precisa criar uma ExecuteCloudScriptRequest e definir a propriedade ActionId como o nome da função do CloudScript que deseja executar (neste caso, seria helloWorld) e, em seguida, enviar o objeto ao PlayFab por meio da nossa API.
Você só pode chamar métodos do CloudScript anexados ao objeto JavaScript handlers.
Para executar métodos do CloudScript, você precisará das seguintes linhas de código no cliente.

Desconstruir o código

ExecuteCloudScriptRequest é o tipo de solicitação para qualquer chamada a PlayFabClientAPI.ExecuteCloudScript.
  • ExecuteCloudScriptRequest.FunctionName é uma cadeia de caracteres. O valor deve corresponder ao nome da função definida no CloudScript. Neste caso, helloWorld.
  • ExecuteCloudScriptRequest.FunctionParameter pode ser qualquer objeto serializável em JSON. Ele se torna o primeiro parâmetro args na função helloWorld (consulte args na seção anterior).
  • ExecuteCloudScriptRequest.GeneratePlayStreamEvent é opcional. Se for true, um evento será publicado no PlayStream, que você poderá exibir no Game Manager ou utilizar para outros gatilhos do PlayStream.
Dependendo da linguagem, a parte final da linha ExecuteCloudScript envolve fazer a solicitação ao servidor do CloudScript do PlayFab e a parte de tratamento de Result e Error, específica da linguagem. Por exemplo, no Unity, JavaScript ou AS3, o tratamento de Error e Result é fornecido por meio de funções de retorno de chamada. Veja a seguir um exemplo de métodos de tratamento de erros.

Visão geral intermediária: globais e argumentos avançados

O CloudScript é um conjunto de funções JavaScript compiladas com o V8 e hospedadas nos servidores do PlayFab. Ele tem acesso a qualquer API de servidor listada na documentação de referência da API do PlayFab, além de um logger, da ID do PlayFab do jogador que está fazendo a solicitação do CloudScript e de quaisquer informações incluídas na solicitação, tudo na forma de objetos predefinidos. As próprias funções do CloudScript são propriedades de um objeto handlers global. A tabela a seguir mostra uma lista completa dessas variáveis predefinidas. Além disso, todas as funções de manipulador recebem dois parâmetros, detalhados abaixo. As funções do CloudScript podem ser chamadas por meio da API ExecuteCloudScript ou por uma ação de evento do PlayStream predefinida. Os detalhes completos sobre a resposta a ExecuteCloudScript podem ser encontrados em ExecuteCloudScriptResult.

Intermediário: FunctionParameter e args

Na seção anterior, descrevemos como preencher request.FunctionParameter e exibir essas informações no parâmetro args. O Início rápido do CloudScript demonstra como fazer upload de um novo CloudScript. Juntando as duas coisas, podemos fornecer outro exemplo de como passar argumentos do cliente para o CloudScript. Pegue o exemplo anterior e modifique o código do CloudScript e o código do cliente conforme mostrado abaixo.
Depois de fazer essas alterações, você poderá enviar e receber dados facilmente entre o CloudScript e seus clientes.
É importante ressaltar que quaisquer dados vindos dos seus clientes estão sujeitos a hacking e exploração.
Você sempre deverá validar os parâmetros de entrada antes de atualizar seu back-end. O processo de validação dos parâmetros de entrada varia de título para título, mas a validação mais básica verifica se as entradas estão dentro de intervalos e períodos aceitáveis.

Intermediário: chamar as APIs de servidor

Conforme mencionado antes, nos métodos do CloudScript, você tem acesso ao conjunto completo de chamadas da Server API. Isso permite que seu código de nuvem funcione como um servidor dedicado. Tarefas comuns de servidor:
  • Atualizar estatísticas e dados do jogador.
  • Conceder itens e moeda.
  • Gerar dados de jogo aleatoriamente.
  • Calcular com segurança os resultados de batalhas e muito mais…
Consulte as Server APIs listadas na nossa documentação de referência da API do PlayFab para ver os parâmetros obrigatórios e as estruturas de objeto. O exemplo a seguir é de dentro de um possível manipulador do CloudScript.

Avançado: ação de evento do PlayStream

Uma função do CloudScript pode ser configurada para ser executada em resposta a um evento do PlayStream.
  1. Em qualquer navegador:
    • Visite o PlayFab Game Manager.
    • Localize seu Title.
    • Em Build, na barra lateral, acesse a guia Automation.
    • Acesse a guia Rules.
A página terá uma aparência semelhante ao exemplo fornecido abaixo. Game Manager: PlayStream: ações de evento
  1. Use o botão New Rule para criar uma nova regra.
    • Dê um nome à nova Rule.
    • Selecione um Event type que será usado como gatilho para uma condição ou ação.
    • Para fazer a Rule disparar uma função do CloudScript, adicione uma Action com o botão dessa seção.
    • Em seguida, selecione a opção no menu suspenso Type.
    • Selecione a função helloWorld no menu suspenso Cloud Script Function.
    • Selecione o botão Save action.
    Game Manager: PlayStream: salvar ação
  2. Essa Rule agora está definida para ser disparada em qualquer evento do tipo selecionado. Para testá-la:
    • Marque a caixa Publish results as PlayStream Event.
    • Salve a Action.
    • Em seguida, dispare um evento.
    • No PlayStream Monitor, deverá aparecer um novo evento correspondente à execução do CloudScript, contendo as informações apropriadas.
    • Para obter mais informações sobre como verificar um evento do PlayStream no depurador, consulte a seção a seguir Avançado: depurar o CloudScript.
As ações de evento só podem usar a revisão ativa ao chamar funções do CloudScript. Se você não conseguir encontrar a função helloWorld na lista suspensa, esse é o motivo mais provável.

Avançado: depurar o CloudScript

A depuração é muito mais fácil com o CloudScript usando Azure Functions. Saiba mais sobre como usar a depuração local do CloudScript usando Azure Functions.

Registro em log

Uma das ferramentas mais importantes para depurar código é o registro em log. Nosso CloudScript fornece um utilitário para executar essa função. Ele assume a forma do objeto log, que pode registrar qualquer mensagem desejada usando os métodos Info, Debug e Error. Além disso, o objeto HTTP registrará quaisquer erros encontrados ao fazer solicitações, definindo o parâmetro logRequestAndResponse. Embora configurar esses logs seja simples, acessá-los exige um pouco de habilidade. Veja um exemplo de uma função do CloudScript que usa os 4 tipos de log.
Para executar este exemplo, adicione essa função à sua revisão ativa antes de continuar. A função logTest pode ser chamada usando ExecuteCloudScript, conforme mostrado abaixo.
Definir GeneratePlayStreamEvent faz com que a chamada da função do CloudScript gere um evento do PlayStream, que inclui o conteúdo da resposta. Para localizar o conteúdo de um evento do PlayStream:
  • Acesse a página inicial do Game Manager do seu Title ou a guia PlayStream dele.
  • O PlayStream Debugger exibirá os eventos à medida que chegarem.
  • Quando chegarem, selecione o pequeno ícone azul Info no canto superior direito do evento, conforme mostrado abaixo. Game Manager: PlayStream: depurador
Selecionar isso exibirá o JSON bruto do evento, que está detalhado para cada evento aqui. Um exemplo desse JSON pode ser visto a seguir.
  • Se adicionarmos o MonoBehavior LogScript à cena, a execução do jogo produzirá isto no PlayStream. Game Manager: PlayStream: log de eventos JSON
O resultado de uma chamada a ExecuteCloudScript inclui um campo chamado Logs, que é uma lista de objetos de log gerados pela função do CloudScript. Você pode ver as três chamadas de log, bem como o log da solicitação HTTP inválida. O log da solicitação HTTP também usa o campo Data, ao contrário das chamadas de log. Esse campo é um objeto JavaScript que pode ser preenchido com quaisquer informações relevantes para a instrução de log. As chamadas de log também podem usar esse campo, por meio do segundo parâmetro, conforme indicado abaixo.
Todas essas chamadas preencherão o campo Data no resultado com o segundo parâmetro. Como os logs estão incluídos no resultado, o código do lado do cliente pode responder às instruções de log. O erro na função logTest é forçado, mas o código do cliente pode ser adaptado para responder a ele.
Se esse código for executado, a saída deverá indicar a presença do erro. Respostas realistas ao erro podem ser exibi-lo na interface do usuário ou salvar um valor em um arquivo de log.

Avançado: erros

Durante o desenvolvimento, os erros do CloudScript muitas vezes não serão disparados manualmente, como no caso de log.error. Felizmente, a resposta a ExecuteCloudScript contém um ExecuteCloudScriptResult que inclui um campo ScriptExecutionError. Adaptando o último exemplo da seção de registro em log, poderíamos usá-lo conforme mostrado abaixo.
Caso ocorra algum erro, esse código o exibirá no log.
Última modificação em 8 de outubro de 2026