Publicar y recibir mensajes de Google Pub/Sub en Jitterbit Studio

Introducción

Google Cloud Pub/Sub es un servicio de mensajería administrado que desacopla sistemas al enrutar mensajes a través de temas y suscripciones. Un publicador escribe mensajes en un tema; uno o más suscriptores reciben esos mensajes a través de suscripciones adjuntas a ese tema.

El conector de Google Pub/Sub proporciona actividades para ambos lados de este patrón:

• Publicación: Utiliza la actividad Publicar Mensaje para escribir mensajes en un tema de Pub/Sub desde una operación de Studio, por ejemplo, cuando se crea un registro en un sistema de origen y los servicios posteriores necesitan ser notificados.
• Recepción: Utiliza la actividad Obtener Mensaje para sondear una suscripción en busca de mensajes pendientes, luego utiliza la actividad Reconocer Mensaje para confirmar que cada mensaje ha sido procesado.

Esta guía cubre ambos patrones. Para la consumo de mensajes impulsado por eventos (donde Studio escucha continuamente en lugar de sondear), consulta la referencia de la actividad Escuchar Mensaje, que requiere un clúster de agentes privado con una configuración de red específica.

Esta guía asume lo siguiente:

• Una cuenta de servicio de Google Cloud con la API de Pub/Sub habilitada y roles apropiados asignados, como se describe en requisitos previos de Google Pub/Sub.
• El tema y la suscripción ya existen en Google Pub/Sub.

Parte 1: Configurar la conexión de Google Pub/Sub

1. En Studio, abre tu proyecto y ve a la pestaña Puntos finales y conectores del proyecto en la paleta de componentes de diseño.

2. Haz clic en el conector Google Pub/Sub para abrir la configuración de la conexión.

3. Nombre de la Conexión: Ingresa un nombre único (por ejemplo, Google Pub/Sub). El nombre no puede contener barras diagonales o dos puntos.

4. ID del Proyecto: Ingresa el valor project_id del archivo JSON de credenciales de la cuenta de servicio.

5. Correo Electrónico del Cliente: Ingresa el valor client_email del archivo JSON de credenciales.

6. Cadena de Clave Privada: Ingresa el valor private_key del archivo JSON de credenciales, formateado como:

   -----BEGIN PRIVATE KEY-----<private_key>-----END PRIVATE KEY-----
   

   Nota

   El valor private_key en el archivo JSON utiliza \n para representar saltos de línea. Reemplaza cada \n con un retorno de carro real antes de pegarlo en este campo. Si la clave se pega con caracteres \n literales, la prueba de conexión devuelve un error de Datos PKCS#8 no válidos.

7. Haz clic en Probar para verificar la conexión.

8. Haz clic en Guardar Cambios.

Parte 2: Publicar un mensaje en un tema

La actividad Publicar Mensaje es una actividad de destino. Utilízala al final de una transformación para escribir datos como un mensaje en un tema de Pub/Sub.

Patrón de diseño

La operación comienza con una actividad de origen que proporciona los datos a publicar. Esto puede ser cualquier actividad que devuelva datos, como una actividad de Consulta de base de datos o Salesforce, una fuente de archivo, o la respuesta de otro conector. La transformación en Paso 2 mapea esos datos de origen en la solicitud de Publicar Mensaje. Los pasos a continuación asumen que ya hay una actividad de origen en la operación; para la configuración de la actividad de origen, consulta la documentación del conector relevante.

Paso 1: Configurar la actividad Publicar Mensaje

1. En el lienzo de diseño, arrastra una actividad Publicar Mensaje desde la conexión de Google Pub/Sub al lienzo.

2. Nombre: Ingresa un nombre descriptivo (por ejemplo, Publicar Pedido Creado).

3. Elegir Tema: Selecciona cómo especificar el tema:

   • Seleccionar Tema Existente: Elige de una lista de temas cargados desde tu proyecto de Google Cloud. Requiere el permiso pubsub.topics.list en la cuenta de servicio.
   • Informar Tema Manualmente: Ingresa el nombre del tema directamente. Usa esto si el nombre del tema es dinámico o la cuenta de servicio no tiene permiso de lista.

4. Tema: Ingresa o selecciona el nombre del tema (por ejemplo, order-events).

5. Haz clic en Siguiente, revisa el esquema de solicitud y luego haz clic en Finalizado.

Paso 2: Mapea la transformación

1. Agrega un paso de Transformación entre la actividad de origen y la actividad de Publicar Mensaje.

2. Abre la transformación. Mapea los campos de datos del origen al esquema de solicitud de Publicar Mensaje.

   El esquema de solicitud incluye un nodo body para la carga útil del mensaje. Si el tema tiene un esquema configurado en Google Pub/Sub, el nodo body refleja ese esquema. Si no se configura un esquema, body acepta un valor de cadena; serializa tus datos a JSON antes de mapearlos:

   JSONStringify($source_data)
   

3. Despliega y ejecuta la operación para publicar un mensaje.

Parte 3: Recibir y reconocer mensajes de una suscripción

Recibir mensajes requiere dos operaciones: una para recuperar mensajes pendientes de una suscripción y otra para reconocerlos después de procesarlos. Los mensajes no reconocidos son entregados nuevamente por Pub/Sub después de que expira el plazo de reconocimiento.

Patrón de diseño

Paso 1: Configura la actividad Obtener Mensaje

1. En el lienzo de diseño, arrastra una actividad de Obtener Mensaje desde la conexión de Google Pub/Sub al lienzo.

2. Nombre: Ingresa un nombre descriptivo (por ejemplo, Obtener Eventos de Pedido).

3. Elegir Suscripción: Selecciona Seleccionar Suscripción Existente o Informar Suscripción Manualmente, luego ingresa o selecciona el nombre de la suscripción.

4. Cantidad de Mensajes: Ingresa el número de mensajes a recuperar por ejecución de operación (1–100, por defecto 1). Establece esto al tamaño del lote que tu procesamiento posterior puede manejar.

5. Plazo de Reconocimiento en Segundos: Opcionalmente, establece cuánto tiempo Pub/Sub retiene el mensaje antes de volver a entregarlo si no se reconoce (1–600 segundos). Deja en blanco para usar el plazo configurado de la suscripción.

6. Haz clic en Siguiente, revisa el esquema de respuesta y luego haz clic en Finalizado.

Paso 2: Procesar los mensajes en una transformación

1. Agrega un paso de Transformación después de la actividad Obtener Mensaje.

2. Abre la transformación y mapea los campos del mensaje del esquema de respuesta al objetivo.

   El esquema de respuesta incluye un campo messageId y un campo body para la carga del mensaje. Si el cuerpo del mensaje es JSON, deserialízalo en la transformación:

   JSONParser(Source.body)
   

   Almacena el messageId (o el campo ackId) en una variable global para que el paso de reconocimiento pueda hacer referencia a él:

   $ack_id = Source.ackId;
   

Paso 3: Configurar la actividad de Reconocimiento de Mensaje

Después de que los mensajes sean procesados, reconócelos para evitar la reentrega.

1. En el lienzo de diseño, arrastra una actividad de Reconocimiento de Mensaje desde la conexión de Google Pub/Sub al lienzo.

2. Nombre: Ingresa un nombre descriptivo (por ejemplo, Reconocer Eventos de Pedido).

3. Elegir Suscripción: Selecciona la misma suscripción utilizada en la actividad Obtener Mensaje.

4. Haz clic en Siguiente, revisa el esquema y luego haz clic en Finalizado.

5. Agrega un paso de Transformación entre la transformación de procesamiento y la actividad de Reconocimiento de Mensaje. Mapea el valor ackId almacenado en ack_id al esquema de solicitud de reconocimiento.

6. En la configuración de operación, configura la operación de Reconocimiento de Mensaje para que se ejecute Al Éxito de la operación de procesamiento.

Verificar la integración

Publicación: Envía un registro de prueba a través de la operación y verifica en la Consola de Google Cloud (Pub/Sub > Temas > [nombre del tema]) que el conteo de mensajes haya aumentado. Alternativamente, utiliza el patrón Obtener Mensaje para recuperar el mensaje y confirmar la carga.

Recepción: Publica un mensaje de prueba en el tema de la suscripción utilizando la Consola de Google Cloud (Pub/Sub > Temas > [nombre del tema] > Publicar mensaje). Ejecuta la operación Obtener mensaje y verifica los registros de operación para confirmar que el mensaje fue recuperado. Verifica que el destino se haya escrito con los datos esperados, luego confirma que el mensaje ya no aparece en la suscripción (lo que indica un reconocimiento exitoso).

Si la prueba de conexión falla, verifica que la cuenta de servicio tenga los roles correctos asignados como se describe en los requisitos previos de Google Pub/Sub.