Exemplos de código de implementação

Exemplo de fragmentos de código XSLT e GatewayScript.

Observação: Se você estiver usando o GatewayScript,, deverá incluir um dos seguintes comandos, dependendo do tipo de gateway:

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

em que apic é o nome comum usado para os exemplos de GatewayScript neste tópico. No entanto, apic poderia ser qualquer nome determinado de sua opção, por exemplo, você poderia usar:

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

e, em seguida, iniciaria suas chamadas com apim.

Acesso ao fragmento de código de propriedades de entrada
Acesso ao fragmento de código de contexto de tempo de execução
Acesso ao fragmento de código de carga útil de entrada
Acesso ao fragmento de código de cabeçalhos de HTTP
Modificar o fragmento de código de carga útil
Configurar o fragmento de código de informações de erro
Acessando a exceção de captura em um bloco catch
Configurar o fragmento de código de variáveis

Acesso ao fragmento de código de propriedades de entrada

O bloco de códigos a seguir mostra um exemplo de como acessar as propriedades de entrada usando a função XSLT policyProperties(). o exemplo define uma propriedade denominada a_property, que está declarada como um valor de número inteiro, mas é recuperada em 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>

Se você estiver usando GatewayScript, chame a função a seguir:

apic.getPolicyProperty(propertyName)

em que propertyName é o nome da propriedade de entrada que você deseja acessar. Se o nome da propriedade de entrada estiver em branco, a ação retornará todas as propriedades de entrada.

Acesso ao fragmento de código de contexto de tempo de execução

O bloco de códigos a seguir mostra um exemplo de como acessar o contexto de tempo de execução usando a função 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>

Se você estiver usando GatewayScript, chame a função a seguir:

apic.getContext(varName)

em que varName é o nome da variável de contexto que você deseja acessar.

Para obter uma lista completa das variáveis de contexto, consulte API Gateway context variables. Se você estiver usando o DataPower® API Gateway, consulte também “Usando variáveis de contexto em políticas de GatewayScript e XSLT com o DataPower API Gateway ”.

Acesso ao fragmento de código de carga útil de entrada

O bloco de códigos a seguir mostra um exemplo de como acessar a carga útil de entrada usando a função 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>

Se você estiver usando GatewayScript, chame a função a seguir:

apic.readInput(callback)

Um retorno de chamada é necessário porque a leitura de carga útil real é assíncrona. O método de retorno de chamada será chamado quando a carga útil estiver pronta.

Esta função retorna um conjunto de nós XML que contém a carga útil da solicitação. Se a carga útil estiver no formato JSON, será retornado um conjunto de nós JSONx que poderá, então, ser manipulado em uma folha de estilo XSLT ou GatewayScript. Se a carga útil não estiver no formato JSON ou XML, o conjunto de nós retornado estará vazio.

O exemplo a seguir mostra como usar a função payloadType() para determinar qual tipo de carga útil (XML ou JSONx) será retornado pela função 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>

Acesso ao fragmento de código de cabeçalhos de HTTP

O bloco de códigos a seguir mostra um exemplo de como acessar os cabeçalhos de HTTP em XSLT usando a função 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>

Se você estiver usando GatewayScript, chame a função a seguir:

apic.getContext(request.headers.headerName)

em que headerName é mapeado para o nome do cabeçalho que você deseja acessar.

Observação: Não é recomendável acessar ou modificar os cabeçalhos de ` HTTP ` usando extensões de ` DataPower `, como dp:set-request-header`,`, pois tais ações podem gerar resultados inesperados quando a política for combinada com outras políticas e etapas de montagem.

Modificar o fragmento de código de carga útil

A saída de uma política definida pelo usuário deve ser um conjunto de nós XML, que representa uma mensagem XML ou SOAP ou uma mensagem JSON usando JSONx. O bloco de códigos a seguir mostra um exemplo de como modificar a carga útil em XSLT. Para ajudar a estrutura de política da API do Gateway a aceitar a mensagem nova ou transformada, chame o modelo apim-output , conforme mostrado no exemplo a seguir:

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

Em que mediaType:

'application/json' é quando a saída é gravada no formato JSONx.
'application/xml' é quando a saída é gravada no formato XML.

Se você estiver usando GatewayScript, chame a função a seguir:

apic.output(mediaType)

Em que mediaType é:

application/json é quando a saída é gravada no formato JSONx.
application/xml é quando a saída é gravada no formato XML.

Especificar o tipo de mídia permite que as próximas etapas no fluxo de conjuntos entendam como processar a nova carga útil.

Dica: A saída de uma política definida pelo usuário deve ser XML ou JSONx. JSONx é um formato padrão da IBM para representar JSON como XML. Uma maneira de converter dados JSON GatewayScript de saída em JSONx é incluir uma ação Convert Query Params to XML para seguir a ação GatewayScript na mesma regra de política. A ação

Convert Query Params to
XML

deve ter um Input Conversion com o

Default
Encoding

configurado como JSON A saída da ação GatewayScript deve ser a entrada para a ação Convert Query Params to XML para JSONx a ser produzida.

Configurar o fragmento de código de informações de erro

O bloco de códigos XSLT a seguir mostra um exemplo de como configurar a implementação da política para produzir informações de erro chamando o modelo 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>

em que:

httpCode é o código da mensagem de erro necessária.
httpReasonPhrase é a razão para o erro.
errorMessage é a ação sugerida para o usuário.

Se você estiver usando GatewayScript, chame a função a seguir:

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

em que:

name é o nome do erro..
httpCode é o código da mensagem de erro necessária.
httpReasonPhrase é a razão para o erro.
message é a ação sugerida para o usuário.

Acessando a exceção de captura em um bloco catch

O bloco de códigos XSLT a seguir mostra um exemplo de como, no bloco catch de um conjunto de API, é possível obter os detalhes da exceção de captura atual. Um possível uso seria criar uma resposta de erro customizada usando os detalhes da exceção de captura.

Para o DataPower Gateway (compatível com o 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 o site 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>

As funções apim:getError() e apigw:get-error() retornam um conjunto de nós XML; por exemplo:

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

Se você estiver usando GatewayScript, chame a função a seguir:

apim.getError()

que retorna um objeto JSON, por exemplo:

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

Configurar o fragmento de código de variáveis

O bloco de códigos XSLT a seguir mostra um exemplo de como configurar uma variável de tempo de execução para um valor da sequência especificado chamando o modelo 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>

em que:

varName é o nome da variável de tempo de execução para a qual que você deseja configurar um valor.
value é o valor de sequência para o qual você deseja configurar a variável. Este pode ser um valor literal, ou outra variável. Por exemplo, para configurar sua variável nomeada para o valor do cabeçalho Content-Type em uma solicitação, você especificaria o value como $(request.headers.content-type).

Se você estiver usando GatewayScript, chame a função a seguir:

apic.setvariable(varName, varValue, action)

em que:

varName é o nome da variável de tempo de execução para a qual você deseja configurar um valor, ou que você deseja incluir ou limpar.
varValue é o valor de sequência para o qual você deseja configurar a variável. Este pode ser um valor literal, ou outra variável. Por exemplo, para configurar sua variável nomeada para o valor do cabeçalho Content-Type em uma solicitação, você especificaria o varValue como request.headers.content-type. Essa propriedade é obrigatória apenas quando set ou add é especificado como a ação.
action é a ação que você deseja aplicar à variável. As opções válidas são:
- set
- add
- clear
Se nenhuma opção for configurada, a opção padrão set será aplicada.

O exemplo XSLT a seguir mostra como recuperar o valor de uma variável de tempo de execução usando a função 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>

em que

varValue é o nome da variável de tempo de execução para a qual você deseja recuperar um valor.

Se você estiver usando GatewayScript, chame a função a seguir:

apic.getvariable(varName)

em que varName é o nome da variável de tempo de execução para a qual você deseja recuperar um valor.