Enviar y recibir mensajes de Azure Service Bus en Jitterbit Studio

Introducción

Azure Service Bus es un servicio de mensajería administrado que admite dos patrones de mensajería:

• Colas: Mensajería punto a punto donde cada mensaje es consumido por un único receptor.
• Temas y suscripciones: Mensajería de publicación-suscripción donde cada mensaje se entrega a varios suscriptores a través de suscripciones de tema.

El conector Microsoft Azure Service Bus proporciona actividades para ambos patrones. Esta guía cubre los flujos de trabajo más comunes:

• Enviar un mensaje a una cola o tema mediante la actividad Enviar Mensaje.
• Recuperar mensajes de una cola mediante la actividad Obtener Mensaje de Cola.
• Recuperar mensajes de una suscripción de tema mediante la actividad Obtener Mensaje de Tema.

Para consumo dirigido por eventos (donde Studio escucha continuamente mensajes entrantes), consulta las referencias de actividad Consumir Cola y Consumir Tema, que requieren un clúster de agente privado con configuración de red específica.

Esta guía supone lo siguiente:

• Se configura un espacio de nombres de Azure Service Bus con las colas o temas requeridos.
• La entidad de servicio o política utilizada para la autenticación tiene el rol o derechos apropiados, como se describe en Requisitos previos de Azure Service Bus.

Parte 1: Configurar la conexión de Azure Service Bus

El conector admite dos tipos de autenticación. Utiliza Microsoft Entra ID al conectarse a través de un registro de aplicación de Azure (recomendado para producción). Utiliza Firmas de Acceso Compartido para configuraciones más simples o cuando Entra ID no está disponible.

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

2. Haz clic en el conector Microsoft Azure Service Bus para abrir la configuración de conexión.

3. Nombre de la Conexión: Introduce un nombre único (por ejemplo, Azure Service Bus). El nombre no puede contener barras diagonales ni dos puntos.

4. Tipo de Autenticación: Selecciona uno de los siguientes:

   Microsoft Entra ID:

   • Espacio de Nombres / Nombre de Host: Introduce el nombre del espacio de nombres de Service Bus (por ejemplo, my-namespace) o el nombre de host completo (por ejemplo, my-namespace.servicebus.windows.net).
   • ID de Inquilino: Introduce el ID de directorio (inquilino) de tu Azure Active Directory.
   • ID de Cliente: Introduce el ID de aplicación (cliente) del registro de aplicación.
   • Secreto de Cliente: Introduce el valor del secreto de cliente para el registro de aplicación.

   Firmas de Acceso Compartido:

   • Espacio de Nombres / Nombre de Host: Introduce el nombre del espacio de nombres o el nombre de host completo.
   • Nombre de Política: Introduce el nombre de la Política de Acceso Compartido configurada en el espacio de nombres o la cola.
   • Clave Primaria: Introduce el valor de clave primaria para la política.

5. Haz clic en Prueba para verificar la conexión.

6. Haz clic en Guardar Cambios.

Parte 2: Enviar un mensaje

La actividad Enviar Mensaje es una actividad de destino que escribe un mensaje en una cola o tema. Úsala cuando Studio necesite publicar eventos o datos en sistemas descendentes.

Patrón de diseño

Paso 1: Configurar la actividad Enviar Mensaje

1. En el lienzo de diseño, arrastra una actividad Enviar Mensaje de la conexión Azure Service Bus al lienzo.

2. Nombre: Introduce un nombre descriptivo (por ejemplo, Enviar Pedido a Cola).

3. Elegir Cola/Tema: Selecciona Seleccionar Cola/Tema Existente para elegir de una lista, o Informar Cola/Tema Manualmente para introducir el nombre directamente.

4. Ingresa o selecciona el nombre de la cola o tema.

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

Paso 2: Mapea la transformación

1. Añade un paso de Transformación entre la actividad de origen y la actividad Enviar mensaje.

2. Abre la transformación y mapea los campos de datos al esquema de solicitud de Enviar mensaje. El esquema incluye un campo body para el contenido del mensaje. Para datos estructurados, serializa a JSON antes de mapear:

   JSONStringify($record_data)
   

   El esquema también incluye campos opcionales para propiedades de mensaje como contentType, correlationId y sessionId. Establece estos valores si tus consumidores posteriores los necesitan para enrutamiento o filtrado.

Parte 3: Recupera mensajes de una cola

La actividad Obtener mensaje de cola es una actividad de origen que sondea una cola en busca de mensajes pendientes. Studio procesa cada mensaje recuperado a través de una transformación y lo escribe en el destino.

Patrón de diseño

Paso 1: Configura la actividad Obtener mensaje de cola

1. En el lienzo de diseño, arrastra una actividad Obtener mensaje de cola desde la conexión de Azure Service Bus al lienzo.

2. Nombre: Ingresa un nombre descriptivo (por ejemplo, Obtener pedidos de la cola).

3. Elegir cola: Selecciona o ingresa el nombre de la cola.

4. Modo de recepción: Selecciona una de las siguientes opciones:

   • Bloqueo de lectura: El mensaje se bloquea durante un período configurable mientras Studio lo procesa. El mensaje permanece en la cola hasta que se elimina explícitamente. Usa este modo cuando sea importante el procesamiento confiable: si la operación falla, el bloqueo expira y el mensaje vuelve a estar disponible.
   • Recibir y eliminar: El mensaje se elimina de la cola inmediatamente cuando se recupera. Usa este modo solo cuando sea aceptable la pérdida de mensajes en caso de fallo.

5. Número de mensajes: Ingresa la cantidad de mensajes que se recuperarán por ejecución (1–100, predeterminado 1).

6. Tiempo de espera: Ingresa el tiempo máximo en segundos para esperar mensajes si la cola está vacía (predeterminado 10, máximo 245).

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

Paso 2: Procesa y elimina el mensaje

Cuando uses el modo Bloqueo de lectura, los mensajes deben eliminarse explícitamente después del procesamiento exitoso para quitarlos de la cola. Añade una operación Eliminar mensaje de cola encadenada al éxito de la operación de procesamiento:

1. En el lienzo de diseño, crea una segunda operación que contenga una actividad Eliminar mensaje de cola.

2. En la operación de procesamiento de Obtener mensaje de cola, almacena el token de bloqueo del mensaje en una variable global durante la transformación:

   $lock_token = Source.lockToken;
   

3. Configura la actividad Eliminar mensaje de cola con el mismo nombre de cola y mapea lock_token al esquema de solicitud de eliminación.

4. En la configuración de la operación de procesamiento, configura la operación Eliminar mensaje de cola para ejecutarse Al tener éxito.

Parte 4: Recupera mensajes de una suscripción de tema

La recuperación de una suscripción de tema sigue el mismo patrón que la recuperación de cola, pero requiere seleccionar tanto un tema como una suscripción.

1. En el lienzo de diseño, arrastra una actividad Obtener mensaje de tema desde la conexión de Azure Service Bus al lienzo.

2. Configura la actividad de la misma forma que Obtener mensaje de cola (consulta Parte 3), pero:

   • Selecciona un nombre de Tema.
   • Después de seleccionar el tema, selecciona una Suscripción dentro de ese tema.

3. Para eliminar los mensajes procesados, usa una actividad Eliminar mensaje de tema en lugar de Eliminar mensaje de cola, y selecciona el mismo tema y suscripción.

Verificar la integración

Envío: Ejecuta la operación de envío y verifica en el portal de Azure que el recuento de mensajes en la cola o tema haya aumentado. Usa la función Service Bus Explorer en el portal para inspeccionar el cuerpo del mensaje y sus propiedades.

Recepción: Envía un mensaje de prueba a la cola o tema usando Service Bus Explorer del portal de Azure. Ejecuta la operación Get Queue Message u Get Topic Message y consulta los registros de operación para confirmar que el mensaje se recuperó. Verifica que el destino se escribió con los datos esperados. Si usas Peek Lock, confirma que el mensaje se eliminó de la cola verificando el recuento de mensajes en el portal.

Si la prueba de conexión falla, verifica que la entidad de servicio o la Política de acceso compartido tenga el rol Azure Service Bus Data Owner o los derechos de envío/escucha apropiados, como se describe en Requisitos previos de Azure Service Bus.