Exemples de code d'implémentation

Exemples de fragments de code XSLT et GatewayScript.

Remarque : si vous utilisez GatewayScript,, vous devez inclure l'une ou l'autre des commandes suivantes, en fonction du type de votre passerelle :

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

où apic est le nom utilisé pour les exemples GatewayScript dans cette rubrique. Toutefois, vous pouvez remplacer apic par le nom de votre choix ; par exemple, vous pouvez utiliser :

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

et démarrer vos appels avec apim.

Fragment de code d'accès aux propriétés d'entrée
Fragment de code d'accès au contexte d'exécution
Accès au fragment de code de contenu d'entrée
Fragment de code d'accès aux en-têtes HTTP
Fragment de code de contenu
Fragment de code de configuration des informations d'erreur
Accès à l'exception interceptée dans un bloc catch
Fragment de code de définition de variables

Fragment de code d'accès aux propriétés d'entrée

Le bloc de code ci-après illustre l'accès aux propriétés d'entrée à l'aide de la fonction XSLT policyProperties(). L'exemple définit la propriété a_property déclarée comme valeur entière, mais extraite dans XSLT comme texte.

<?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"
  xmlns:apigw="http://www.ibm.com/xmlns/datapower/2017/11/apigateway"
  exclude-result-prefixes="dp func apim apigw"
  extension-element-prefixes="dp func apim apigw"> 

  <!-- 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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.getPolicyProperty(propertyName)

où propertyName est le nom de la propriété d'entrée à laquelle vous souhaitez accéder. S'il n'est pas indiqué, l'action renvoie toutes les propriétés d'entrée.

Fragment de code d'accès au contexte d'exécution

Le bloc de code ci-après illustre l'accès au contexte d'exécution à l'aide de la fonction XSLT getContext().

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.getContext(varName)

où varName est le nom de la variable contextuelle à laquelle vous souhaitez accéder.

Pour obtenir la liste complète des variables de contexte, consultez la page API Gateway context variables. Si vous utilisez le DataPower® API Gateway, consultez également la section « Utilisation des variables de contexte dans les politiques GatewayScript et XSLT » sur le site DataPower API Gateway.

Accès au fragment de code de contenu d'entrée

Le bloc de code ci-après illustre l'accès au contenu d'entrée à l'aide de la fonction XSLT payloadRead().

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.readInput(callback)

Un rappel est requis car la lecture du contenu réel est asynchrone. La méthode de rappel est appelée lorsque le contenu est prêt.

Cette fonction renvoie un ensemble de noeuds XML comportant le contenu de la demande. Si le contenu est au format JSON, un ensemble de noeuds JSONx, qui peut être manipulé dans une feuille de style XSLT ou GatewayScript, est renvoyé. Si le contenu n'est pas au format JSON ou XML, l'ensemble de noeuds renvoyé est vide.

L'exemple ci-dessous illustre l'utilisation de la fonction payloadType() pour déterminer le type de contenu (XML ou JSONx) qui sera renvoyé par la fonction XSLT payloadRead().

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

Fragment de code d'accès aux en-têtes HTTP

Le bloc de code ci-après explique comment accéder aux en-têtes HTTP dans XSLT en utilisant la fonction getContext().

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.getContext(request.headers.headerName)

où headerName correspond au nom de l'en-tête auquel vous souhaitez accéder.

Remarque : il est déconseillé d'accéder aux en-têtes de la stratégie « HTTP » ou de les modifier à l'aide d'extensions de la stratégie « DataPower », telles que dp:set-request-header, car de telles actions pourraient entraîner des résultats inattendus lorsque cette stratégie est combinée avec d'autres stratégies et étapes d'assemblage.

Fragment de code de contenu

La sortie d'une stratégie définie par l'utilisateur doit être un ensemble de noeuds XML, qui représente un message XML ou SOAP , ou un message JSON à l'aide de JSONx. Le bloc de code ci-après est un exemple de modification du contenu dans XSLT. Pour aider l'infrastructure de stratégie Passerelle d'API à accepter le message nouveau ou transformé, appelez le modèle apim-output , comme illustré dans l'exemple suivant.

<?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:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  <xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <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>

Où mediaType :

'application/json' est le moment où la sortie est écrite dans le format JSONx.
'application/xml' est le moment où la sortie est écrite dans le format XML.

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.output(mediaType)

Où mediaType est :

application/json est le moment où la sortie est écrite dans le format JSONx.
application/xml est le moment où la sortie est écrite dans le format XML.

La définition du type de support permet aux étapes suivantes dans le flux d'assemblage de savoir comment traiter le nouveau contenu.

Astuce: La sortie d'une stratégie définie par l'utilisateur doit être XML ou JSONx. JSONx est un format IBM standard représentant JSON sous forme de XML. L'une des manières de convertir des données JSON GatewayScript de sortie en JSONx consiste à ajouter une action Convert Query Params to XML qui suivra l'action GatewayScript dans la même règle conditionnelle. L'action

Convert Query Params to
XML

doit avoir un Input Conversion avec

Default
Encoding

défini sur JSON. La sortie de l'action GatewayScript doit correspondre à l'entrée de l'action Convert Query Params to XML pour que JSONx soit généré.

Fragment de code de configuration des informations d'erreur

Le bloc de code XSLT ci-après explique comment configurer l'implémentation de stratégie afin de générer des informations sur les erreurs en appelant le modèle apim-error.

<?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:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  <xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <!-- 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>

où :

httpCode est le code du message d'erreur requis.
httpReasonPhrase est la cause de l'erreur.
errorMessage est l'action suggérée à l'utilisateur.

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

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

où :

name est le nom de l'erreur.
httpCode est le code du message d'erreur requis.
httpReasonPhrase est la cause de l'erreur.
message est l'action suggérée à l'utilisateur.

Accès à l'exception interceptée dans un bloc catch

Le bloc de code XSLT ci-après explique comment obtenir, dans le bloc catch d'un assemblage d'API, les détails relatifs à l'exception interceptée. Une utilisation possible serait de créer une réponse d'erreur personnalisée à l'aide des détails de l'exception interceptée.

Pour « DataPower Gateway » (compatible avec v5 ) :

<?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:apim="http://www.ibm.com/apimanagement" 
  extension-element-prefixes="dp" 
  exclude-result-prefixes="dp apim">

  <xsl:output method="xml" />

  <!-- 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="exception" select="apim:getError()"/>
    <!-- output desired error message based on the exception -->
    <myError>
       <errorReason><xsl:value-of select="$exception/error/message"/></errorReason>
    </myError>

    <!-- Propagate the HTTP status code and reason phrase from the exception -->       
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.code'"/>
      <xsl:with-param name="value" select="$exception/error/status/code"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
              
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.reason'"/>
      <xsl:with-param name="value" select="$exception/error/status/reason"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
       
    </xsl:template>

</xsl:stylesheet>

Pour plus d' API Gateway s :

<?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:apim="http://www.ibm.com/apimanagement"
  xmlns:apigw="http://www.ibm.com/xmlns/datapower/2017/11/apigateway" 
  extension-element-prefixes="dp apim apigw" 
  exclude-result-prefixes="dp apim apigw">

  <xsl:output method="xml" />

  <!-- Contains the APIM functions -->
  <xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">

    <xsl:variable name="exception" select="apigw:get-error()"/>
    <!-- output desired error message based on the exception -->
    <myError>
       <errorReason><xsl:value-of select="$exception/error/message"/></errorReason>
    </myError>

    <!-- Propagate the HTTP status code and reason phrase from the exception -->       
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.code'"/>
      <xsl:with-param name="value" select="$exception/error/status/code"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
              
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.reason'"/>
      <xsl:with-param name="value" select="$exception/error/status/reason"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
       
    </xsl:template>

</xsl:stylesheet>

Les fonctions apim:getError() et apigw:get-error() renvoient un ensemble de noeuds XML ; par exemple :

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <name>RuntimeError</name>
    <message>This is a thrown Runtime Error</message>
    <policyTitle>Throw Runtime Error</policyTitle>
    <status>
        <code>500</code>
        <reason>Internal Server Error</reason>
    </status>
</error>

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apim.getError()

qui renvoie un objet JSON ; par exemple :

{
  "name": "OperationError",
  "message": "This is a thrown Operation Error",
  "policyTitle": "Throw Operation Error",
  "status": {
    "code": "500",
    "reason": "Internal Server Error"
  }
}

Fragment de code de définition de variables

Le bloc de code XSLT ci-après explique comment associer une variable d'exécution à une valeur de chaîne spécifiée en appelant le modèle setVariable.

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

où :

varName est le nom de la variable d'exécution à laquelle vous voulez affecter une valeur.
value est la valeur de chaîne que vous voulez affecter à la variable. Il peut s'agir d'une valeur littérale ou d'une autre variable. Par exemple, pour affecter à la variable nommée la valeur de l'en-tête Content-Type dans une demande, définissez value sous la forme $(request.headers.content-type).

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.setvariable(varName, varValue, action)

où :

varName est le nom de la variable d'exécution à laquelle vous souhaitez définir une valeur ou que vous souhaitez ajouter ou effacer.
varValue est la valeur de chaîne que vous voulez affecter à la variable. Il peut s'agir d'une valeur littérale ou d'une autre variable. Par exemple, pour affecter à la variable nommée la valeur de l'en-tête Content-Type dans une demande, définissez varValue sous la forme request.headers.content-type. Cette propriété n'est requise que si l'action spécifiée est set ou add.
action représente l'action à appliquer à la variable. Les options valides sont les suivantes :
- set
- add
- clear
Si aucune option n'est définie, l'option par défaut set est appliquée.

L'exemple XSLT ci-après explique comment extraire la valeur d'une variable d'exécution à l'aide de la fonction getVariable().

<?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:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API 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>

où

varValue est le nom de la variable d'exécution pour laquelle vous voulez extraire une valeur.

Si vous utilisez GatewayScript, vous devez appeler la fonction suivante :

apic.getvariable(varName)

où varName est le nom de la variable d'exécution pour laquelle vous souhaitez extraire une valeur.