> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Arquivos e código de actors

> Referência completa da classe Actor, seus handlers, conexões, armazenamento e timers

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Você está vendo a documentação para desenvolvedores
    </div>

    <div className="dev-docs-banner-text">
      Esta documentação é para desenvolvedores que trabalham com a plataforma para desenvolvedores
      Base44.
    </div>
  </div>
</div>

Referência completa da classe `Actor` que é executada no backend do seu app. Para o SDK do cliente que se conecta a uma sessão, veja a [referência do SDK de `actors`](/pt-BR/developers/references/sdk/docs/type-aliases/actors).

Para conceitos e terminologia de actors, veja a [visão geral de actors](/pt-BR/developers/backend/resources/actors/overview).

## Handlers obrigatórios

A classe `Actor` é abstrata. Implemente o corpo de cada um dos handlers a seguir. Os handlers respondem a eventos de clientes e timers.

| Handler | Eventos |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | Um cliente se conecta. |
| [`handleMessage()`](#lifecycle-handlers) | Um cliente conectado envia uma mensagem. |
| [`handleClose()`](#lifecycle-handlers) | Um cliente se desconecta. |
| [`handleTick()`](#timer-handlers-and-settings) | A cada intervalo de tick, enquanto os ticks estão ativos. |

## Handlers opcionais

Quando seu actor precisar deles, implemente estes handlers.

| Handler | Eventos |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | A sessão inicia, antes que a Base44 processe uma conexão. |
| [`shouldTick()`](#timer-handlers-and-settings) | Após cada conexão, mensagem, desconexão e tick. |
| [`handleWake()`](#timer-handlers-and-settings) | Chega um horário definido com `schedule()`. |

Quando a sessão usa ticks, defina [`tickIntervalMs`](#timer-handlers-and-settings). Se você omitir `shouldTick()`, a sessão nunca executa ticks.

## Métodos para chamar

A classe do actor oferece funcionalidades integradas. Os métodos a seguir podem ser usados ao implementar os handlers de um actor.

| Método | Finalidade |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Agenda um wake em um horário que você escolhe. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Remove um wake agendado. |
| [`conn.send()`](#connections) | Responde a um cliente. |
| [`conn.reject()`](#connections) | Recusa um cliente que está se conectando. |
| [`broadcast()`](#connections) | Alcança todos os clientes da sessão. |
| [`getConnections()`](#connections) | Lista os clientes conectados. |
| [`this.storage.get()`](#storage) | Lê um valor salvo da sessão. |
| [`this.storage.put()`](#storage) | Salva um valor da sessão. |
| [`this.storage.delete()`](#storage) | Remove um valor salvo. |
| [`this.storage.deleteAll()`](#storage) | Limpa o armazenamento da sessão. |
| [`secrets.get()`](#read-secrets) | Lê um secret do app. |

Use [`this.client`](#entity-access) para ler e gravar [entidades](/pt-BR/developers/backend/resources/entities/overview).

## Declaração da classe

Importe `Actor` de `base44:runtime/actors` e exporte uma classe que estende `Actor` como exportação padrão de `base44/actors/<actor-name>/entry.ts`.
O nome da pasta se torna o nome do actor no SDK. Para detalhes de configuração, veja [criar um actor](/pt-BR/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Tipa as mensagens que o actor recebe dos clientes conectados. Aplica-se ao
  parâmetro `msg` de `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Tipa as mensagens que o actor envia para os clientes conectados. Aplica-se a
  `conn.send()` e `broadcast()`.
</ResponseField>

## API de runtime

Os actors importam a classe `Actor` do módulo `base44:runtime/actors`:

```typescript theme={null}
import { Actor } from "base44:runtime/actors";
```

### Ler secrets

Use `secrets.get()` para ler as variáveis de ambiente do seu app a partir de um handler. O método retorna o valor como string, ou `undefined` quando o secret não está definido.

Importe `secrets` do módulo `base44:runtime`:

```typescript theme={null}
import { secrets } from "base44:runtime";
```

Configure secrets pela CLI com [`secrets set`](/pt-BR/developers/references/cli/commands/secrets-set).

Recomendamos chamar uma [função de backend](/pt-BR/developers/backend/resources/backend-functions/overview) para trabalhos que precisam de um secret. A função lê o secret e retorna o resultado, então o actor nunca recebe o secret. Para um fluxo de exemplo, veja [chamar uma função de backend para trabalhos com secrets](/pt-BR/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Handlers de ciclo de vida

A Base44 chama esses handlers em resposta à atividade dos clientes na sessão.
Você implementa o corpo de cada um.
Saiba mais sobre [como actors e clientes interagem](/pt-BR/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
Para um fluxo de exemplo, veja [gerenciar conexões de clientes](/pt-BR/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  É executado sempre que uma sessão é ativada, por exemplo:

  * Quando a sessão é criada pela primeira vez.
  * Quando um cliente se conecta a uma sessão inativa.
  * Quando uma mensagem chega em uma sessão inativa.
  * Quando chega um horário agendado.

  Retorna `void` ou uma `Promise<void>`.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  É executado quando um cliente se conecta à sessão.
  Você pode enviar o estado atual da sessão com `conn.send()` ou recusar a conexão com `conn.reject()`.
  Retorna `void` ou uma `Promise<void>`.

  <Expandable title="Parâmetros">
    <ResponseField name="conn" type="Conn" required>
      Representa o cliente que se conectou.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  É executado quando um cliente conectado envia uma mensagem.
  Você pode validar a mensagem antes de alterar o estado da sessão ou acessar os dados do app.
  Retorna `void` ou uma `Promise<void>`.

  <Expandable title="Parâmetros">
    <ResponseField name="conn" type="Conn" required>
      Representa o cliente que enviou a mensagem.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Contém a mensagem enviada pelo cliente. O genérico `Incoming` define
      o tipo da mensagem.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  É executado quando um cliente se desconecta.
  Use este handler para remover qualquer estado da sessão associado ao ID da conexão.
  Uma reconexão que reutiliza o mesmo ID substitui o socket antigo sem executar `handleClose()`.
  Retorna `void` ou uma `Promise<void>`.

  <Expandable title="Parâmetros">
    <ResponseField name="conn" type="Conn" required>
      Representa o cliente que se desconectou.
    </ResponseField>
  </Expandable>
</ResponseField>

## Handlers e configurações de timers

Esses handlers e configurações controlam o trabalho temporizado na sessão.
A Base44 os chama quando chega um horário agendado, não em resposta à atividade dos clientes.
Saiba mais sobre [trabalho agendado](/pt-BR/developers/backend/resources/actors/overview#scheduled-work).
Para fluxos de exemplo, veja [executar ticks](/pt-BR/developers/backend/resources/actors/sample-flows#run-ticks) e [agendar wakes](/pt-BR/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  É executado uma vez por intervalo enquanto `shouldTick()` retorna `true` e a sessão tem pelo menos um cliente.
  Retorna `void` ou uma `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Especifica o intervalo entre ticks em milissegundos. O padrão é `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Retorna um `boolean`. Retorne `true` para manter os ticks da sessão, ou `false` para interrompê-los. Este método é síncrono.

  Mantenha este método rápido e sem efeitos colaterais. A Base44 chama este método após cada conexão, mensagem, desconexão e tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  É executado uma vez quando chega um horário definido com `schedule()`.
  Retorna `void` ou uma `Promise<void>`.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Contém a chave passada para `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Agenda uma execução de `handleWake()` em um horário especificado.
  Retorna uma `Promise` que é concluída depois que a Base44 armazena o agendamento.
  O agendamento sobrevive a um período de inatividade e pode iniciar uma sessão inativa.
  Chamar este método novamente com a mesma chave substitui o horário agendado.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Identifica o wake agendado. É passada para `handleWake()` quando o wake é disparado.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Especifica quando `handleWake()` é executado. Use um objeto `Date` ou milissegundos
      desde 1º de janeiro de 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Cancela o wake agendado associado a uma chave.
  Retorna uma `Promise` que é concluída depois que a Base44 remove o agendamento.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Especifica a chave passada para `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Conexões

Estas propriedades e métodos estão disponíveis no objeto `conn` passado para os handlers de ciclo de vida que envolvem um cliente.
Use estas propriedades e métodos para ler a identidade do cliente, enviar mensagens e gerenciar a conexão.
Para uma visão geral das mensagens, veja [mensagens em tempo real](/pt-BR/developers/backend/resources/actors/overview#realtime-messages).
Para um fluxo de exemplo, veja [gerenciar conexões de clientes](/pt-BR/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` é a ponta de backend do WebSocket, e `Connection` no cliente é a outra ponta do mesmo socket. Use `conn` na classe do actor. Veja a referência do SDK de `actors` para o objeto do cliente.
</Note>

<ResponseField name="conn.id" type="string">
  Identifica esta conexão. Corresponde ao ID que o cliente passou ao se conectar,
  ou a um ID gerado pelo SDK.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifica o cliente nesta conexão. Presente em todas as
  conexões.

  <Expandable title="Propriedades">
    <ResponseField name="type" type="string" required>
      Contém `authenticated` ou `anonymous`.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Identifica o cliente logado. Presente quando `type` é
      `authenticated`.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifica o cliente anônimo. Presente quando `type` é `anonymous`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Envia uma mensagem para esta conexão. Retorna `void`.

  <Expandable title="Parâmetros">
    <ResponseField name="data" type="Outgoing" required>
      Contém a mensagem a ser enviada para esta conexão. O genérico `Outgoing` define o tipo da mensagem.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Recusa uma conexão a partir de `handleConnect()`. Retorna `void`.

  <Expandable title="Parâmetros">
    <ResponseField name="code" type="number" required>
      Especifica o código de status enviado ao cliente.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Descreve por que o actor recusou a conexão.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Envia uma mensagem para todas as conexões ativas na sessão. Retorna `void`.

  <Expandable title="Parâmetros">
    <ResponseField name="data" type="Outgoing" required>
      Contém a mensagem a ser enviada para todas as conexões da sessão. O genérico `Outgoing` define o tipo da mensagem.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Retorna um array dos objetos `conn` ativos na sessão. Use este método em
  `handleStart()` para associar os dados restaurados aos clientes que permaneceram conectados
  durante um período de inatividade.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Propriedade no nível da sessão. Contém o ID de sessão que o cliente usou para acessar
  esta sessão.
</ResponseField>

## Armazenamento

Use `this.storage` para ler e gravar dados da sessão. Diferentemente dos campos da classe, o armazenamento sobrevive aos períodos de inatividade. Para escolher entre armazenamento e campos da classe, veja [armazenamento](/pt-BR/developers/backend/resources/actors/overview#storage). Para um fluxo de exemplo, veja [persistir dados da sessão](/pt-BR/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Recupera um valor pela chave. Retorna uma `Promise` que resolve para o valor
  armazenado, ou `undefined` quando a chave não existe.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Especifica a chave a ser recuperada.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Salva um valor pela chave. Substitui o valor já armazenado sob a chave. Retorna
  uma `Promise` que é concluída quando a gravação termina.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Especifica a chave a ser salva.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Especifica o valor compatível com JSON a ser salvo.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Remove um valor pela chave. Retorna uma `Promise` que resolve para `true` quando a
  chave existia, e `false` caso contrário.

  <Expandable title="Parâmetros">
    <ResponseField name="key" type="string" required>
      Especifica a chave a ser removida.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Remove todos os dados salvos da sessão. Retorna uma `Promise` que é concluída quando
  o armazenamento estiver vazio. Uma conexão posterior começa com o mesmo armazenamento vazio de uma
  nova sessão.
</ResponseField>

## Acesso a entidades

Use `this.client` e `this.client.asServiceRole` para ler e gravar entidades do app dentro de um handler do actor. Para um fluxo de exemplo, veja [gravar dados de entidades a partir de uma sessão](/pt-BR/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Fornece um cliente do app com escopo para esta sessão. Este cliente usa autenticação
  anônima, então o acesso às entidades segue as mesmas regras de um cliente
  não logado, e ele lê dados de produção.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Fornece acesso elevado que ignora a segurança em nível de linha. Valide as mensagens
  antes de usar este cliente. Torne as gravações seguras para repetição, porque a sessão pode executar um handler
  novamente após um erro.
</ResponseField>

## Veja também

* [Visão geral de actors](/pt-BR/developers/backend/resources/actors/overview): Conceitos e terminologia
* [Actors: fluxos de exemplo](/pt-BR/developers/backend/resources/actors/sample-flows): Ciclo de vida, timers, conexões, armazenamento, entidades e funções de backend
* [Referência do SDK de `actors`](/pt-BR/developers/references/sdk/docs/type-aliases/actors): API do SDK do cliente
* [`secrets set`](/pt-BR/developers/references/cli/commands/secrets-set): Configure variáveis de ambiente pela CLI

<Note>Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a [versão em inglês](/). </Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.