实施代码示例

XSLT 和 GatewayScript 代码片段示例。

注意： 如果使用 GatewayScript, 则必须根据网关类型加入以下命令中的一个或多个：
DataPower
Gatewayvar apic = require(./apim.custom.js);
DataPower API
Gatewayvar apic = require('apim');
其中，apic 是该主题中用于 GatewayScript 示例的公共名称。 但是，apic 可以是您选择的任意名称，例如，您可以使用：
var apim = require(./apim.custom.js);
然后使用 apim 开始调用。

访问输入属性代码片段

以下代码块提供的示例介绍了如何使用 XSLT policyProperties() 函数来访问输入属性。 此示例定义了名为 a_property 的属性，该属性声明为一个整数值，但是在 XSLT 中作为文本进行检索。
<?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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
如果您正在使用 GatewayScript，请调用以下函数：
apic.getPolicyProperty(propertyName)
其中 propertyName 是您要访问的输入属性的名称。 如果输入属性名称为空白，那么操作将返回所有输入属性。

访问运行时上下文代码片段

以下代码块提供的示例介绍了如何使用 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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
如果您正在使用 GatewayScript，请调用以下函数：
apic.getContext(varName)
其中 varName 是您要访问的上下文变量的名称。

有关上下文变量的完整列表，请参阅 API Gateway 上下文变量。 如果要使用 DataPower® API Gateway，另请参阅 将 GatewayScript 和 XSLT 策略中的上下文变量用于 DataPower API Gateway。

访问输入有效内容代码片段

以下代码块提供的示例介绍了如何使用 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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
如果您正在使用 GatewayScript，请调用以下函数：
apic.readInput(callback)
由于实际读取有效内容是一个异步操作，因此需要使用回调方法。 准备好有效内容后，将调用回调方法。
此函数会返回一个 XML 节点集，其中包含请求的有效内容。 如果有效内容采用 JSON 格式，那么会返回一个 JSONx 节点集，随后可在 XLST 或 GatewayScript 样式表中操作此节点集。 如果有效内容未采用 JSON 或 XML 格式，那么返回的节点集为空。
以下示例介绍了如何使用 payloadType() 函数来确定将由 XSLT payloadRead() 函数返回的有效内容的类型（XML 或 JSONx）。
<?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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>

访问 HTTP 头代码片段

以下代码块显示了如何通过使用 getContext() 函数来访问 XSLT 中 HTTP 头的示例。
<?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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
如果您正在使用 GatewayScript，请调用以下函数：
apic.getContext(request.headers.headerName)
其中 headerName 会映射到您要访问的头的名称。
注意： 不建议使用 DataPower 扩展（如 dp:set-request-header ）访问或修改 HTTP ，因为当策略与其他策略和组装步骤结合使用时，此类操作可能会产生意外结果。

修改有效内容代码片段

用户定义的策略 的输出必须是 XML 节点集，它表示 XML 或 SOAP 消息，或者是使用 JSONx 的 JSON 消息。 以下代码块显示了如何修改 XSLT 中的有效内容的示例。 要帮助 API Gateway 策略框架接受新的或已变换的消息，请调用 apim-output 模板，如以下示例中所示。
<?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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
其中 mediaType 为：
  • 'application/json'，前提是以 JSONx 格式写入输出。
  • 'application/xml'，前提是以 XML 格式写入输出。
如果您正在使用 GatewayScript，请调用以下函数：
apic.output(mediaType)
其中 mediaType 是:
  • application/json，前提是以 JSONx 格式写入输出。
  • application/xml，前提是以 XML 格式写入输出。

指定介质类型使组合件流中的后续步骤可以了解如何处理新的有效内容。

提示: 用户定义的策略 的输出必须是 XML 或 JSONx。 JSONx 是一种 IBM 标准格式，用于将 JSON 表示为 XML。 将输出 GatewayScript JSON 数据转换为 JSONx 的一种方法是添加 Convert Query Params to XML 操作以遵循同一策略规则中的 GatewayScript 操作。 Convert Query Params to XML 操作必须具有将 Default Encoding 设置为 JSON的 Input Conversion 。 GatewayScript 操作的输出必须为 Convert Query Params to XML 操作的输入，才能生成 JSONx。

配置错误消息代码片段

以下 XSLT 代码块提供的示例介绍了如何调用 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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
其中：
  • httpCode 是所需错误消息的代码。
  • httpReasonPhrase 是错误的原因。
  • errorMessage 是用户的建议操作。
如果您正在使用 GatewayScript，请调用以下函数：
apic.error(name, httpCode, httpReasonPhrase, message)
其中：
  • name 是错误的名称。
  • httpCode 是所需错误消息的代码。
  • httpReasonPhrase 是错误的原因。
  • message 是用户的建议操作。

访问 catch 块中捕获的异常

以下 XSLT 代码块提供的示例说明了如何在 API 组合件的 catch 块中获取当前捕获的异常的详细信息。 可能的用途将是使用捕获的异常的详细信息创建定制错误响应。

适用于DataPower Gateway（兼容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>
对于 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>
apim:getError() 和 apigw:get-error() 函数返回 XML 节点集；例如：
<?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>
如果您正在使用 GatewayScript，请调用以下函数：
apim.getError()
其返回一个 JSON 对象；例如：
{
  "name": "OperationError",
  "message": "This is a thrown Operation Error",
  "policyTitle": "Throw Operation Error",
  "status": {
    "code": "500",
    "reason": "Internal Server Error"
  }
}

设置变量代码片段

以下 XSLT 代码块提供的示例介绍了如何调用 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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
其中：
  • varName 是要将值设置为的运行时变量的名称。
  • value 是要将变量设置为的字符串值。 这可以是字面值或其他变量。 例如，要将指定变量设置为请求中 Content-Type 头的值，可以将 value 指定为 $(request.headers.content-type)。
如果您正在使用 GatewayScript，请调用以下函数：
apic.setvariable(varName, varValue, action)
其中：
  • varName 是要为其设置值或者要添加/清除的运行时变量的名称。
  • varValue 是要将变量设置为的字符串值。 这可以是字面值或其他变量。 例如，要将指定变量设置为请求中 Content-Type 头的值，可以将 varValue 指定为 request.headers.content-type。 仅当将 set 或 add 指定为操作时，才需要该属性。
  • action 是想要应用于变量的操作。 有效选项为：
    • set
    • add
    • clear
    如果未设置选项，那么会应用缺省选项 set。
以下 XSLT 示例介绍了如何使用 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 -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
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>
其中，
  • varValue 是要为其检索值的运行时变量的名称。
如果您正在使用 GatewayScript，请调用以下函数：
apic.getvariable(varName)
其中 varName 是要为其检索值的运行时变量的名称。