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 un solo mensaje (SMT). Las UDF proporcionan una forma flexible de implementar una lógica de transformación personalizada en Pub/Sub, 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: Es un objeto JavaScript que contiene metadatos inmutables sobre el mensaje de Pub/Sub:

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

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

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

Salidas

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

  • Para filtrar un mensaje, muestra 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 muestra null.

    • SMT de temas: Pub/Sub muestra un estado de éxito al publicador y incluye un ID de mensaje en la respuesta de 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 muestra un error.

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

    • SMT de suscripción: Pub/Sub confirma negativamente el mensaje.

Límites de recursos

Pub/Sub aplica límites de recursos en las UDF para garantizar operaciones de transformación eficaces. Entre las limitaciones, se incluyen las siguientes:

  • Máximo de 20 KB de código por UDF
  • Máximo de 500 ms de ejecución por mensaje
  • No hay llamadas a APIs externas.
  • No hay importaciones de bibliotecas externas.

UDF de muestra

Estos son algunos ejemplos de UDF para publicar y suscribirse.

Función: Convierte un número entero de 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 vuelve a serializar la carga útil modificada 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: Ocultar 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 arroja un error.

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

  3. La UDF vuelve a serializar la carga útil modificada 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: Filtra y confirma automáticamente 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 muestra valor 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 tu 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 arroja un error.

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

  5. Luego, Pub/Sub marca el mensaje como fallido o pasa el mensaje original 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?