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 enrutando 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 al tema.

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

• Publicación: Usa la actividad Publish Message 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 necesita notificarse a servicios posteriores.
• Recepción: Usa la actividad Get Message para sondear una suscripción en busca de mensajes pendientes; después, usa la actividad Acknowledge Message para confirmar que cada mensaje ha sido procesado.

Esta guía cubre ambos patrones. Para el consumo de mensajes basado en eventos (donde Studio escucha continuamente en lugar de sondear), consulta la referencia de la actividad Listen Message, que requiere un clúster de agente privado con configuración de red específica.

Esta guía asume lo siguiente:

• Una cuenta de servicio de Google Cloud con la API 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 Project endpoints and connectors en la paleta de componentes de diseño.

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

3. Connection Name: Introduce un nombre único (por ejemplo, Google Pub/Sub). El nombre no puede contener barras oblicuas ni dos puntos.

4. Project ID: Introduce el valor project_id del archivo JSON de credenciales de la cuenta de servicio.

5. Client Email: Introduce el valor client_email del archivo JSON de credenciales.

6. Private Key String: Introduce el valor private_key del archivo JSON de credenciales, con el siguiente formato:

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

   Nota

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

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

8. Haz clic en Save Changes.

Parte 2: Publicar un mensaje en un tema

La actividad Publish Message es una actividad de destino. Úsala 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. Puede ser cualquier actividad que devuelva datos, como una actividad de Query de base de datos o Salesforce, una fuente de archivo o la respuesta de otro conector. La transformación en el Paso 2 asigna esos datos de origen en la solicitud de Publish Message. 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 correspondiente.

Paso 1: Configurar la actividad Publish Message

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

2. Name: Introduce un nombre descriptivo (por ejemplo, Publish Order Created).

3. Choose Topic: Selecciona cómo especificar el tema:

   • Select Existent Topic: Elige de una lista de temas cargados desde tu proyecto de Google Cloud. Requiere el permiso pubsub.topics.list en la cuenta de servicio.
   • Inform Topic Manually: Introduce 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 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 hay un esquema configurado, body acepta un valor de cadena; serializa tus datos a JSON antes de mapearlos:

   JSONStringify($source_data)
   

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

Parte 3: Recibe y reconoce 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 del procesamiento. Pub/Sub reentrega los mensajes no reconocidos después de que vence 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 Obtener Mensaje desde la conexión de Google Pub/Sub al lienzo.

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

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). Establécelo al tamaño de lote que tu procesamiento posterior puede manejar.

5. Plazo de Reconocimiento en Segundos: Opcionalmente, establece cuánto tiempo Pub/Sub mantiene el mensaje antes de reenviarlo si no se reconoce (1–600 segundos). Déjalo 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: Procesa 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 desde el esquema de respuesta al destino.

   El esquema de respuesta incluye un campo messageId y un campo body para la carga útil del mensaje. Si el cuerpo del mensaje es JSON, desserialí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 referenciarlo:

   $ack_id = Source.ackId;
   

Paso 3: Configura la actividad Reconocer Mensaje

Después de procesar los mensajes, reconócelos para evitar su reentrega.

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

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

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 Reconocer 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 Reconocer Mensaje para ejecutarse En Caso de Éxito de la operación de procesamiento.

Verifica 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 > Topics > [nombre del tema]) que el recuento de mensajes aumentó. Alternativamente, utiliza el patrón Get Message para extraer el mensaje y confirmar la carga útil.

Recepción: Publica un mensaje de prueba en el tema de la suscripción usando la consola de Google Cloud (Pub/Sub > Topics > [nombre del tema] > Publish Message). Ejecuta la operación Get Message y revisa los registros de operación para confirmar que el mensaje se recuperó. Verifica que el destino se escribió con los datos esperados y luego confirma que el mensaje ya no aparece en la suscripción (lo que indica reconocimiento exitoso).

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