Actors: fluxos de exemplo

Use estes fluxos de exemplo como ponto de partida para sua implementação.

Conectar um cliente a uma sessão

Quando o frontend precisa entrar em uma sessão ao vivo, receber mensagens do actor e enviar mensagens para o actor, conecte um cliente a uma sessão de actor. Para conectar um cliente a uma sessão:

Chame base44.actors.ActorName(sessionId) para selecionar a sessão.
Chame .connect() para abrir a conexão WebSocket.
Chame conn.subscribe() para registrar um listener para as mensagens do actor.
Chame conn.send() para enviar uma mensagem para o actor.

O exemplo a seguir se conecta a uma sessão do actor chatRoom, escuta mensagens e envia uma mensagem:

const conn = base44.actors.chatRoom("lobby-1").connect();

conn.subscribe((msg) => {
  if (msg.type === "message") console.log(msg.text);
});

conn.send({ type: "message", text: "Hello" });

Para saber mais sobre conexões, veja conexões.

Executar ticks

Quando um trabalho precisa se repetir em um intervalo enquanto há clientes na sessão, execute ticks. Exemplos incluem transmitir o estado do jogo ou atualizar um timer de rodada. Para executar ticks:

Defina tickIntervalMs com a duração do intervalo em milissegundos.
Implemente shouldTick() para retornar true para continuar os ticks e false para pará-los.
Em handleTick(), execute o trabalho de cada intervalo.

O exemplo a seguir executa um tick a cada segundo enquanto há pelo menos dois clientes na sessão, transmitindo uma contagem regressiva a cada tick:

export default class Game extends Actor<Incoming, Outgoing> {
  tickIntervalMs = 1000;
  countdown = 60;

  shouldTick() {
    return this.getConnections().length >= 2;
  }

  async handleTick() {
    this.countdown--;
    this.broadcast({ type: "tick", countdown: this.countdown });
  }
}

Para saber mais sobre ticks, veja handlers e configurações de timers.

Agendar wakes

Quando um trabalho precisa ser executado uma vez em um horário específico, esteja a sessão ativa ou inativa, agende um wake. Exemplos incluem encerrar uma vez após 30 segundos ou fechar um lobby vazio. Para agendar um wake:

Chame schedule() com uma chave e um horário para agendar o wake.
Em handleWake(), verifique a chave e execute o trabalho desse wake.
Quando o wake não for mais necessário, chame cancelSchedule() com a chave.

O exemplo a seguir agenda um tempo limite quando uma vez começa e transmite uma mensagem quando o tempo limite é disparado:

export default class Game extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    if (msg.type === "start-turn") {
      await this.schedule("turn-timeout", Date.now() + 30_000);
    }
    if (msg.type === "end-turn") {
      await this.cancelSchedule("turn-timeout");
    }
  }

  async handleWake(key: string) {
    if (key === "turn-timeout") {
      this.broadcast({ type: "timeout" });
    }
  }
}

Para saber mais sobre wakes, veja handlers e configurações de timers.

Gerenciar conexões de clientes

Quando você precisa decidir quem pode entrar em uma sessão, responder a um cliente específico e alcançar todos os clientes da sessão, gerencie as conexões de clientes. Para gerenciar conexões de clientes:

Em handleConnect(), verifique conn.identity e chame conn.reject() para recusar um cliente.
Chame conn.send() para responder apenas a esse cliente.
Em handleMessage(), chame broadcast() para alcançar todos os clientes conectados. Para identificar o remetente, inclua campos de conn na mensagem.

O exemplo a seguir rejeita clientes anônimos, envia o histórico para o cliente que está se conectando e transmite mensagens com o ID de usuário do remetente:

async handleConnect(conn) {
  if (conn.identity.type === "anonymous") {
    conn.reject(401, "Login required");
    return;
  }
  conn.send({ type: "history", messages: this.messages });
}

async handleMessage(conn, msg) {
  this.broadcast({ type: "message", from: conn.identity.userId, text: msg.text });
}

Para saber mais sobre conexões, veja conexões.

Persistir dados da sessão

Quando os valores precisam sobreviver a um período de inatividade, persista os dados da sessão. Exemplos incluem um tabuleiro, uma lista de histórico ou a vez atual. Para persistir dados da sessão:

Em handleStart(), carregue os valores de this.storage para os campos da classe.
Após cada mudança, chame this.storage.put() para salvar o valor atualizado.
Para redefinir a sessão, chame this.storage.delete() ou this.storage.deleteAll().

O exemplo a seguir carrega um tabuleiro ao iniciar, salva-o após cada jogada e limpa o armazenamento quando o último cliente se desconecta:

async handleStart() {
  this.board = (await this.storage.get<Board>("board")) ?? newBoard();
}

async handleMessage(_conn, msg) {
  applyMove(this.board, msg.move);
  await this.storage.put("board", this.board);
}

async handleClose(_conn) {
  if (this.getConnections().length === 0) {
    await this.storage.deleteAll();
  }
}

Para saber mais sobre armazenamento, veja armazenamento.

Gravar dados de entidades a partir de uma sessão

Quando a sessão precisa criar ou atualizar registros do app, grave dados de entidades. Exemplos incluem uma pontuação final ou um pedido concluído. Para gravar dados de entidades a partir de uma sessão:

Valide a mensagem recebida antes de gravar.
Leia o ID do usuário em conn.identity.userId.
Use this.client.asServiceRole para acesso elevado. Grave com uma chave estável, como o ID da sessão, para que um handler repetido atualize o mesmo registro.

O exemplo a seguir salva uma pontuação final para o cliente autenticado. Um salvamento posterior para a mesma sessão atualiza esse registro:

async handleMessage(conn, msg) {
  if (msg.type !== "save-score" || conn.identity.type !== "authenticated") return;
  if (typeof msg.score !== "number") return;

  const fields = {
    sessionId: this.instanceId,
    userId: conn.identity.userId,
    score: msg.score,
  };
  const [existing] = await this.client.asServiceRole.entities.Score.filter({
    sessionId: this.instanceId,
  });

  if (existing) {
    await this.client.asServiceRole.entities.Score.update(existing.id, fields);
  } else {
    await this.client.asServiceRole.entities.Score.create(fields);
  }
}

Para saber mais sobre acesso a entidades, veja acesso a entidades.

Chamar uma função de backend para trabalhos com secrets

Os actors podem ler secrets do app com secrets.get(). Quando um handler precisa de um trabalho que usa um secret, como chamar uma API externa com uma chave de API, recomendamos chamar uma função de backend. A função lê o secret e retorna o resultado, nunca o secret. Para chamar uma função de backend a partir de um actor:

Crie uma função de backend que leia o secret com secrets.get(), faça o trabalho e retorne o resultado.
Em um handler, chame this.client.functions.invoke() com o nome da função e os dados a serem enviados.
Use o resultado na sua sessão, por exemplo transmitindo-o para os clientes conectados.

O exemplo a seguir mostra uma função de backend que lê uma chave de API e retorna uma tradução:

// base44/functions/translateText/entry.ts
import { secrets } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  const { text } = await req.json();
  const apiKey = secrets.get("TRANSLATE_API_KEY");

  const res = await fetch("https://api.example.com/translate", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: JSON.stringify({ text }),
  });
  const { translation } = await res.json();

  return Response.json({ translation });
}

O exemplo a seguir chama essa função a partir de um actor e transmite o resultado:

export default class ChatRoom extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    const result = await this.client.functions.invoke("translateText", { text: msg.text });
    this.broadcast({ type: "message", text: result.data.translation });
  }
}

Veja também

Visão geral de actors: Conceitos e terminologia
Criar um actor: Arquivos do actor e uma classe mínima
Arquivos e código de actors: API completa da classe de backend
actors deploy: Implante actors locais

Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a versão em inglês.

Visão geral

Início rápido

Projeto

Ferramentas de Desenvolvimento com IA

Recursos

Conectar um cliente a uma sessão

Executar ticks

Agendar wakes

Gerenciar conexões de clientes

Persistir dados da sessão

Gravar dados de entidades a partir de uma sessão

Chamar uma função de backend para trabalhos com secrets

Veja também

​Conectar um cliente a uma sessão

​Executar ticks

​Agendar wakes

​Gerenciar conexões de clientes

​Persistir dados da sessão

​Gravar dados de entidades a partir de uma sessão

​Chamar uma função de backend para trabalhos com secrets

​Veja também

Conectar um cliente a uma sessão

Executar ticks

Agendar wakes

Gerenciar conexões de clientes

Persistir dados da sessão

Gravar dados de entidades a partir de uma sessão

Chamar uma função de backend para trabalhos com secrets

Veja também