> ## 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.
# Escrever CloudScript personalizado
> Escreva funções JavaScript personalizadas do CloudScript do PlayFab que podem ser chamadas por clientes Unity, regras do PlayStream e tarefas agendadas, com exemplos de helloWorld.
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](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart) 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](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) 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:
* [Ambiente do **Unity** configurado com o **Unity SDK** do PlayFab](/pt-BR/services/playfab/sdks/unity3d/quickstart)
* A ID do título está definida no objeto `PlayFabSharedSettings`.
* O projeto consegue fazer login de um usuário com êxito.
## 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).
```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 };
}
```
### 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.
```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
```
### Desconstruir o código
[ExecuteCloudScriptRequest](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptrequest) é o tipo de solicitação para qualquer chamada a [PlayFabClientAPI.ExecuteCloudScript](xref:titleid.playfabapi.com.client.server-sidecloudscript.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.
```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());
}
```
## 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](/pt-BR/services/playfab/api-references), 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.
| Nome | Uso |
| :- | :- |
| **server** | Tem acesso a todas as chamadas de API do lado do servidor listadas na [documentação de referência da API do PlayFab](/pt-BR/services/playfab/api-references). Elas podem ser chamadas (de forma síncrona) assim: `var result = server.AuthenticateUserTicket(request);` |
| **http** | Executa solicitações HTTP síncronas, assim: `http.request(url, method, content, contentType, headers, logRequestAndResponse)`. O objeto `headers` contém propriedades correspondentes a vários cabeçalhos e seus valores. `logRequestAndResponse` é um booliano que determina se o título deve registrar quaisquer erros da solicitação como parte da resposta. |
| **log** | Cria instruções de log e as adiciona à resposta. Os logs têm três níveis: `log.info()`, `log.debug()` e `log.error()`. Os três níveis aceitam uma cadeia de caracteres de mensagem, junto com um objeto opcional contendo dados extras a serem incluídos no log. Por exemplo, `log.info('hello!', { time: new Date() });` |
| **currentPlayerId** | A ID do PlayFab do jogador que disparou a chamada do CloudScript. |
| **handlers** | Objeto global que contém todas as funções do CloudScript do seu título. As funções podem ser adicionadas ou chamadas por meio desse objeto. Por exemplo, `handlers.pop = function() {};`, `handlers.pop();`. |
| **script** | Objeto global que contém `Revision` e `titleId`. `Revision` representa o **número da revisão** do CloudScript em execução no momento, e `titleId` representa a ID do título atual. |
Além disso, todas as funções de manipulador recebem dois parâmetros, detalhados abaixo.
| Nome | Uso |
| :- | :- |
| **args** | Primeiro parâmetro de uma função de manipulador. Uma representação de objeto do campo `FunctionParameter` de uma solicitação `ExecuteCloudscript`. |
| **context** | Segundo parâmetro de uma função de manipulador. Informações adicionais sobre a solicitação quando ela é disparada por uma ação de evento do PlayStream, incluindo os [dados do evento](/pt-BR/services/playfab/api-references/events) que disparou a ação (context.playStreamEvent) e os [dados de perfil](xref:titleid.playfabapi.com.client.accountmanagement.getplayerprofile#playerprofilemodel) do jogador associado a ele. (context.playerProfile) |
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](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#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](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) 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.
```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());
}
```
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](/pt-BR/services/playfab/api-references) 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.
```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);
}
```
## 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.
2. 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**.
3. 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](#advanced-debugging-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](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af). Saiba mais sobre como usar a [depuração local do CloudScript usando Azure Functions.](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/local-debugging-for-cloudscript-using-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.
```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 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.
```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
```
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.
Selecionar isso exibirá o JSON bruto do evento, que está detalhado para cada evento [aqui](/pt-BR/services/playfab/api-references/events). Um exemplo desse JSON pode ser visto a seguir.
* Se adicionarmos o MonoBehavior `LogScript` à cena, a execução do jogo produzirá isto no PlayStream.
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.
```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 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.
```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);
}
```
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](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript) contém um [ExecuteCloudScriptResult](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptresult) que inclui um campo [ScriptExecutionError](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#scriptexecutionerror). Adaptando o último exemplo da seção de registro em log, poderíamos usá-lo conforme mostrado abaixo.
```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);
}
```
Caso ocorra algum erro, esse código o exibirá no log.
## Related topics
- [Início rápido do CloudScript](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart.md)
- [Documentação do gerenciamento de serviços ao vivo do PlayFab](/pt-BR/services/playfab/live-service-management/index.md)
- [Recursos do ES6 no CloudScript](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript/es6-features-in-cloudscript.md)
- [CloudScript do PlayFab usando Azure Functions](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/index.md)
- [Guia de início rápido do CloudScript do PlayFab usando Azure Functions](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart.md)