SOAPMessageValidation-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur Apigee X-Dokumentation.
Weitere Informationen

Die SOAPMessageValidation-Richtlinie führt Folgendes aus:

  • Validiert alle XML-Nachrichten anhand ihrer XSD-Schemas
  • Überprüft SOAP-Nachrichten anhand einer WSDL-Definition
  • Bestimmt die Wohlgeformtheit von JSON- und XML-Nachrichten
<ph type="x-smartling-placeholder">

Diese Richtlinie lautet in der UI "SOAPMessageValidation" und validiert mehr als nur SOAP-Nachrichten. In diesem Abschnitt wird die Richtlinie als "MessageValidation-Richtlinie" bezeichnet.

Element <MessageValidation>

Definiert die MessageValidation-Richtlinie.

Standardwert Siehe Standardrichtlinie Tab unten
Erforderlich? Optional
Typ Komplexes Objekt
Übergeordnetes Element
Untergeordnete Elemente <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

Syntax

Das <MessageValidation>-Element verwendet die folgende Syntax:

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

Standardrichtlinie

Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie eine Richtlinie für die Nachrichtenüberprüfung hinzufügen zu Ihrem Ablauf in der Edge-Benutzeroberfläche hinzufügen:

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name Erforderlich

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

continueOnError falsch Optional Ist das Element auf "false" gesetzt, wird ein Fehler zurückgegeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Ist das Element auf "true" gesetzt, wird die Ausführung des Ablaufs auch nach dem Fehlschlagen einer Richtlinie fortgesetzt.
enabled wahr Optional Auf "true" setzen, um die Richtlinie durchzusetzen. Auf "false" setzen, um die Richtlinie zu "deaktivieren". Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   falsch Eingestellte Funktionen Dieses Attribut wurde verworfen.

Beispiele

Die folgenden Beispiele zeigen einige Möglichkeiten, wie Sie die MessageValidation-Richtlinie verwenden können:

1: XSD-Validierung

Sie können die MessageValidation-Richtlinie verwenden, um die Nutzlast einer XML-Nachrichtenanfrage mit einem XSD-Schema zu validieren.

  1. Erstellen Sie eine neue XSD-Ressourcendatei. Für Beispiel, "note-schema.xsd":
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="note">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="to" type="xs:string"/>
            <xs:element name="from" type="xs:string"/>
            <xs:element name="heading" type="xs:string"/>
            <xs:element name="body" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  2. Fügen Sie die MessageValidation-Richtlinie von SOAP dem Pre-Flow Ihres Proxy-Endpunkts hinzu:
    1. Geben Sie den Speicherort Ihrer XSD-Ressourcendatei mit dem Element <ResourceURL> an. Hier einige Beispiele:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Entfernen Sie die Elemente <SOAPMessage>, <Element> anhand der Richtliniendefinition.

    Ihre Richtliniendefinition sollte so aussehen:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. Senden Sie eine POST-Anfrage mit Ihrer XML-Datei als Nachricht an Ihren API-Proxy Nutzlast, wie das folgende Beispiel zeigt:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<note>
      <to>Fred Rogers</to>
      <from>Nick Danger</from>
      <heading>Greetings from my neighborhood</heading>
      <body>Just writing to say hello.</body>
    </note>'

    Beachten Sie, dass der Header Content-type auf "application/xml" gesetzt ist.

    Sie können auch eine Datendatei für die Nutzlast erstellen und mit einem Befehl wie diesem referenzieren:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

Sie sollten eine HTTP 200-Antwort erhalten. Je nach Zielendpunkt erhalten Sie möglicherweise weitere Details zur Anfrage. Wenn Sie zum Beispiel http://httpbin.org/post als Zielendpunkt verwenden und eine -v-Ausgabe (ausführlich) angeben, sollte die Antwort in etwa so aussehen:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

Fügen Sie ein anderes Tag in den Text Ihrer Anfrage ein, um zu prüfen, ob die XSD-Validierung funktioniert. Beispiel:

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

Sie sollten einen Validierungsfehler erhalten.

2. SOAP-Validierung

Sie können die MessageValidation-Richtlinie zum Validieren der Nutzlast einer SOAP-Nachrichtenanfrage anhand einer WSDL verwenden.

<ph type="x-smartling-placeholder">
  1. Erstellen Sie eine neue WSDL-Ressourcendatei. Zum Beispiel "example-wsdl.wsdl":
  2. Fügen Sie die MessageValidation-Richtlinie von SOAP dem Pre-Flow Ihres Proxy-Endpunkts hinzu:
    1. Setzen Sie das Attribut version des Elements <SOAPMessage> auf die Version des SOAP-Protokolls, das Sie zur Validierung verwenden möchten. Beispiel: "1,1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. Legen Sie den Wert des Elements <Element> auf das Element fest, das Sie verwenden möchten. Validieren:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element> gibt das erste untergeordnete Element unter <Body> im Envelope der SOAP-Anfrage an.

      Setzen Sie das Attribut namespace auf den Namespace für dieses untergeordnete Element.

    3. Geben Sie den Speicherort Ihrer WSDL-Ressourcendatei mit dem Element <ResourceURL> an. Hier einige Beispiele:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    Ihre Richtliniendefinition sollte so aussehen:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateSOAPRequest">
      <DisplayName>My SOAP Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <SOAPMessage version="1.1"/>
      <Element namespace="https://example.com/gateway">getID</Element>
      <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
    </MessageValidation>
  3. Senden Sie eine POST-Anfrage mit dem SOAP-Umschlag als wie im folgenden Beispiel gezeigt:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
      <soapenv:Header/>
      <soapenv:Body>
        <prox:getID>
          <typ:MyType>
            <typ:ID>42</typ:ID>
          </typ:MyType>
        </prox:getID>
      </soapenv:Body>
    </soapenv:Envelope>'

    Beachten Sie, dass der Header Content-type auf "application/xml" gesetzt ist.

    Sie können auch eine Datendatei für die Nutzlast erstellen und mit einem Befehl wie diesem referenzieren:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

Sie sollten eine HTTP 200-Antwort erhalten. Je nach Zielendpunkt erhalten Sie möglicherweise weitere Details zur Anfrage. Wenn Sie beispielsweise http://httpbin.org/post als Zielendpunkt verwenden, sollte die Antwort in etwa so aussehen:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: Wohlgeformtes XML/JSON

Mit der MessageValidation-Richtlinie können Sie überprüfen, ob die Nutzlast einer JSON- oder XML-Nachricht wohlgeformt ist (nicht dasselbe wie Validierung). Die Richtlinie stellt sicher, dass die Struktur und der Inhalt anerkannten Standards entsprechen, einschließlich:

  • Es gibt ein einziges Stammelement.
  • Der Inhalt enthält keine unzulässigen Zeichen.
  • Objekte und Tags sind ordnungsgemäß verschachtelt.
  • Start- und End-Tags stimmen überein.

So prüfen Sie eine wohlgeformte XML- oder JSON-Nutzlast:

  1. Fügen Sie die MessageValidation-Richtlinie von SOAP dem Pre-Flow Ihres Proxy-Endpunkts hinzu.
  2. Entfernen Sie die Elemente <ResourceURL>, <SOAPMessage> und <Element> anhand der Richtliniendefinition.

    Ihre Richtliniendefinition sollte so aussehen:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. Senden Sie eine POST-Anfrage an Ihren API-Proxy, wie das folgende Beispiel zeigt:
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
      -d '{
    "note": {
      "to": "Fred Rogers",
      "from": "Nick Danger",
      "header": "Greetings from my neighborhood",
      "body": "Just writing to say hello."
      }
    }'

    Beachten Sie, dass der Header Content-type auf "application/json" gesetzt ist.

    Um eine XML-Datei auf Wohlgeformtheit zu überprüfen, verwenden Sie XML als Nachrichtennutzlast und Legen Sie Content-type auf „application/xml“ fest.

Sie sollten eine HTTP 200-Antwort erhalten. Wenn Sie eine Nachrichtennutzlast senden, die kein korrekt formatiertes XML- oder JSON-Format enthält, sollten Sie den Fehler steps.messagevalidation.Failed erhalten.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <MessageValidation> beschrieben.

<DisplayName>

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert
Erforderlich/Optional? Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ String
Übergeordnetes Element <PolicyElement>
Untergeordnete Elemente

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Beispiel

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<Element>

Gibt das zu validierende Element in der Nachricht an. Dies ist das erste untergeordnete Element unter <Body> im Envelope der SOAP-Anfrage.

Standardwert sampleObject
Erforderlich? Optional
Typ String
Übergeordnetes Element <MessageValidation>
Untergeordnete Elemente

Das <Element>-Element verwendet die folgende Syntax:

Syntax

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

Beispiel 1

Im folgenden Beispiel wird ein einzelnes zu validierendes Element definiert:

...
<Element namespace="https://example.com/gateway">getID</Element>
...

Beispiel 2

Sie können mehrere Elemente für die Überprüfung angeben, indem Sie mehrere <Element>-Elemente hinzufügen:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

Das <Element>-Element hat die folgenden Attribute:

Attribut Standardeinstellung Erforderlich? Beschreibung
namespace "http://sample.com" Optional Definiert den Namespace des zu validierenden Elements.

<ResourceURL>

Gibt das XSD-Schema oder die WSDL-Definition an, die zur Validierung der Quellnachricht verwendet werden soll.

Standardwert wsdl://display_name.wsdl
Erforderlich? Optional
Typ String
Übergeordnetes Element <MessageValidation>
Untergeordnete Elemente

Das <ResourceURL>-Element verwendet die folgende Syntax:

Syntax

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

Beispiele

Für eine XML-Datei:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

Für eine WSDL-Datei:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

Der Wert von <ResourceURL> muss auf eine Ressourcendatei in Ihrem API-Proxy verweisen. Er kann nicht über HTTP oder HTTPS auf externe Ressourcen verweisen.

Wenn Sie für <ResourceURL> keinen Wert angeben, wird die Nachricht auf wohlgeformte JSON geprüft. oder XML, wenn der Content-type-Header „application/json“ ist oder "application/xml" enthalten, .

Das <ResourceURL>-Element hat keine untergeordneten Elemente oder Attribute.

XSDs zur Validierung verwenden

Wenn die XML-Nutzlast, die Sie mit der MessageValidation-Richtlinie validieren, auf ein anderes Schema verweist, müssen Sie der enthaltenen XSD-Datei im Attribut schemaLocation das Präfix xsd voranstellen.

Das folgende Beispielschema besteht aus mehreren XSD-Dateien:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

WSDLs zur Validierung verwenden

Eine WSDL-Datei muss mindestens ein Schema definieren. Wenn nicht mindestens ein Schema referenziert wird, Richtlinie für die Nachrichtenüberprüfung schlägt fehl.

Die maximale Importtiefe für ein Schema beträgt 10. Wenn Sie diese Anzahl von verschachtelten Importen überschreiten, Richtlinie für die Nachrichtenüberprüfung schlägt fehl.

<SOAPMessage>

Definiert die SOAP-Version, die zur Validierung der MessageValidation-Richtlinie verwendet wird.

Standardwert
Erforderlich? Optional
Typ
Übergeordnetes Element <MessageValidation>
Untergeordnete Elemente

Das <SOAPMessage>-Element verwendet die folgende Syntax:

Syntax

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

Beispiel

...
<SOAPMessage version="1.1"/>
...

Das <SOAPMessage>-Element hat die folgenden Attribute:

Attribut Standardeinstellung Erforderlich? Beschreibung
version Optional Die SOAP-Version, die von dieser Richtlinie zum Validieren der SOAP-Nachrichten verwendet wird.

Gültige Werte sind:

  • "1.1"
  • "1.2"
  • "1.1/1.2"

Weitere Informationen finden Sie unter Von SOAP/1.1 zu SOAP-Version 1.2 in 9 Punkten.

<Source>

Gibt die zu validierende Quellnachricht an. Der Wert dieses Elements ist der Name der Nachricht, die Sie überprüfen möchten.

Wenn Sie <Source> nicht festlegen, wird diese Richtlinie standardmäßig auf "Nachricht" gesetzt. Dies bezieht sich auf die gesamte Anfragenachricht (in einem Anfrageablauf) oder auf die Antwortnachricht (in einem Antwortablauf), einschließlich der Nutzlast. Sie können die Richtlinie auch explizit auf "Anfrage" oder "Antwort" setzen, um auf die Anfrage oder Antwort zu verweisen.

Standardwert Anfrage
Erforderlich? Optional
Typ String
Übergeordnetes Element <MessageValidation>
Untergeordnete Elemente

Das <Source>-Element verwendet die folgende Syntax:

Syntax

...
  <Source>message_to_validate</Source>
...

Beispiel

...
<Source>request</Source>
...

Neben „Nachricht“, „Anfrage“ und „Antwort“ können Sie den Wert <Source> an den Namen einer beliebigen Nachricht in Ihrem Ablauf. In diesem Fall müssen Sie jedoch vor dem Ausführen dieser Richtlinie eine benutzerdefinierte Nachricht mit diesem Namen erstellen. Andernfalls erhalten Sie eine Fehlermeldung.

Wenn der Wert von <Source> nicht im Nachrichtenfluss aufgelöst werden kann oder in einen Nicht-Nachrichtentyp aufgelöst wird, tritt einer der folgenden Fälle ein:

  • Wenn ein Nullwert:Edge wirft eine steps.messagevalidation.SourceMessageNotAvailable Fehler.
  • Wenn ein Nicht-Nachrichtentyp: Edge wirft eine steps.messagevalidation.NonMessageVariable Fehler.

Das <Source>-Element hat keine Attribute oder untergeordneten Elemente.

Fehlercodes

Von Edge-Richtlinien zurückgegebene Fehler haben ein konsistentes Format, wie in der Fehlercode-Referenz beschrieben.

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Problembehebung
steps.messagevalidation.SourceMessageNotAvailable 500

Dieser Fehler tritt bei einer Variablen auf, die im Element <Source> der Richtlinie angegeben ist:

  • Der Wert liegt außerhalb des Bereichs (ist nicht in dem spezifischen Ablauf verfügbar, in dem die Richtlinie ausgeführt wird)
  • oder
  • Der Wert nicht aufgelöst werden kann (nicht definiert ist)
steps.messagevalidation.NonMessageVariable 500

Dieser Fehler tritt auf, wenn für das Element <Source> in der SOAPMessageValidation-Richtlinie eine Variable festgelegt ist, die nicht vom Typ message ist.

Nachrichtentypvariablen stellen ganze HTTP-Anfragen und -Antworten dar. Die integrierten Edge-Flussvariablen request, response und message sind vom Typ „Nachricht“. Weitere Informationen zu Nachrichtenvariablen finden Sie in der Variablenreferenz.

steps.messagevalidation.Failed 500 Dieser Fehler tritt auf, wenn die SOAPMessageValidation-Richtlinie die Eingabe-Nachrichten-Nutzlast nicht gegen das XSD-Schema oder die WSDL-Definition validiert. Sie wird auch angezeigt, wenn die Nutzlastnachricht fehlerhaft formatierte JSON- oder XML-Daten enthält.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.

Fehlername Ursache Korrigieren
InvalidResourceType Das Element <ResourceURL> in der SOAPMessageValidation-Richtlinie ist auf einen Ressourcentyp festgelegt, der von der Richtlinie nicht unterstützt wird.
ResourceCompileFailed Das Ressourcenskript, auf das im <ResourceURL>-Element der SOAPMessageValidation-Richtlinie verwiesen wird, enthält einen Fehler, der die Kompilierung verhindert.
RootElementNameUnspecified Das Element <Element> in der SOAPMessageValidation-Richtlinie enthält nicht den Namen des Stammelements.
InvalidRootElementName Das Element <Element> in der SOAPMessageValidation-Richtlinie enthält einen Stammelementnamen, der nicht den XML-Regeln für gültige Elementnamen entspricht.

Schemas

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Weitere Informationen