Anleitung zum Zugriff auf den Nachrichtenkontext und -inhalt in WSO2 Enterprise Integrator

Der WSO2 Enterprise Integrator ist ein Enterprise Service Bus, mit dem Sie Nachrichten transformieren und vermitteln können, um Systeme zu verbinden. Ein wesentlicher Teil des Message-Flows durch den WSO2 EI ist der sogenannte Message Context oder Synapse Message Context. Dieser Nachrichtenkontext ist die Umgebung, in der die Nachrichten fließen, und wir können auf die Nachrichten zugreifen und sie natürlich auch manipulieren. Die Manipulation kann auf verschiedene Arten erfolgen. Wir werden uns die folgenden Möglichkeiten dazu ansehen:

1. Mit regelmäßiger Übertragung
2. Mit einem Skript-Mediator
3. Aus Java 

Regelmäßige Übermittlung

Übermittlung ermöglicht es uns, den Nachrichtenkontext zu ändern. In WSO2 können wir Mediatoren wie einen Payload-Factory-Mediator verwenden, der die Payload des Message-Bodys ersetzen wird. Wir werden uns später mit den Eigenschaften und anderen Möglichkeiten zur Manipulation des Nachrichtenkontexts beschäftigen.

Aus einem Skript-Mediator

Ein Skript-Mediator kann als Bestandteil der regulären Mediation betrachtet werden, da er zu den Standard-Mediatoren im Enterprise Integrator gehört. Allerdings ermöglicht er mehr Flexibilität durch die Unterstützung verschiedener Skriptsprachen wie JavaScript, Groovy und Ruby. 

Synapse nutzt das Apache Bean Scripting Framework für die Unterstützung von Skriptsprachen. Mit dem Skript-Mediator können Sie im entsprechenden Skript eine Funktion aufrufen. Über diese Funktionen ist es möglich, auf den Synapse-Nachrichtenkontext zuzugreifen, der in der Skriptvariablen mc vordefiniert ist. Bei der Variabel mc handelt es sich um einen ScriptMessageContext, der einen eingeschränkten Zugriff auf den MessageContext ermöglicht. Die Variable enthält die folgenden Methoden, auf die innerhalb des Skripts als mc.[methodName] zugegriffen werden kann, z. B. getPayloadXML(), das eine XML-Darstellung der SOAP Body-Payload abruft.

Das Arbeiten mit einem Skript-Mediator ist einfacher als mit einem in Java geschriebenen Klassen-Mediator, was unsere nächste Möglichkeit ist.

Aus Java 

Selbstverständlich haben wir auch von Java aus Kontrolle über den Message Context. WSO2-Produkte sind in Java geschrieben, sodass wir durch das Einbinden der richtigen Klassen, z. B. org.apache.synapse.MessageContext, auf den Message-Kontext zugreifen können. Da ein Custom- oder Class-Mediator erfordert, dass ein Jar zum Enterprise Integrator hinzugefügt wird und oft ein Neustart erforderlich ist, ist dies etwas komplizierter zu handhaben. Der Vorteil ist jedoch die Flexibilität und die detailliertere Manipulation der Nachricht und ihrer Verarbeitung. Es wird empfohlen, die Implementierung von Funktionen zu vermeiden, die möglicherweise in zukünftigen Versionen des Produkts nicht mehr unterstützt werden.

Fokus auf regelmäßige Übermittlung

Daher konzentrieren wir uns auf die reguläre Übermittlung und werden die Möglichkeiten beschreiben, die uns mit den out-of-the-box verfügbaren Funktionen zur Verfügung stehen. Dabei konzentrieren wir uns auf den Teil, in dem sich die Nachricht innerhalb der EI befindet und gehen nicht auf den Zu- oder Abfluss der Nachricht ein.

Manche Mediatoren sind inhaltsbewusst, d. h., sie greifen auf den Nachrichtenkontext zu oder manipulieren ihn. Weitere Mediatoren sind inhaltsunbewusst, wie z. B. der Sende-Mediator, der einfach das Senden der Nachricht signalisiert. Andere sind bedingt inhaltsbewusst/unbewusst. Ein <log/>-Mediator ist unaware, während ein <log level=“full“/> auf den Inhalt der Nachricht zugreift, um sie auf der Konsole anzuzeigen und daher content-aware ist. Die meisten Mediatoren sind (bedingt) content-aware, da Mediation und Transformation das Ziel sind. Worin besteht der Unterschied zwischen Nachrichteninhalt und Nachrichtenkontext? Der Unterschied von nur einem Buchstaben mag verwirrend sein. Der Message Context ist jedoch die Metadaten, die mit einer Nachricht übertragen werden. Der Inhalt steuert, wie sich die Transformations-Engine, Synapse, und das Transport-Framework, Axis2, verhalten. 

Der Nachrichteninhalt ist die eigentliche Nachricht, die vom Produkt empfangen, transformiert und versendet wird. Der Nachrichteninhalt wird auch als Message-Body bezeichnet. 

Eigenschaften

Wir konzentrieren uns auf das Festlegen von Eigenschaften und die Manipulation mit xpath-Variablen wie $body. Es gibt eine Reihe von Standardeigenschaften, die wir festlegen können. Diese sind: 

Synapse Nachrichtenkontext-Eigenschaften: Ermöglicht das Abrufen von Informationen über die Nachricht, z. B. Datum/Uhrzeit, zu der sie gesendet wurde, das Format der Nachricht und die Operation der Nachricht.

SOAP Headers: Provide information about the message, such as the To and From values. These values also appear in the list of Synapse Message Context Properties.

Generische Eigenschaften: Allow you to configure messages as they are processed by the ESB profile, such as marking a message as out-only (no response message will be expected). These are more about the management of the message.

HTTP-Transport-Eigenschaften: Allow you to configure how the HTTP transport processes messages, such as forcing a 202 HTTP response to the client so that it stops waiting for a response. These concern again the transport of the message.

Axis2-Eigenschaften: Allow you to configure the web services engine in the ESB profile, such as specifying how to cache JMS objects, setting the minimum and maximum threads for consuming messages, and forcing outgoing HTTP/S messages to use HTTP 1.0. These properties have to do with the web engine Axis2. 

Get-Property

Die Funktion get-property()ermöglicht es jedem in einer Konfiguration verwendeten XPath-Ausdruck, Informationen aus dem aktuellen Nachrichtenkontext nachzuschlagen. Mit Hilfe des Property-Mediators können Sie Eigenschaften aus dem Nachrichtenkontext, dem Nachrichteninhalt, dem Nachrichtenkopf, aber auch aus den Systemumgebungsvariablen und der Registry abrufen.

Hinweis: Es empfiehlt sich, Synapse XPath-Variablen zu verwenden, wenn diese für Ihren Bereich verfügbar sind. Der Einsatz der Synapse XPath-Variablen belastet die Ressourcen des Systems weniger. Wir werden sie später in den Shortcuts besprechen.

Die Syntax der Funktion hat das folgende Format:

• get-property(String propertyName)
• get-property(String scope, String propertyName)

Das Festlegen und Abrufen einer Eigenschaft (‚Test‘) sieht wie folgt aus:

<property name="Test" scope="default" type="STRING" value="sample value"/>
 <log level="custom">
   <property expression="get-property('Test')" name="Value via get-property"/>
</log>

Auf der Konsole ist dies die Ausgabe:

Anwendungsbereiche

Diese Funktion akzeptiert den Bereich als optionalen Parameter. Sie holt eine Nachrichteneigenschaft im angegebenen Bereich, der einer der folgenden sein kann.

Wenn Sie nur den Namen der Property ohne den Anwendungsbereich angeben, wird der Standard-Anwendungsbereich verwendet.

Shortcuts

Es gibt verschiedene so genannte Shortcuts, oder XPath-Variablen, wie WSO2 sie nennt, mit denen wir auf den Befehl „get-property synapse“ verzichten können. Es gibt einen Satz vordefinierter XPath-Variablen, mit denen Sie direkt auf Bereiche des Message Context oder Message Content schreiben können. Mit diesen XPath-Variablen werden Eigenschaften verschiedener Bereiche wie folgt abgerufen:

Ein Beispiel

Was kann man mit all diesen Informationen machen? Lassen Sie es uns anhand eines Beispiels erklären. 

Wir haben einen einfachen Proxy, der die folgende XML-Nachricht empfängt:

<VatNumbers xmlns="http://yenlo.com/blog">
  <VatNumber>
    <country>AT</country>
    <vat>U34275908</vat>
  </VatNumber>
  <VatNumber>
    <country>BE</country>
    <vat>98235273941</vat>
  </VatNumber>
  <VatNumber>
    <country>DE</country>
    <vat>432256432</vat>
  </VatNumber>
</VatNumbers>

Der Quellcode des Proxys ist übersichtlich und schlicht gehalten:

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="mcExample" startOnLoad="true" transports="http https"
  xmlns="http://ws.apache.org/ns/synapse"
  xmlns:ns="http://yenlo.com/blog">
  <target>
    <inSequence>
      <log level="custom">
        <property name="Value" expression="$body//ns:VatNumbers" /> <!-- #1 -->
      </log>
      <property name="Test" value="sample value"/>
      <log level="custom">
        <property name="Content Type via $trp" expression="$trp:Content-Type" /> <!-- #2 -->
        <property name="Value via get-property" expression="get-property('Test')" /> <!-- #3 -->
      </log>
      <foreach expression="$body//ns:VatNumber">
        <sequence>
          <log level="custom">
            <property name="Country" expression="$body//ns:country" />
          </log>
        </sequence>
      </foreach>
      <respond/>
    </inSequence>
  </target>
</proxy>

In Zeile 1 wird auf den Nachrichtentext zugegriffen und alle VatNumbers-Elemente in der Nachricht referenziert.

In Zeile #2 greifen wir auf einen Transport-Header zu, genauer gesagt auf den HTTP Content-Type, und protokollieren ihn.

In Zeile #3 greifen wir mit der Funktion get-property auf den Wert der Eigenschaft Test zu.

Im foreach-Vermittler wird gezeigt, dass $body je nach Situation, in der er verwendet wird, auf andere Teile des Nachrichtentextes verweist.

Wenn wir nun die Nachricht an den Proxy senden und uns das wso2carbon.log ansehen, sehen wir diese Message Context-Beispiele in Aktion (zur besseren Lesbarkeit bereinigt):

Value = <VatNumbers xmlns=“http://yenlo.com/blog“><VatNumber><country>AT</country><vat>U34275908</vat></VatNumber><VatNumber><country>BE</country><vat>98235273941</vat></VatNumber><VatNumber><country>DE</country><vat>432256432</vat></VatNumber></VatNumbers>, Content Type via $trp = text/xml; charset=UTF-8,

Value via get-property = sample value
[2021-04-21 11:43:35,196]  INFO {org.apache.synapse.mediators.builtin.LogMediator} – Country = AT
[2021-04-21 11:43:35,196]  INFO {org.apache.synapse.mediators.builtin.LogMediator} – Country = BE
[2021-04-21 11:43:35,197]  INFO {org.apache.synapse.mediators.builtin.LogMediator} – Country = DE

In den drei letzten Log-Zeilen sehen wir, dass $body nun ein VatNumber-Element referenziert, da foreach jedes dieser Elemente in einer Schleife durchläuft.  

Schlussfolgerung

Dieser Blog erklärt, wie Sie den Message-Kontext und den Message-Inhalt manipulieren können. Mit WSO2 Enterprise Integrator werden Mediatoren bereitgestellt, die verwendet werden können, um sowohl den Message-Kontext als auch den Message-Inhalt zu manipulieren, aber auch eigene Mediatoren können entwickelt werden, falls die bereitgestellten Mediatoren nicht ausreichend sind.

Es gibt unterschiedliche Möglichkeiten, auf Teile des Message-Kontexts und des Message-Inhalts zuzugreifen, und es gibt mehrere XPath-Variablen, um dies zu tun. Einige von ihnen werden in einem Beispiel-Proxy demonstriert.

Mit den im Enterprise Integrator definierten $-Variablen ist der Zugriff auf den Message-Kontext einfach. So können wir schnell Informationen abrufen, zum Beispiel im Body der Message. Viel Spaß beim Integrieren!