Descripción general de las funciones definidas por el usuario (UDF)

Una función definida por el usuario (UDF) de JavaScript es un tipo de transformación de mensaje único (SMT). Las UDF proporcionan una forma flexible de implementar lógica de transformación personalizada en Pub/Sub, de manera similar a las UDF de JavaScript de BigQuery.

Las UDF aceptan un solo mensaje como entrada, realizan las acciones definidas en la entrada y muestran el resultado del proceso.

Las UDF tienen las siguientes propiedades clave:

  • Nombre de la función: Es el nombre de la función de JavaScript dentro del código proporcionado que Pub/Sub aplica a los mensajes.

  • Código: Es el código JavaScript que define la lógica de transformación. Este código debe contener una función con la siguiente firma:

    /**
* 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: Es un objeto JavaScript que representa el mensaje de Pub/Sub. Contiene las siguientes propiedades:

    • data: (String, obligatorio) Es la carga útil del mensaje.

    • attributes: (Object<String, String>, opcional) Es un mapa de pares clave-valor que representan atributos de mensajes.

  • Argumento metadata: Un objeto JavaScript que contiene metadatos inmutables sobre el mensaje de Pub/Sub:

    • message_id: (String, opcional) ID único del mensaje.

    • publish_time: (String, opcional) Es la fecha y hora de publicación del mensaje en formato RFC 3339 (AAAA-MM-DDTHH:mm:ssZ).

    • ordering_key: (String, opcional) Es la clave de ordenamiento del mensaje, si corresponde.

Salidas

  • Para transformar un mensaje, edita el contenido de message.data y message.attributes, y devuelve el objeto message modificado.

  • Para filtrar un mensaje, devuelve null.

Cómo las UDF transforman un mensaje

El resultado de ejecutar una UDF en un mensaje puede ser uno de los siguientes:

  • La UDF transforma un mensaje.

  • La UDF devuelve null.

    • SMT del tema: Pub/Sub devuelve un mensaje de éxito al publicador y, en la respuesta, incluye un ID de mensaje para los mensajes filtrados. Pub/Sub no almacena el mensaje ni lo envía a ningún suscriptor.

    • SMT de suscripción: Pub/Sub confirma la entrega del mensaje sin enviarlo a un suscriptor.

  • La UDF arroja un error.

    • SMT de temas: Pub/Sub devuelve el error al publicador y no publica ninguno de los mensajes.

    • SMT de suscripción: Pub/Sub confirma negativamente la recepción del mensaje.

Limitaciones

Pub/Sub aplica límites de recursos en las UDF para garantizar operaciones de transformación eficientes. Las limitaciones incluyen lo siguiente:

  • Un máximo de 20 KB de código por UDF
  • Un máximo de 500 ms de tiempo de ejecución por mensaje
  • Solo se admite ECMAScript estándar integrado
  • No se realizan llamadas a APIs externas
  • No se importan bibliotecas externas

Ejemplos de UDF

A continuación, se incluyen algunas UDF de ejemplo para publicar y suscribirse.

Función: Convierte un número entero del día de la semana en la cadena correspondiente

Cuando agregas la siguiente UDF a un tema o una suscripción, se producen los siguientes cambios durante la publicación o entrega de mensajes:

  1. Pub/Sub aplica la función al mensaje. Si el mensaje no tiene una carga útil JSON, la UDF genera un error.

  2. La UDF busca un campo llamado dayOfWeek y, si el valor de este campo es un número entre 0 y 6, lo convierte en el día de la semana correspondiente, como Monday. Si el campo no existe o el número no está en el rango de 0 a 6, el código establece el campo dayOfWeek en Unknown.

  3. La UDF serializa la carga útil modificada de nuevo en el mensaje.

  4. Pub/Sub pasa el mensaje actualizado al siguiente paso de tu canalización.

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;
}

Función: Redactar un número de seguridad social

Cuando agregas la siguiente UDF a un tema o una suscripción, se producen los siguientes cambios durante la publicación o entrega de mensajes:

  1. Pub/Sub aplica la función al mensaje. Si el mensaje no tiene una carga útil JSON, la UDF genera un error.

  2. La UDF quita el campo ssn de la carga útil del mensaje (si existe).

  3. La UDF serializa la carga útil modificada de nuevo en el mensaje.

  4. Pub/Sub pasa el mensaje actualizado al siguiente paso de tu canalización.

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

Función: Filtrar y confirmar automáticamente la recepción de mensajes específicos

Cuando agregas la siguiente UDF a un tema o una suscripción, se producen los siguientes cambios durante la publicación o entrega de mensajes:

  1. Pub/Sub aplica la función al mensaje. Si el mensaje no tiene una carga útil JSON, la UDF genera un error.

  2. La UDF verifica si la carga útil contiene un campo llamado region.

  3. Si el valor del campo region no es US, la función devuelve nulo, lo que hace que Pub/Sub filtre el mensaje.

  4. Si el valor del campo region es US, Pub/Sub pasa el mensaje original al siguiente paso de la canalización.

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

Función: Valida el contenido del mensaje para garantizar que el importe no sea superior a 100.

Cuando agregas la siguiente UDF a un tema o una suscripción, se producen los siguientes cambios durante la publicación o entrega de mensajes:

  1. Pub/Sub aplica la función al mensaje. Si el mensaje no tiene una carga útil JSON, la UDF genera un error.

  2. La UDF verifica si el mensaje contiene un campo llamado amount.

  3. Si el valor del campo amount es mayor que 100, la función genera un error.

  4. Si el valor del campo amount no es mayor que 100, la función devuelve el mensaje original.

  5. Luego, Pub/Sub marca el mensaje como con errores o lo pasa al siguiente paso de la canalización.

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

¿Qué sigue?