Vista geral das funções definidas pelo utilizador (FDUs)

Uma função definida pelo utilizador (FDU) em JavaScript é um tipo de transformação de mensagem única (SMT). As UDFs oferecem uma forma flexível de implementar lógica de transformação personalizada no Pub/Sub, semelhante às UDFs JavaScript do BigQuery.

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

As FDU 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. Este código tem de 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

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

    • data: (String, obrigatório) A carga útil da mensagem.

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

  • Argumento metadata: um objeto JavaScript que contém metadados imutáveis acerca da mensagem Pub/Sub:

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

    • publish_time: (String, opcional) A hora 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.

Resultados

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

  • Para filtrar uma mensagem, devolva null.

Requisitos de entrada / saída

  • Se a FDU transformar o conteúdo útil da mensagem, a entrada e a saída do conteúdo útil têm de ser strings codificadas em UTF-8.
  • Se a UDF não transformar o payload da mensagem, o payload pode usar qualquer codificação.
  • Os pares de chave-valor dos atributos têm de ser strings codificadas em UTF-8.

Como as FUDs transformam uma mensagem

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

  • A FDU transforma uma mensagem.

  • A FDU devolve null.

    • SMTs de tópicos: o Pub/Sub devolve êxito ao publicador e inclui um ID da mensagem na resposta para as mensagens filtradas. O Pub/Sub não armazena a mensagem nem a envia para nenhum subscritor.

    • SMTs de subscrição: o Pub/Sub confirma a entrega da mensagem sem enviar a mensagem a um subscritor.

  • A FDU gera um erro.

    • SMTs de tópicos: o Pub/Sub devolve o erro ao publicador e não publica nenhuma das mensagens.

    • SMTs de subscrição: o Pub/Sub acusa negativamente a receção da mensagem.

Limitações

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

  • Um máximo de 20 KB de código por FDU
  • Um máximo de 500 ms de tempo de execução por mensagem
  • Suporte apenas para incorporações padrão do ECMAScript
  • Sem chamadas para APIs externas
  • Nenhuma importação de bibliotecas externas

Exemplos de FDUs

Seguem-se alguns exemplos de FUDs para publicação e subscrição. Pode encontrar amostras adicionais na biblioteca de FDU.

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

Quando adiciona a seguinte UDF a um tópico ou a uma subscrição, as seguintes alterações ocorrem durante a publicação ou a entrega de mensagens:

  1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver uma carga útil JSON, a UDF gera um erro.

  2. A FDU procura um campo denominado dayOfWeek e, se o valor deste campo for um número entre 0 e 6, converte-o num 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 define o campo dayOfWeek como Unknown.

  3. A UDF serializa o payload modificado de volta para a mensagem.

  4. O Pub/Sub passa a mensagem atualizada para o passo seguinte no 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 da segurança social

Quando adiciona a seguinte UDF a um tópico ou a uma subscrição, as seguintes alterações ocorrem durante a publicação ou a entrega de mensagens:

  1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver uma carga útil JSON, a UDF gera um erro.

  2. A FDU remove o campo ssn do payload da mensagem (se existir).

  3. A UDF serializa o payload modificado de volta para a mensagem.

  4. O Pub/Sub passa a mensagem atualizada para o passo seguinte no 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 adiciona a seguinte UDF a um tópico ou a uma subscrição, as seguintes alterações ocorrem durante a publicação ou a entrega de mensagens:

  1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver uma carga útil JSON, a UDF gera um erro.

  2. A FDU verifica se a carga útil contém um campo denominado region.

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

  4. Se o valor do campo region for US, o Pub/Sub passa a mensagem original para o passo seguinte no seu 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 é superior a 100

Quando adiciona a seguinte UDF a um tópico ou a uma subscrição, as seguintes alterações ocorrem durante a publicação ou a entrega de mensagens:

  1. O Pub/Sub aplica a função à mensagem. Se a mensagem não tiver uma carga útil JSON, a UDF gera um erro.

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

  3. Se o valor do campo amount for superior a 100, a função gera um erro.

  4. Se o valor do campo amount não for superior a 100, a função devolve a mensagem original.

  5. Em seguida, o Pub/Sub marca a mensagem como falhada ou transmite a mensagem original ao passo seguinte no seu pipeline.

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

O que se segue?