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 devuelven el resultado del proceso.

Las UDF tienen las siguientes propiedades clave:

  • Código: Es el código JavaScript que define la lógica de transformación.

  • 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.

Crea la función de JavaScript

El código de la UDF 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

La función toma las siguientes 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 del mensaje.

  • 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

La función debe devolver uno de los siguientes valores:

  • 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.

Requisitos de entrada y salida

  • Si la UDF transforma la carga útil del mensaje, la entrada y la salida de la carga útil deben ser cadenas codificadas en UTF-8.
  • Si la UDF no transforma la carga útil del mensaje, esta puede usar cualquier codificación.
  • Los pares clave-valor de los atributos deben ser cadenas codificadas en UTF-8.

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.

Crea una SMT de UDF

Los SMT se pueden configurar en temas o suscripciones de Pub/Sub.

  • Los SMT de temas se ejecutan antes de que Pub/Sub almacene el mensaje, y los resultados están disponibles para todos los suscriptores.

  • Los SMT de suscripción se ejecutan antes de que se entregue el mensaje, y los resultados solo están disponibles para esa suscripción.

Console

  1. En la consola de Google Cloud , ve a la página Temas de Pub/Sub.

    Ir a temas

  2. Crea un tema o una suscripción.

    • Para crear un tema, haz clic en Crear tema. Se abrirá la página Crear tema.

    • Sigue los pasos a continuación para crear una suscripción:

      1. Haz clic en el nombre del tema al que deseas suscribirte.

      2. Haz clic en Crear suscripción. Se abrirá la página Agregar suscripción al tema.

  3. En Transformaciones, haz clic en Agregar una transformación.

  4. En Tipo de transformación, selecciona UDF de JavaScript.

  5. En el campo Nombre de la función, ingresa el nombre de la función de JavaScript a la que llama el SMT. Ejemplo: redactSSN.

  6. En el área de texto, ingresa el código de la UDF. Ejemplo:

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

    El código debe contener una función cuyo nombre coincida con el campo Nombre de la función.

  7. Si no quieres que la SMT esté activa de inmediato, selecciona Inhabilitar transformación. Cuando se selecciona esta opción, se crea el SMT con el tema, pero no se ejecuta en los mensajes entrantes. Después de crear el tema, puedes editarlo para habilitar el SMT.

  8. Para crear el tema o la suscripción, haz clic en Crear.

gcloud

Crea un archivo de definición

Crea un archivo YAML o JSON que defina el SMT de la UDF.

YAML 

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

JSON 

{
  "javascriptUdf": {
    "code": {
      FUNCTION_CODE
    }
    "functionName": FUNCTION_NAME
  }
}

Reemplaza lo siguiente:

  • FUNCTION_CODE: Es el código de JavaScript para la UDF. El código debe contener una función cuyo nombre coincida con el campo functionName. Ejemplo:

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

  • FUNCTION_NAME: Es el nombre de la función de JavaScript a la que llama el SMT. Ejemplo: redactSSN.

Crea un tema o una suscripción

Para crear un tema, ejecuta el comando gcloud pubsub topics create.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Reemplaza lo siguiente:

  • TOPIC_ID: Es el ID o el nombre del tema que deseas crear.
  • TRANSFORMS_FILE: Es la ruta de acceso al archivo de definición.

Para crear una suscripción, ejecuta el comando gcloud pubsub subscriptions create.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Reemplaza lo siguiente:

  • SUBSCRIPTION_ID: Es el ID o el nombre de la suscripción que se creará.

  • PROJECT_ID: Es el ID del proyecto que contiene el tema.

  • TOPIC_ID: Es el ID del tema al que se suscribirá.

  • TRANSFORMS_FILE: Es la ruta de acceso al archivo de definición.

De manera opcional, puedes validar y probar la SMT antes de crearla. Para obtener más información, consulta las siguientes páginas:

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. Puedes encontrar muestras adicionales en la biblioteca de UDF.

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?