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 a lógica de transformação personalizada no Pub/Sub, semelhante às UDFs do BigQuery em JavaScript.

As UDFs aceitam uma única mensagem como entrada, executam 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ópicos: 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 enviar a mensagem 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 confirma a mensagem de forma negativa.

Limites de recursos

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

  • Máximo de 20 KB de código por UDF
  • Execução máxima de 500 ms por mensagem
  • Nenhuma chamada para APIs externas
  • Nenhuma importação de bibliotecas externas

Exemplos de UDFs

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

Função: converta um número inteiro do dia da semana na string correspondente

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

  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. O UDF procura um campo chamado dayOfWeek e, se o valor desse campo for um número entre 0 e 6, ele será convertido 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 à mensagem.

  4. O Pub/Sub transmite a mensagem atualizada para a próxima etapa do 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: omitir um CPF ou CNPJ

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

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

  2. O UDF remove o campo ssn do payload da mensagem (se ele existir).

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

  4. O Pub/Sub transmite a mensagem atualizada para a próxima etapa do 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 o UDF a seguir a um tópico ou uma assinatura, as seguintes mudanças ocorrem durante a publicação ou entrega de mensagens:

  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. O 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 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: validar o conteúdo da mensagem para garantir que o valor não seja maior que 100

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

  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 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. O Pub/Sub marca a mensagem como com falha ou encaminha 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