Informações gerais sobre as funções definidas pelo usuário (UDFs)

Uma função definida pelo usuário (UDF) do JavaScript é um tipo de transformação de mensagem única (SMT, na sigla em inglês). As UDFs oferecem uma maneira flexível de implementar lógica de transformação personalizada no Pub/Sub, semelhante às UDFs JavaScript do BigQuery.

As UDFs aceitam uma única mensagem como entrada, realizam as ações definidas na entrada e retornam o resultado do processo.

As UDFs têm as seguintes propriedades principais:

• Nome da função:o nome da função JavaScript no código fornecido que o Pub/Sub aplica às mensagens.

• Código:o código JavaScript que define a lógica de transformação. Esse código precisa conter uma função com a seguinte assinatura:

  /**
  * Transforms a Pub/Sub message.
  * @return {(Object<string, (string | Object<string, string>)>|* null)} - To
  * filter a message, return `null`. To transform a message, return a map with
  * the following keys:
  *   - (required) 'data' : {string}
  *   - (optional) 'attributes' : {Object<string, string>}
  * Returning empty `attributes` will remove all attributes from the message.
  *
  * @param  {(Object<string, (string | Object<string, string>)>} - Pub/Sub
  * message. Keys:
  *   - (required) 'data' : {string}
  *   - (required) 'attributes' : {Object<string, string>}
  *
  * @param  {Object<string, any>} metadata - Pub/Sub message metadata.
  * Keys:
  *   - (optional) 'message_id'  : {string}
  *   - (optional) 'publish_time': {string} YYYY-MM-DDTHH:MM:SSZ format
  *   - (optional) 'ordering_key': {string}
  */
  function <function_name>(message, metadata) {
    // Perform custom transformation logic
    return message; // to filter a message instead, return `null`
  }
  

Entradas

• Argumento message:um objeto JavaScript que representa a mensagem do Pub/Sub. Ele contém as seguintes propriedades:

  • data: (String, obrigatório) O payload da mensagem.

  • attributes: (Object<String, String>, opcional) um mapa de pares de chave-valor que representam atributos de mensagem.

• Argumento metadata:um objeto JavaScript que contém metadados imutáveis sobre a mensagem do Pub/Sub:

  • message_id: (String, opcional) O ID exclusivo da mensagem.

  • publish_time: (String, opcional) o horário de publicação da mensagem no formato RFC 3339 (AAAA-MM-DDTHH:mm:ssZ).

  • ordering_key: (String, opcional) a chave de ordenação da mensagem, se aplicável.

Saídas

• Para transformar uma mensagem, edite o conteúdo de message.data e message.attributes e retorne o objeto message alterado.

• Para filtrar uma mensagem, retorne null.

Como as UDFs transformam uma mensagem

O resultado da execução de uma UDF em uma mensagem pode ser um dos seguintes:

• A UDF transforma uma mensagem.

• A UDF retorna null.

  • SMTs de tópico: o Pub/Sub retorna sucesso ao editor e inclui um ID de mensagem na resposta para as mensagens filtradas. O Pub/Sub não armazena nem envia a mensagem para nenhum assinante.

  • SMTs de assinatura: o Pub/Sub confirma a entrega da mensagem sem enviá-la a um assinante.

• A UDF gera um erro.

  • SMTs de tópico: o Pub/Sub retorna o erro ao editor e não publica nenhuma das mensagens.

  • SMTs de assinatura: o Pub/Sub envia uma confirmação negativa da mensagem.

Limitações

O Pub/Sub aplica limites de recursos às UDFs para garantir operações de transformação eficientes. As limitações incluem:

• No máximo 20 KB de código por UDF
• Tempo máximo de execução de 500 ms por mensagem
• Suporte apenas para ECMAScript padrão integrado
• Nenhuma chamada para APIs externas
• Sem importações de bibliotecas externas

Exemplos de UDFs

Confira alguns exemplos de UDFs para publicação e inscrição.

Função: converte um número inteiro de um dia da semana na string correspondente.

Quando você adiciona a UDF a seguir a um tópico ou uma assinatura, as seguintes mudanças ocorrem durante a publicação ou entrega da mensagem:

1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver um payload JSON, a UDF vai gerar um erro.

2. A UDF procura um campo chamado dayOfWeek e, se o valor desse campo for um número entre 0 e 6, o converte em um dia da semana correspondente, como Monday. Se o campo não existir ou o número não estiver no intervalo de 0 a 6, o código vai definir o campo dayOfWeek como Unknown.

3. A UDF serializa o payload modificado de volta na mensagem.

4. O Pub/Sub transmite a mensagem atualizada para a próxima etapa do seu pipeline.

function intToString(message, metadata) {
  const data = JSON.parse(message.data);
  switch(`data["dayOfWeek"]`) {
    case 0:
      data["dayOfWeek"] = "Sunday";
      break;
    case 1:
      data["dayOfWeek"] = "Monday";
      break;
    case 2:
      data["dayOfWeek"] = "Tuesday";
      break;
    case 3:
      data["dayOfWeek"] = "Wednesday";
      break;
    case 4:
      data["dayOfWeek"] = "Thursday";
      break;
    case 5:
      data["dayOfWeek"] = "Friday";
      break;
    case 6:
      data["dayOfWeek"] = "Saturday";
      break;
    default:
      data["dayOfWeek"] = "Unknown";
  }
  message.data = JSON.stringify(data);
  return message;
}

Função: ocultar um número de CPF ou CNPJ

Quando você adiciona a UDF a seguir a um tópico ou uma assinatura, as seguintes mudanças ocorrem durante a publicação ou entrega da mensagem:

1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver um payload JSON, a UDF vai gerar um erro.

2. A UDF remove o campo ssn do payload da mensagem, se ele existir.

3. A UDF serializa o payload modificado de volta na mensagem.

4. O Pub/Sub transmite a mensagem atualizada para a próxima etapa do seu pipeline.

function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

Função: filtrar e confirmar automaticamente mensagens específicas

Quando você adiciona a UDF a seguir a um tópico ou uma assinatura, as seguintes mudanças ocorrem durante a publicação ou entrega da mensagem:

1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver um payload JSON, a UDF vai gerar um erro.

2. A UDF verifica se o payload contém um campo chamado region.

3. Se o valor do campo region não for US, a função vai retornar nulo, fazendo com que o Pub/Sub filtre a mensagem.

4. Se o valor do campo region for US, o Pub/Sub vai transmitir a mensagem original para a próxima etapa do pipeline.

function filterForUSRegion(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["region"] !== "US") {
    return null;
  }
  return message;
}

Função: valida o conteúdo da mensagem para garantir que o valor não seja maior que 100

Quando você adiciona a UDF a seguir a um tópico ou uma assinatura, as seguintes mudanças ocorrem durante a publicação ou entrega da mensagem:

1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver um payload JSON, a UDF vai gerar um erro.

2. A UDF verifica se a mensagem contém um campo chamado amount.

3. Se o valor do campo amount for maior que 100, a função vai gerar um erro.

4. Se o valor do campo amount não for maior que 100, a função vai retornar a mensagem original.

5. Em seguida, o Pub/Sub marca a mensagem como falha ou transmite a mensagem original para a próxima etapa do pipeline.

function validateAmount(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["amount"] > 100) {
    throw new Error("Amount is invalid");
  }
  return message;
}

A seguir

• Escolha entre SMTs de tópico e assinatura

• Criar um tópico com SMTs

• Criar uma assinatura com SMTs