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

# Usando ações do CloudScript com o PlayStream

> Explica os dados de contexto disponíveis em um manipulador do CloudScript disparado por uma ação do PlayStream e como usá-los para conduzir a lógica de servidor do PlayFab.

Quando um manipulador do CloudScript é iniciado a partir de uma ação do PlayStream, esse manipulador tem acesso a mais dados sobre o motivo pelo qual está sendo executado (o *contexto*), que você pode usar para conduzir sua lógica do lado do servidor.

Este tutorial mostra tudo o que está disponível no contexto e como usá-lo nos seus manipuladores do CloudScript.

## Noções básicas do CloudScript

A chave para aproveitar ao máximo o CloudScript é saber como trabalhar com as entradas disponíveis, ou seja, os args e o contexto do seu manipulador.

Por exemplo, aqui está o exemplo `helloWorld` do CloudScript inicial, carregado como Revisão 1 em todos os títulos recém-criados (também disponível no nosso GitHub, [mostrado abaixo](https://github.com/PlayFab/CloudScriptSamples/tree/master/BasicSample)).

```javascript theme={null}
// This is a CloudScript function.
// "args" is set to the value of the "FunctionParameter" parameter of the ExecuteCloudScript API.
// "context" contains additional information when the CloudScript function is called from a PlayStream action.
handlers.helloWorld = function (args, context) {

    // The pre-defined "currentPlayerId" variable is initialized to the PlayFab ID of the player logged-in on the game client.
    // CloudScript handles authenticating the player automatically.
    var message = "Hello " + currentPlayerId + "!";

    // You can use the "log" object to write out debugging statements. It has
    // three functions corresponding to logging level: debug, info, and error. These functions
    // take a message string and an optional object.
    log.info(message);
    var inputValue = null;
    if (args != null && args != undefined)
    {
        inputValue = args.inputValue;
    }
    log.debug("helloWorld:", { input: inputValue });

    // The value you return from a CloudScript function is passed back
    // to the game client in the ExecuteCloudScript API response, along with any log statements
    // and additional diagnostic information, such as any errors returned by API calls or external HTTP
    // requests. They are also included in the optional player_executed_cloudscript PlayStream event
    // generated by the function execution.
    return { messageValue: message };
}
```

Este exemplo demonstra o caso de uso comum de chamar o CloudScript a partir de um cliente, por meio de [ExecuteCloudScript](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript). Ele verifica se há um argumento passado com a chave `inputValue` e usa o valor dessa chave como parte do texto retornado nas informações do log de depuração da execução.

## O parâmetro de entrada context

No entanto, também é possível chamar um CloudScript como resultado de um evento no PlayStream, por meio de uma Regra (**Automation**->**Rules**), uma Ação de Entrada/Saída de Segmento (**Players**->**Segments**) ou o Serviço de Tarefas (**Automation**->**Tasks**).

Quando você faz isso, o contexto passado para a função fornece todas as informações necessárias para executar a ação apropriada.

Para ler sobre os conceitos básicos de como os eventos do PlayStream funcionam, consulte o nosso blog [Introducing PlayStream](https://blog.playfab.com/blog/introducing-playstream/) e, para obter uma lista dos tipos de eventos do PlayStream e suas propriedades, consulte a nossa [Referência da API do PlayFab](/pt-BR/services/playfab/api-references).

Para ver essa ação, dê uma olhada no manipulador `handlePlayStreamEventAndProfile` do mesmo CloudScript de exemplo.

```javascript theme={null}
// This is a simple example of a function that is called from a
handlers.handlePlayStreamEventAndProfile = function (args, context) {

    // The event that triggered the action.
    // For a list of event types, see our PlayFab API documentation.
    var psEvent = context.playStreamEvent;

    // The profile data of the player associated with the event
    var profile = context.playerProfile;

    // Post data about the event to an external API
    var content = JSON.stringify({user: profile.PlayerId, event: psEvent.EventName});
    var response = http.request('https://httpbin.org/status/200', 'post', content, 'application/json', null, true);

    return { externalAPIResponse: response };
}
```

No caso de uma chamada do CloudScript disparada pelo PlayStream, o contexto contém 3 elementos que podem ser usados para conduzir a lógica do seu manipulador com autoridade do servidor.

1. Há o `playStreamEvent`, que você pode ver no código de exemplo acima. O `playStreamEvent` contém o evento completo que disparou o manipulador como um objeto JSON, com todos os parâmetros que você vê na [documentação de eventos do PlayStream](/pt-BR/services/playfab/api-references/events). Assim, por exemplo, se você configurar uma regra no seu título que chame `handlePlayStreamEventAndProfile` em qualquer `player_logged_in event`, `playStreamEvent.EventName` seria `player_logged_in` etc. ([aqui está o conjunto completo de parâmetros desse evento](/pt-BR/services/playfab/api-references/events/PlayerIdentity/player-logged-in)).

2. Em seguida, há o `playerProfile`, também mostrado no exemplo anterior. Ele contém informações sobre o jogador que disparou o evento. Você pode encontrar todos os detalhes dos parâmetros do perfil aqui, mas, entre outras coisas, ele contém o conjunto completo de estatísticas do jogador no seu título e quaisquer marcas personalizadas que você tenha atribuído ao jogador, para que você possa usar esses dados para uma tomada de decisão avançada.

3. O último elemento do contexto é `triggeredByTask`. Ao contrário dos dois primeiros, que são definidos ao usar Regras e gatilhos de Entrada/Saída de Segmento, `triggeredByTask` só é aplicável quando o manipulador está sendo executado como resultado de uma tarefa, seja manual ou por temporizador. Ele contém apenas dois parâmetros:

* **Name**: o nome exclusivo que você deu à tarefa quando a criou.

* **ID**: o identificador exclusivo gerado automaticamente pelo PlayFab para a tarefa.

Para uma tarefa executada em um segmento de usuários, você também terá o `playerProfile`, mas não terá um `playStreamEvent`.

E, para uma tarefa executada simplesmente no seu jogo, mas *sem* nenhum segmento, não haverá um `playerProfile`, pois a intenção é executar algo mais geral, como definir alguns dados de título para um evento.

Portanto, *name* é o elemento que você vai querer usar no fluxo de código do seu manipulador para determinar a ação apropriada a ser executada.

## PlayStream mais CloudScript

De muitas maneiras, os manipuladores do CloudScript disparados por ações do PlayStream têm ainda mais funcionalidade potencial do que aqueles disparados diretamente por meio de chamadas para `ExecuteCloudScript`, pois há um conjunto avançado de dados disponibilizado por meio do contexto.

Isso oferece a capacidade de atualizar seus manipuladores após o lançamento com *mais* lógica que usa elementos do evento ou do perfil do jogador que você não havia previsto originalmente, *sem* precisar atualizar o código do cliente de forma alguma.

Além disso, continuaremos fazendo acréscimos ao perfil do jogador em atualizações futuras do serviço PlayFab, o que fornecerá *ainda mais* opções para a lógica do lado do servidor.


## Related topics

- [Estatísticas com PlayStream e telemetria](/pt-BR/services/playfab/player-progression/statistics/statistics-with-playstream-and-telemetry.md)
- [Início rápido de Ações e Regras](/pt-BR/services/playfab/data-analytics/acting-data/action-rules-quickstart.md)
- [Configuração de segmentos de jogadores](/pt-BR/services/playfab/player-progression/player-data/player-segment-configuration.md)
- [Modelos de contexto do CloudScript do PlayFab usando Azure Functions](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/CloudScript-af-context.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)