Beispiele für Implementierungscodes

Beispiel-Code-Snippets zur Unterstützung bei der Erstellung einer benutzerdefinierten Richtlinienimplementierung .

Notiz: Wenn Sie GatewayScript, Sie müssen den folgenden Befehl einfügen:

var apic = require(./apim.custom.js);

dabei steht apic für den allgemeinen Namen, der für die GatewayScript-Beispiele in diesem Thema verwendet wird. apic kann jedoch auch für einen beliebigen Namen stehen, z. B.:

var apim = require(./apim.custom.js);

in diesem Fall starten Sie Ihre Aufrufe anschließend mit apim.

Zugriff auf Codeausschnitt für Eingabeeigenschaften
Zugriff auf Codeausschnitt für den Laufzeitkontext
Zugriff auf Codeausschnitt für Eingabenutzdaten
Zugriff auf Codeausschnitt für HTTP-Header
Codeausschnitt für Nutzdaten ändern
Codeausschnitt für Fehlerinformationen konfigurieren
Variablen-Codeausschnitt festlegen

Zugriff auf Codeausschnitt für Eingabeeigenschaften

Der folgende Codeblock enthält ein Beispiel dafür, wie mithilfe der XSLT-Funktion policyProperties() auf die Eingabeeigenschaften zugegriffen werden kann. Im Beispiel wird eine Eigenschaft namens a_property definiert, die als Ganzzahlwert angegeben wird, aber in XSLT als Text abgerufen wird.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement"
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="p" select="apim:policyProperties()" />
    <xsl:message>
      The value of my input property is
      <xsl:value-of select="$p/a_property" />
      <apigw:set-variable name="'propfound'" value="'true'"/>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.getPolicyProperty(propertyName)

Dabei ist propertyName der Name der Eingabeeigenschaft, auf die Sie zugreifen möchten. Wenn kein Name für die Eingabeeigenschaft angegeben wird, werden bei der Aktion alle Eingabeeigenschaften zurückgegeben.

Zugriff auf Codeausschnitt für den Laufzeitkontext

Der folgende Codeblock enthält ein Beispiel dafür, wie mithilfe der XSLT-Funktion getContext() auf den Laufzeitkontext zugegriffen werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="client-id" select="apim:getContext('client.app.id')" />
    <xsl:message>
      The calling application is
      <xsl:value-of select="$client-id" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.getContext(varName)

Dabei ist varName der Name der Kontextvariablen, auf die Sie zugreifen möchten.

Eine vollständige Liste der Kontextvariablen finden Sie unter API Gateway -Kontextvariablen.

Zugriff auf Codeausschnitt für Eingabenutzdaten

Der folgende Codeblock enthält ein Beispiel dafür, wie mithilfe der XSLT-Funktion payloadRead() auf die Eingabenutzdaten zugegriffen werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="input" select="apim:payloadRead()" />
    <xsl:message>
      The input payload is
      <xsl:copy-of select="$input" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.readInput(callback)

Ein Callback ist erforderlich, weil die tatsächlichen Nutzdaten asynchron gelesen werden. Die Callback-Methode wird aufgerufen, wenn die Nutzdaten bereit sind.

Diese Funktion gibt eine XML-Knotengruppe zurück, die die Nutzdaten der Anforderung enthält. Wenn die Nutzdaten im JSON-Format vorliegen, wird eine JSONx-Knotengruppe zurückgegeben, die dann innerhalb eines XSLT- oder GatewayScript-Style-Sheets bearbeitet werden kann. Wenn die Nutzdaten nicht im JSON- oder XML-Format sind, ist die zurückgegebene Knotengruppe leer.

Im folgenden Beispiel wird gezeigt, wie die Funktion payloadType() verwendet werden kann, um zu bestimmen, welcher Typ von Nutzdaten (XML oder JSONx) von der XSLT-Funktion payloadRead() zurückgegeben wird.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="payloadType" select="apim:payloadType()" />
    <xsl:message>
      <xsl:text>Payload type is [</xsl:text>
      <xsl:value-of select="$payloadType" />
      <xsl:text>]</xsl:text>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Zugriff auf Codeausschnitt für HTTP-Header

Der folgende Codeblock enthält ein Beispiel dafür, wie mithilfe der Funktion getContext() auf die HTTP-Header in XSLT zugegriffen werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="content-type" select="apim:getContext('request.headers.content-type')" />
    <xsl:message>
      The request content type is
      <xsl:value-of select="$content-type" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.getContext(request.headers.headerName)

Dabei wird headerName dem Namen des Headers zugeordnet, auf den Sie zugreifen wollen.

Hinweis: Der Zugriff auf oder die Änderung von HTTP-Headern mithilfe von DataPower® -Erweiterungen wie dp:set-request-headerist nicht zu empfehlen, da solche Aktionen zu unerwarteten Ergebnissen führen können, wenn die Richtlinie mit anderen Richtlinien und Assembly-Schritten kombiniert wird.

Codeausschnitt für Nutzdaten ändern

Die Ausgabe einer benutzerdefinierten Richtlinie muss eine XML-Knotengruppe sein, die eine XML- oder SOAP- Nachricht oder eine JSON-Nachricht mit JSONx darstellt. Der folgende Codeblock enthält ein Beispiel dafür, wie die Nutzdaten in XSLT geändert werden können. Um das API- Gateway -Richtlinienframework beim Akzeptieren der neuen oder transformierten Nachricht zu unterstützen, rufen Sie die Vorlage apim-output auf, wie im folgenden Beispiel gezeigt.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:apim="http://www.ibm.com/apimanagement"
  xmlns:jsonx="http://www.ibm.com/xmlns/prod/2009/jsonx"
  exclude-result-prefixes="apim"
  extension-element-prefixes="apim">

  <!-- Contains the APIM functions -->
  <xsl:include href="local:///isp/policy/apim.custom.xsl" />

  <xsl:template match="/">
    <!-- Creates a JSON document (empty object is for simplicity) -->
    <jsonx:object>
    </jsonx:object>

    <!-- Indicates the media type of the output being produced -->

    <xsl:call-template name="apim:output">
      <xsl:with-param name="mediaType" select="'application/json'" />
    </xsl:call-template>
  </xsl:template>

</xsl:stylesheet>

Dabei gilt Folgendes: mediaType

'application/json' bedeutet, dass die Ausgabe im JSONx-Format geschrieben wird.
'application/xml' bedeutet, dass die Ausgabe im XML-Format geschrieben wird.

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.output(mediaType)

Dabei ist mediaType:

application/json bedeutet, dass die Ausgabe im JSONx-Format geschrieben wird.
application/xml bedeutet, dass die Ausgabe im XML-Format geschrieben wird.

Die Angabe des Datenträgertyps ermöglicht es den nächsten Schritten im Assembly-Ablauf zu verstehen, wie die neuen Nutzdaten zu verarbeiten sind.

Tipp: Die Ausgabe einer benutzerdefinierten Richtlinie muss XML oder JSONx sein. JSONx ist ein IBM Standardformat zur Darstellung von JSON als XML. Eine Möglichkeit, GatewayScript -JSON-Ausgabedaten in JSONx zu konvertieren, besteht darin, eine Convert Query Params to XML -Aktion hinzuzufügen, um der GatewayScript -Aktion innerhalb derselben Richtlinienregel zu folgen. Für die Aktion

Convert Query Params to
XML

muss Input Conversion mit

Default
Encoding

auf JSONgesetzt sein. Die Ausgabe der Aktion GatewayScript muss die Eingabe für die Aktion Convert Query Params to XML sein, damit JSONx erzeugt wird.

Codeausschnitt für Fehlerinformationen konfigurieren

Der folgende XSLT-Codeblock enthält ein Beispiel dafür, wie die Richtlinienimplementierung durch Aufrufen der Vorlage apim-error zum Ausgeben von Fehlerinformationen konfiguriert werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:apim="http://www.ibm.com/apimanagement"
  exclude-result-prefixes="apim"
  extension-element-prefixes="apim">

  <!-- Contains the APIM functions -->
  <xsl:include href="local:///isp/policy/apim.custom.xsl" />

  <!-- Indicates this policy has a failure and provides
       additional information for the client application -->
  <xsl:template match="/">
    <xsl:call-template name="apim:error">
      <xsl:with-param name="httpCode" select="'401'" />
      <xsl:with-param name="httpReasonPhrase" select="'Unauthorized'" />
      <xsl:with-param name="errorMessage" select="'Please select a Plan'" />
    </xsl:call-template>
  </xsl:template>

</xsl:stylesheet>

Dabei gilt:

httpCode ist der Code der erforderlichen Fehlernachricht.
httpReasonPhrase ist die Fehlerursache.
errorMessage ist die vorgeschlagene Aktion für den Benutzer.

Bei Verwendung von GatewayScript müssen Sie die folgende Schablone aufrufen:

apic.error(name, httpCode, httpReasonPhrase, message)

Dabei gilt:

name ist der Name des Fehlers.
httpCode ist der Code der erforderlichen Fehlernachricht.
httpReasonPhrase ist die Fehlerursache.
message ist die vorgeschlagene Aktion für den Benutzer.

Variablen-Codeausschnitt festlegen

Der folgende XSLT-Codeblock enthält ein Beispiel dafür, wie eine Laufzeitvariable durch Aufrufen der Schablone setVariable auf einen bestimmten Zeichenfolgewert gesetzt werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="" select="'https://endpoint.host.com/data'" />
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'serviceEndpoint'" />
      <xsl:with-param name="value" select="$targetUrl" />
      <xsl:with-param name="action" select="'set'" />
    </xsl:call-template>
    <xsl:message>
      <xsl:text>Variable [</xsl:text>
      <xsl:value-of select="'serviceEndpoint'" />
      <xsl:text>] = [</xsl:text>
      <xsl:value-of select="$targetUrl" />
      <xsl:text>]</xsl:text>
    </xsl:message>
    <dp:url-open target="{$targetUrl}" response="xml" http-method="get"/>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

Dabei gilt:

varName ist der Name der Laufzeitvariable, auf die Sie einen Wert setzen möchten.
value ist der Zeichenfolgewert, auf den Sie die Variable setzen möchten. Dabei kann es sich um einen Literalwert oder um eine andere Variable handeln. Um beispielsweise Ihre benannte Variable auf den Wert des Inhaltstyp-Headers (content-type) in einer Anforderung zu setzen, geben Sie für value Folgendes ein: $(request.headers.content-type).

Bei Verwendung von GatewayScript müssen Sie die folgende Schablone aufrufen:

apic.setvariable(varName, varValue, action)

Dabei gilt:

varName ist der Name der Laufzeitvariablen, auf die Sie einen Wert setzen oder die Sie hinzufügen oder löschen möchten.
varValue ist der Zeichenfolgewert, auf den Sie die Variable setzen möchten. Dabei kann es sich um einen Literalwert oder um eine andere Variable handeln. Um beispielsweise Ihre benannte Variable auf den Wert des Inhaltstyp-Headers (content-type) in einer Anforderung zu setzen, geben Sie für varValue Folgendes ein: request.headers.content-type. Diese Eigenschaft ist nur erforderlich, wenn als Aktion set oder add angegeben ist.
action ist die Aktion, die Sie auf die Variable anwenden möchten. Gültige Optionen sind:
- set
- add
- clear
Ist keine Option festgelegt, wird die Standardoption set angewendet.

Im folgenden XSLT-Beispiel wird gezeigt, wie mithilfe der Funktion getVariable() der Wert einer Laufzeitvariablen abgerufen werden kann.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="varValue" select="apim:getVariable('serviceEndpoint')" />
    <xsl:message>
      <xsl:text>Variable [</xsl:text>
      <xsl:value-of select="'serviceEndpoint'" />
      <xsl:text>] = [</xsl:text>
      <xsl:value-of select="$varValue" />
      <xsl:text>]</xsl:text>
    </xsl:message>
    <dp:url-open target="{$varValue}" response="xml" http-method="get"/>
  </xsl:template>

</xsl:stylesheet>

varValue ist der Name der Laufzeitvariable, für die Sie einen Wert abrufen möchten.

Bei Verwendung von GatewayScript müssen Sie die folgende Funktion aufrufen:

apic.getvariable(varName)

Dabei ist varName der Name der Laufzeitvariablen, für die ein Wert abgerufen werden soll.