Senden und Empfangen von Azure Service Bus-Nachrichten in Jitterbit Studio

Einführung

Azure Service Bus ist ein verwalteter Messagingdienst, der zwei Messagingmuster unterstützt:

• Warteschlangen: Point-to-Point-Messaging, bei dem jede Nachricht von einem einzelnen Empfänger verarbeitet wird.
• Themen und Abonnements: Publish-Subscribe-Messaging, bei dem jede Nachricht über Themenabonnements an mehrere Abonnenten zugestellt wird.

Der Microsoft Azure Service Bus-Connector bietet Aktivitäten für beide Muster. Dieses Handbuch behandelt die gängigsten Workflows:

• Senden einer Nachricht an eine Warteschlange oder ein Thema mit der Aktivität Send Message.
• Abrufen von Nachrichten aus einer Warteschlange mit der Aktivität Get Queue Message.
• Abrufen von Nachrichten aus einem Themenabonnement mit der Aktivität Get Topic Message.

Für ereignisgesteuerten Verbrauch (bei dem Studio kontinuierlich auf eingehende Nachrichten wartet), siehe die Referenzen zu den Aktivitäten Consume Queue und Consume Topic, die einen privaten Agent-Cluster mit spezifischer Netzwerkkonfiguration erfordern.

Dieses Handbuch geht von folgenden Voraussetzungen aus:

• Ein Azure Service Bus-Namespace ist mit den erforderlichen Warteschlangen oder Themen konfiguriert.
• Der für die Authentifizierung verwendete Service Principal oder die Richtlinie hat die entsprechende Rolle oder Berechtigung, wie in Azure Service Bus-Voraussetzungen beschrieben.

Teil 1: Konfigurieren der Azure Service Bus-Verbindung

Der Connector unterstützt zwei Authentifizierungstypen. Verwenden Sie Microsoft Entra ID bei der Verbindung über eine Azure-App-Registrierung (empfohlen für die Produktion). Verwenden Sie Shared Access Signatures für einfachere Setups oder wenn Entra ID nicht verfügbar ist.

1. Öffnen Sie in Studio Ihr Projekt und gehen Sie zur Registerkarte Project endpoints and connectors in der Design Component Palette.

2. Klicken Sie auf den Microsoft Azure Service Bus-Connector, um die Verbindungskonfiguration zu öffnen.

3. Connection Name: Geben Sie einen eindeutigen Namen ein (z. B. Azure Service Bus). Der Name darf keine Schrägstriche oder Doppelpunkte enthalten.

4. Authentication Type: Wählen Sie eine der folgenden Optionen:

   Microsoft Entra ID:

   • Namespace / Hostname: Geben Sie den Service Bus-Namespace-Namen (z. B. my-namespace) oder den vollständigen Hostnamen ein (z. B. my-namespace.servicebus.windows.net).
   • Tenant ID: Geben Sie die Verzeichnis-ID (Tenant-ID) Ihres Azure Active Directory ein.
   • Client ID: Geben Sie die Anwendungs-ID (Client-ID) der App-Registrierung ein.
   • Client Secret: Geben Sie den Client Secret-Wert für die App-Registrierung ein.

   Shared Access Signatures:

   • Namespace / Hostname: Geben Sie den Namespace-Namen oder vollständigen Hostnamen ein.
   • Policy Name: Geben Sie den Namen der auf dem Namespace oder der Warteschlange konfigurierten Shared Access Policy ein.
   • Primary Key: Geben Sie den Primärschlüssel-Wert für die Richtlinie ein.

5. Klicken Sie auf Test, um die Verbindung zu überprüfen.

6. Klicken Sie auf Save Changes.

Teil 2: Eine Nachricht senden

Die Aktivität Send Message ist eine Zielaktivität, die eine Nachricht in eine Warteschlange oder ein Thema schreibt. Verwenden Sie sie, wenn Studio Ereignisse oder Daten an nachgelagerte Systeme veröffentlichen muss.

Designmuster

Schritt 1: Konfigurieren Sie die Send Message-Aktivität

1. Ziehen Sie auf der Designfläche eine Aktivität vom Typ Send Message aus der Azure Service Bus-Verbindung auf die Fläche.

2. Name: Geben Sie einen aussagekräftigen Namen ein (z. B. Send Order to Queue).

3. Choose Queue/Topic: Wählen Sie Select Existent Queue/Topic, um aus einer Liste auszuwählen, oder Inform Queue/Topic Manually, um den Namen direkt einzugeben.

4. Geben Sie den Namen der Warteschlange oder des Themas ein, oder wählen Sie ihn aus.

5. Klicken Sie auf Weiter, überprüfen Sie das Anforderungsschema, und klicken Sie dann auf Fertig.

Schritt 2: Mapping der Transformation

1. Fügen Sie einen Transformation-Schritt zwischen der Quellaktivität und der Aktivität Nachricht senden hinzu.

2. Öffnen Sie die Transformation und ordnen Sie Datenfelder dem Anforderungsschema „Nachricht senden" zu. Das Schema enthält ein Feld body für den Nachrichteninhalt. Für strukturierte Daten müssen Sie vor dem Mapping in JSON serialisieren:

   JSONStringify($record_data)
   

   Das Schema enthält auch optionale Felder für Nachrichteneigenschaften wie contentType, correlationId und sessionId. Legen Sie diese fest, wenn nachgelagerte Consumer diese für Routing oder Filterung benötigen.

Teil 3: Nachrichten aus einer Warteschlange abrufen

Die Aktivität Get Queue Message ist eine Quellaktivität, die eine Warteschlange auf ausstehende Nachrichten abfragt. Studio verarbeitet jede abgerufene Nachricht durch eine Transformation und schreibt sie in das Ziel.

Entwurfsmuster

Schritt 1: Konfigurieren Sie die Aktivität „Get Queue Message"

1. Ziehen Sie auf dem Design-Canvas eine Aktivität Get Queue Message aus der Azure Service Bus-Verbindung auf den Canvas.

2. Name: Geben Sie einen aussagekräftigen Namen ein (z. B. Get Orders from Queue).

3. Warteschlange wählen: Wählen Sie den Warteschlangennamen aus, oder geben Sie ihn ein.

4. Empfangsmodus: Wählen Sie einen der folgenden Modi:

   • Peek Lock: Die Nachricht wird für einen konfigurierbaren Zeitraum gesperrt, während Studio sie verarbeitet. Die Nachricht bleibt in der Warteschlange, bis sie explizit gelöscht wird. Verwenden Sie diesen Modus, wenn zuverlässige Verarbeitung wichtig ist: Falls der Vorgang fehlschlägt, läuft die Sperre ab und die Nachricht wird wieder verfügbar.
   • Receive and Delete: Die Nachricht wird sofort aus der Warteschlange gelöscht, wenn sie abgerufen wird. Verwenden Sie diesen Modus nur, wenn Nachrichtenverlust bei Fehler akzeptabel ist.

5. Anzahl der Nachrichten: Geben Sie die Anzahl der Nachrichten ein, die pro Ausführung abgerufen werden sollen (1–100, Standard 1).

6. Wartezeit: Geben Sie die maximale Wartezeit in Sekunden ein, bis Nachrichten eintreffen, wenn die Warteschlange leer ist (Standard 10, Maximum 245).

7. Klicken Sie auf Weiter, überprüfen Sie das Antwortschema, und klicken Sie dann auf Fertig.

Schritt 2: Nachricht verarbeiten und löschen

Bei Verwendung des Modus Peek Lock müssen Nachrichten nach erfolgreicher Verarbeitung explizit gelöscht werden, um sie aus der Warteschlange zu entfernen. Fügen Sie einen Vorgang Delete Queue Message hinzu, der bei erfolgreicher Verarbeitung verkettet ist:

1. Erstellen Sie auf dem Design-Canvas einen zweiten Vorgang mit einer Aktivität Delete Queue Message.

2. Speichern Sie im Verarbeitungsvorgang der Aktivität Get Queue Message das Sperr-Token der Nachricht während der Transformation in einer globalen Variable:

   $lock_token = Source.lockToken;
   

3. Konfigurieren Sie die Aktivität Delete Queue Message mit demselben Warteschlangennamen, und ordnen Sie lock_token dem Anforderungsschema zum Löschen zu.

4. Konfigurieren Sie in den Einstellungen des Verarbeitungsvorgangs den Vorgang Delete Queue Message so, dass er Bei Erfolg ausgeführt wird.

Teil 4: Nachrichten aus einem Topic-Abonnement abrufen

Das Abrufen aus einem Topic-Abonnement folgt dem gleichen Muster wie das Abrufen aus Warteschlangen, erfordert aber die Auswahl sowohl eines Themas als auch eines Abonnements.

1. Ziehen Sie auf dem Design-Canvas eine Aktivität Get Topic Message aus der Azure Service Bus-Verbindung auf den Canvas.

2. Konfigurieren Sie die Aktivität auf die gleiche Weise wie Get Queue Message (siehe Teil 3), aber:

   • Wählen Sie einen Topic-Namen aus.
   • Wählen Sie nach der Auswahl des Themas ein Abonnement innerhalb dieses Themas aus.

3. Um verarbeitete Nachrichten zu löschen, verwenden Sie statt Delete Queue Message eine Aktivität Delete Topic Message, und wählen Sie das gleiche Thema und Abonnement aus.

Integration überprüfen

Senden: Führen Sie die Sendeoperation aus und überprüfen Sie im Azure-Portal, dass die Nachrichtenanzahl in der Warteschlange oder im Thema gestiegen ist. Verwenden Sie die Funktion Service Bus Explorer im Portal, um den Nachrichtentext und die Eigenschaften zu inspizieren.

Empfangen: Senden Sie eine Testnachricht an die Warteschlange oder das Thema mithilfe des Service Bus Explorers im Azure-Portal. Führen Sie die Operation Get Queue Message oder Get Topic Message aus und überprüfen Sie die Operationsprotokolle, um zu bestätigen, dass die Nachricht abgerufen wurde. Überprüfen Sie, dass das Ziel mit den erwarteten Daten geschrieben wurde. Bei Verwendung von Peek Lock bestätigen Sie, dass die Nachricht aus der Warteschlange gelöscht wurde, indem Sie die Nachrichtenanzahl im Portal überprüfen.

Wenn der Verbindungstest fehlschlägt, überprüfen Sie, dass der Service Principal oder die Shared Access Policy die Rolle Azure Service Bus Data Owner oder die entsprechenden Send/Listen-Rechte hat, wie in Voraussetzungen für Azure Service Bus beschrieben.