XSLTransform-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Die XSLTransform-Richtlinie wendet benutzerdefinierte Extensible Stylesheet Language-Transformationen (XSLT) auf XML-Nachrichten an. Damit können sie von XML in ein anderes Format wie XML, HTML oder Nur-Text umgewandelt werden. Die Richtlinie wird häufig verwendet, um Anwendungen zu integrieren, die XML unterstützen, aber für dieselben Daten unterschiedliche XML-basierte Formate erfordern.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Eingaben

Die XSL-Richtlinie übernimmt die folgenden Eingaben:

  • (Erforderlich) Der Name eines XSLT-Stylesheets, das eine Reihe von Transformationsregeln enthält, die im API-Proxy unter /resources/xsl gespeichert sind.
  • (Erforderlich) Die zu transformierende XML-Datei (in der Regel eine Anfrage oder Antwortnachricht).
  • (Optional) Der Name einer Variablen, in der die Ausgabe gespeichert wird.
  • (Optional) Parameter, die mit Parametern im XSL-Stylesheet übereinstimmen.

Parsing-Prozessor

Apigee stützt sich auf den Saxon XSLT-Prozessor und unterstützt XSLT 1.0 und 2.0.

Nicht unterstützte XSL-Elemente

Die XSL-Richtlinie unterstützt die folgenden XSL-Elemente nicht:

  • <xsl:include>
  • <xsl:import>

Beispiele

Die folgenden Beispiele zeigen einen XSL-Transformationsablauf:

XSL-Richtlinie -->

<XSL name="TransformXML">
  <ResourceURL>xsl://my_transform.xsl</ResourceURL>
  <Source>request</Source>
</XSL>

Einfache XSL-Richtlinie. Im nächsten Beispiel wird das in der Richtlinie referenzierte XSLT-Stylesheet angezeigt (my_transform.xsl). Das Element <Source> ist wichtig. Wenn beispielsweise die XML-Datei, die Sie transformieren möchten, in der Antwort enthalten ist, wird die Transformation nur ausgeführt, wenn Sie <Source> auf response setzen und die Richtlinie an den Antwortablauf angehängt ist. In diesem Fall befindet sich die zu transformierende XML jedoch in der Anfrage.

XSLT-Stylesheet -->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
    <xsl:text></xsl:text>
  </xsl:variable>
  <xsl:template match="/">
  <xsl:text>&lt;Life&gt;</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:text>Here are the odd-numbered items from the list:</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:for-each select="list/listitem">
      <xsl:if test="(position() mod 2) = 1">
        <xsl:number format="1. "/>
        <xsl:value-of select="."/>
        <xsl:value-of select="$newline"/>
      </xsl:if>
    </xsl:for-each>
  <xsl:text>&lt;/Life&gt;</xsl:text>
</xsl:template>
</xsl:stylesheet>

Das Stylesheet my_transform.xsl, auf das in der Richtlinie verwiesen wird. Rufen Sie das nächste Beispiel auf, um ein Beispiel für eine eingehende XML-Nachricht zu sehen.

Nachricht -->

<?xml version="1.0"?>
<list>
  <title>A few of my favorite albums</title>
  <listitem>A Love Supreme</listitem>
  <listitem>Beat Crazy</listitem>
  <listitem>Here Come the Warm Jets</listitem>
  <listitem>Kind of Blue</listitem>
  <listitem>London Calling</listitem>
  <listitem>Remain in Light</listitem>
  <listitem>The Joshua Tree</listitem>
  <listitem>The Indestructible Beat of Soweto</listitem>
</list>

Beispielnachricht in der Anfrage (in Beispiel 1 im Element <Source>request</Source> der Richtlinie angegeben).

Transformierte Nachricht

<Life>
Here are the odd-numbered items from the list:
1. A Love Supreme
3. Here Come the Warm Jets
5. London Calling
7. The Joshua Tree
</Life>

Die transformierte Nachricht nach dem XSLT-Stylesheet aus diesen Beispielen wird auf die XML-Nachricht angewendet.

Element <XSL>

Definiert eine XSLTransform-Richtlinie.

Standardwert –
Erforderlich? Erforderlich
Typ Komplexes Objekt
Übergeordnetes Element –
Untergeordnete Elemente <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

Das <XSL>-Element hat die folgenden Attribute:

Attribut Beschreibung Erforderlich? Typ
name Name der Richtlinie. Folgende Zeichen sind im Namen zulässig: A-Z0-9._\-$ %. Die Apigee-Benutzeroberfläche erzwingt jedoch zusätzliche Einschränkungen, z. B. das automatische Entfernen nicht alphanumerischer Zeichen. Erforderlich String

Verweis auf untergeordnetes Element

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

<OutputVariable>

Eine Variable, die die Ausgabe der Transformation speichert. Sie sollten dieses Element als benutzerdefinierte Variable festlegen und dann diese Variable nutzen.

Standardwert –
Erforderlich? Optional
Typ String
Übergeordnetes Element <XSL>
Untergeordnete Elemente Keine

Der Wert von <OutputVariable> darf nicht vom Typ Nachricht sein. Das heißt, er darf nicht message, request oder response sein.

Um den Nachrichteninhalt durch die Ausgabe der Transformation zu ersetzen, löschen Sie dieses Element. Wenn Sie beispielsweise eine Nachricht in HTML umwandeln, fügen Sie dieses Element nicht ein.

<Parameters>

In Ihren Stylesheets wird das Element <xsl:param> unterstützt. Sie definieren jeden Parameter als untergeordnetes <Parameter>-Element dieses Elements.

Standardwert –
Erforderlich? Optional
Typ Array von <Parameter>-Elementen
Übergeordnetes Element <XSL>
Untergeordnete Elemente <Parameter>

Das <Parameters>-Element hat die folgenden Attribute:

Attribut Beschreibung Erforderlich? Typ
ignoreUnresolvedVariables Ermittelt, ob die Richtlinie alle Fehler bzgl. nicht aufgelöster Variablen in den Anweisungen des XSLT-Skripts ignoriert. Der Standardwert ist false. Das bedeutet, dass die Richtlinie standardmäßig Fehler ausgibt, wenn nicht aufgelöste Variablen gefunden werden. Optional Boolesch

<Parameter>

Definiert einen Parameter im Element <Parameters>.

Standardwert –
Erforderlich? Optional
Typ Komplexes Objekt
Übergeordnetes Element <Parameters>
Untergeordnete Elemente Keine

Das <Parameter>-Element hat die folgenden Attribute:

Attribut Erforderlich? Typ Beschreibung
name Erforderlich String

Name des Parameters. Apigee vergleicht den hier festgelegten Wert mit dem Wert des Attributs name für ein <xsl:param>-Element im Stylesheet.

Wenn Sie beispielsweise den Namen uid eingeben, kann Ihr XSL-Code etwa so aussehen: 

<xsl:param name="uid" select="''"/>
ref Optional String

Verweist auf eine Kontextvariable, die den Wert für den Parameter enthält. Werte für die Kontextvariablen ref müssen vor der Auswertung dieser Richtlinie festgelegt werden.

Wenn ein uid-Parameter beispielsweise den Wert aus einer Variablen namens authn.uid abrufen muss, sieht das Element <Parameter> so aus:

<Parameter name="uid" ref="authn.uid"/>

Wenn Sie dieses Attribut verwenden, verwenden Sie nicht das Attribut value.
value Optional String

Gibt einen hartcodierten Wert für den Parameter an. Beispiel: Ein Parameter mit dem Namen answer sollte den Wert 42 haben. Das Element <Parameter> würde dann so aussehen:

<Parameter name="answer" value="42"/>

Wenn Sie dieses Attribut verwenden, verwenden Sie nicht das Attribut ref.

Der Parameter erhält seinen Wert entweder aus dem Attribut ref oder mit einem expliziten value.

Ein Beispiel und weitere Informationen finden Sie unter Wie sollten die optionalen Parameter der XSL-Transformationsrichtlinie verwendet werden?.

<ResourceURL>

Die XSL-Datei, die Apigee für die Transformation der Nachricht verwendet. Der Wert dieses Elements ist der Name des XSL-Stylesheets, das im API-Proxy unter /resources/xsl gespeichert ist.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <XSL>
Untergeordnete Elemente Keine

Beispiel:

<ResourceURL>xsl://SubscriberNumbers-Request.xsl</ResourceURL>

Weitere Informationen finden Sie unter Ressourcendateien.

<Source>

Gibt die Nachricht an, die transformiert wird. Normalerweise ist dieser Wert auf request oder response gesetzt, je nachdem, ob die transformierte Nachricht eingehend oder ausgehend ist.

Standardwert –
Erforderlich? Optional
Typ String
Übergeordnetes Element <XSL>
Untergeordnete Elemente Keine

Die XSL-Datei, die die Transformation definiert, wird durch <ResourceURL> definiert.

  • Wenn die Quelle fehlt, wird sie als einfache Nachricht behandelt. Beispiel: <Source>message</Source>
  • Wenn die Quellvariable nicht aufgelöst werden kann oder in einen Nicht-Nachrichtentyp aufgelöst wird, schlägt der Transformationsschritt fehl.

Fehlerreferenz

Laufzeitfehler

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

Fehlercode HTTP-Status Ursache Beheben
steps.xsl.XSLSourceMessageNotAvailable 500 Dieser Fehler tritt auf, wenn die Nachricht oder Stringvariable, die im <Source>-Element der Richtlinie XSLTransform angegeben ist, entweder außerhalb des zulässigen Bereichs ist (nicht im spezifischen Ablauf, in dem die Richtlinie ausgeführt wird) oder nicht aufgelöst werden kann (ist nicht definiert).
steps.xsl.XSLEvaluationFailed 500 Dieser Fehler tritt auf, wenn die XML-Eingabenutzlast nicht verfügbar/fehlerhaft ist oder die XSLTransform-Richtlinie fehlschlägt/die XML-Eingabedatei nicht auf Basis der in der XSL-Datei bereitgestellten Transformationsregeln transformieren kann. Es sind viele verschiedene Gründe dafür denkbar, dass die XSLTransform-Richtlinie fehlschlägt. Der in der Fehlermeldung angegebene Fehlerursache enthält weitere Informationen zum Grund.

Bereitstellungsfehler

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

Fehlername Ursache Beheben
XSLEmptyResourceUrl Wenn das Element <ResourceURL> in der Richtlinie XSLTransform leer ist, schlägt die Bereitstellung des API-Proxys fehl.
XSLInvalidResourceType Wenn der im <ResourceURL>-Element der XSLTransform-Richtlinie angegebene Ressourcentyp nicht dem Typ xsl ist, schlägt die Bereitstellung des API-Proxys fehl.

Weitere Informationen