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: Es 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) 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 de temas: Pub/Sub devuelve un mensaje de éxito al publicador y, además, incluye un ID de mensaje en la respuesta 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 la recepción del mensaje de forma negativa.

Crea un 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.

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

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

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

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

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

• Crea un tema con SMT
• Crea una suscripción con SMT

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 admiten los objetos integrados estándar de ECMAScript.
• No se realizan llamadas a APIs externas
• No se importan bibliotecas externas

UDF de muestra

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 del mensaje:

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 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 del mensaje:

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 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 del mensaje:

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 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 del mensaje:

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 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?

• Elige entre los SMT de temas y suscripciones

• Crea un tema con SMT

• Crea una suscripción con SMT

• Explora muestras adicionales en la biblioteca de UDF