Ejemplos de código de implementación

Fragmentos de código de XSLT y GatewayScript de ejemplo.

Nota: Si utilizas GatewayScript,, debes incluir uno de los siguientes comandos, dependiendo del tipo de puerta de enlace que tengas:

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

donde apic es el nombre común utilizado para los ejemplos de GatewayScript en este tema. Sin embargo, apic podría ser cualquier nombre de su elección, por ejemplo podría utilizar:

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

y entonces iniciaría las llamadas con apim.

Acceder al fragmento de código de propiedades de entrada
Acceder al fragmento de código de contexto de tiempo de ejecución
Acceder al fragmento de código de carga útil de entrada
Acceder al fragmento de código de cabeceras HTTP
Modificar el fragmento de código de carga útil
Configurar el fragmento de código de información de error
Acceso a la excepción interceptada en un bloque catch
Establecer fragmento de código de variables

Acceder al fragmento de código de propiedades de entrada

El bloque de código siguiente muestra un ejemplo de cómo acceder a las propiedades de entrada utilizando la función XSLT policyProperties(). El ejemplo define una propiedad denominada a_property, que se declara como un valor entero, pero se recupera en XSLT como texto.

<?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 está utilizando GatewayScript, llame a la función siguiente:

apic.getPolicyProperty(propertyName)

donde propertyName es el nombre de la propiedad de entrada a la que desea acceder. Si el nombre de propiedad de entrada está vacío, la acción devolverá todas las propiedades de entrada.

Acceder al fragmento de código de contexto de tiempo de ejecución

El bloque de código siguiente muestra un ejemplo de cómo acceder al contexto de tiempo de ejecución mediante la función 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 está utilizando GatewayScript, llame a la función siguiente:

apic.getContext(varName)

donde varName es el nombre de la variable de contexto a la que desea acceder.

Para obtener una lista completa de las variables de contexto, consulte API Gateway variables de contexto. Si utiliza el DataPower® API Gateway, consulte también «Uso de variables de contexto en GatewayScript » y «Políticas XSLT con DataPower » en API Gateway.

Acceder al fragmento de código de carga útil de entrada

El bloque de código siguiente muestra un ejemplo de cómo acceder a la carga útil de entrada utilizando la función 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 está utilizando GatewayScript, llame a la función siguiente:

apic.readInput(callback)

Se necesita una devolución de llamada porque la carga útil leída real es asíncrona. El método de devolución de llamada se llama cuando la carga útil está lista.

Esta función devuelve un conjunto de nodos XML que contiene la carga útil de la solicitud. Si la carga útil está en formato JSON, se devuelve un conjunto de nodos JSONx que se puede manipular en una hoja de estilo XSLT o GatewayScript. Si la carga útil no está en formato JSON o XML, el conjunto de nodos que se devuelve está vacío.

El ejemplo siguiente muestra cómo utilizar la función payloadType() para determinar qué tipo de carga útil (XML o JSONx) devolverá función 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>

Acceder al fragmento de código de cabeceras HTTP

El bloque de código siguiente muestra un ejemplo de cómo acceder a las cabeceras HTTP en XSLT mediante la función 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 está utilizando GatewayScript, llame a la función siguiente:

apic.getContext(request.headers.headerName)

donde headerName se correlaciona con el nombre de la cabecera a la que desea acceder.

Nota: No se recomienda acceder a los encabezados de « HTTP » ni modificarlos mediante extensiones de « DataPower », como dp:set-request-header, ya que estas acciones podrían dar lugar a resultados inesperados cuando la política se combine con otras políticas y pasos de ensamblaje.

Modificar el fragmento de código de carga útil

La salida de una política definida por el usuario debe ser un conjunto de nodos XML, que representa un mensaje XML o SOAP , o un mensaje JSON utilizando JSONx. El bloque de código siguiente muestra un ejemplo de cómo modificar la carga útil en XSLT. Para ayudar a la infraestructura de políticas de Pasarela de la API a aceptar el mensaje nuevo o transformado, llame a la plantilla apim-output , tal como se muestra en el ejemplo siguiente.

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

Donde mediaType:

'application/json' es cuando la salida se escribe en formato JSONx.
'application/xml' es cuando la salida se escribe en formato XML.

Si está utilizando GatewayScript, llame a la función siguiente:

apic.output(mediaType)

Donde mediaType es:

application/json es cuando la salida se escribe en formato JSONx.
application/xml es cuando la salida se escribe en formato XML.

La especificación del tipo de soporte permite que los siguientes pasos del flujo de ensamblaje comprendan cómo procesar la carga útil nueva.

Sugerencia: La salida de una política definida por el usuario debe ser XML o JSONx. JSONx es un formato estándar de IBM para representar JSON como XML. Una forma de convertir datos JSON GatewayScript de salida en JSONx es añadir una acción Convert Query Params to XML para seguir la acción GatewayScript dentro de la misma regla de política. La acción

Convert Query Params to
XML

debe tener un Input Conversion con

Default
Encoding

establecido en JSON. La salida de la acción GatewayScript debe ser la entrada de la acción Convert Query Params to XML para que se genere JSONx.

Configurar el fragmento de código de información de error

El bloque de código XSLT siguiente muestra un ejemplo de cómo configurar la implementación de política para generar información de error llamando a la plantilla 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>

donde:

httpCode es el código del mensaje de error necesario.
httpReasonPhrase es la razón del error.
errorMessage es la acción sugerida para el usuario.

Si está utilizando GatewayScript, llame a la función siguiente:

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

donde:

name es el nombre del error.
httpCode es el código del mensaje de error necesario.
httpReasonPhrase es la razón del error.
message es la acción sugerida para el usuario.

Acceso a la excepción interceptada en un bloque catch

El siguiente bloque de código XSLT muestra un ejemplo de cómo, en el bloque catch de un ensamblaje de API, puede obtener los detalles de la excepción interceptada actual. Un posible uso sería crear una respuesta de error personalizada utilizando los detalles de la excepción interceptada.

Para « DataPower Gateway » (compatible con « 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>

Para « API Gateway »:

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

Las funciones apim:getError() y apigw:get-error() devuelven un conjunto de nodos XML; por ejemplo:

<?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 está utilizando GatewayScript, llame a la función siguiente:

apim.getError()

que devuelve un objeto JSON; por ejemplo:

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

Establecer fragmento de código de variables

El bloque de código XSLT siguiente muestra un ejemplo de cómo establecer una variable de tiempo de ejecución en un valor de serie especificado llamando a la plantilla 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>

donde:

varName es el nombre de la variable de tiempo de ejecución para la que desea establecer un valor.
value es el valor de serie en el que desea establecer la variable. Puede tratarse de un valor literal u otra variable. Por ejemplo, para establecer la variable con nombre en el valor de la cabecera Content-Type en una solicitud, debe especificar value como $(request.headers.content-type).

Si está utilizando GatewayScript, llame a la función siguiente:

apic.setvariable(varName, varValue, action)

donde:

varName es el nombre de la variable de tiempo de ejecución para la que desea establecer un valor o que desea añadir o borrar.
varValue es el valor de serie en el que desea establecer la variable. Puede tratarse de un valor literal u otra variable. Por ejemplo, para establecer la variable con nombre en el valor de la cabecera Content-Type en una solicitud, debe especificar varValue como request.headers.content-type. Esta propiedad sólo es necesaria cuando se especifica set o add como acción.
action es la acción que desea aplicar a la variable. Las opciones válidas son:
- set
- add
- clear
Si no se establece ninguna opción, se aplica la opción predeterminada set.

El ejemplo de XSLT siguiente muestra cómo recuperar el valor de una variable de tiempo de ejecución mediante la función 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>

donde

varValue es el nombre de la variable de tiempo de ejecución para la que desea recuperar un valor.

Si está utilizando GatewayScript, llame a la función siguiente:

apic.getvariable(varName)

donde varName es el nombre de la variable de tiempo de ejecución para la que desea recuperar un valor.