XSLTransform 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

内容

XSLTransform 政策将自定义可扩展样式表语言转换 (XSLT) 应用于 XML 消息，让您可以将其从 XML 格式转换为其他格式（如 HTML 或纯文本格式）。该政策通常用于集成支持 XML 的应用，但要求对相同的数据使用不同的 XML 格式。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

输入

XSL 政策接受以下输入：

  • （必需）XSLT 样式表的名称，其中包含一组存储在 API 代理中 /resources/xsl 下的转换规则。
  • （必需）需要转换的 XML（通常是请求或响应消息）。
  • （可选）存储输出的变量名称。
  • （可选）与 XSL 样式表中的参数相匹配的参数。

解析处理器

Apigee 依赖于 Saxon XSLT 处理器，并支持 XSLT 1.0 和 2.0。

不受支持的 XSL 元素

XSL 政策不支持以下 APEX 元素：

  • <xsl:include>
  • <xsl:import>

示例

以下示例显示了一个 XSL 转换流程：

XSL 政策 ->

<XSL name="TransformXML">
  <ResourceURL>xsl://my_transform.xsl</ResourceURL>
  <Source>request</Source>
</XSL>

简单的 XSL 政策。转到下一个示例，查看政策中引用的 XSLT 样式表 (my_transform.xsl)。<Source> 元素很重要。例如，如果要转换的 XML 在响应中，除非您将 <Source> 设置为 response（且政策附加到响应流），否则不会发生转换。但在这种情况下，要转换的 XML 位于请求中。

XSLT 样式表 ->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
    <xsl:text></xsl:text>
  </xsl:variable>
  <xsl:template match="/">
  <xsl:text>&lt;Life&gt;</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:text>Here are the odd-numbered items from the list:</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:for-each select="list/listitem">
      <xsl:if test="(position() mod 2) = 1">
        <xsl:number format="1. "/>
        <xsl:value-of select="."/>
        <xsl:value-of select="$newline"/>
      </xsl:if>
    </xsl:for-each>
  <xsl:text>&lt;/Life&gt;</xsl:text>
</xsl:template>
</xsl:stylesheet>

政策中引用的 my_transform.xsl 样式表。转到下一个示例以查看传入 XML 消息的示例。

消息 ->

<?xml version="1.0"?>
<list>
  <title>A few of my favorite albums</title>
  <listitem>A Love Supreme</listitem>
  <listitem>Beat Crazy</listitem>
  <listitem>Here Come the Warm Jets</listitem>
  <listitem>Kind of Blue</listitem>
  <listitem>London Calling</listitem>
  <listitem>Remain in Light</listitem>
  <listitem>The Joshua Tree</listitem>
  <listitem>The Indestructible Beat of Soweto</listitem>
</list>

请求中的示例消息（在第一个示例中，在政策的 <Source>request</Source> 元素中指示）。

转换后的消息

<Life>
Here are the odd-numbered items from the list:
1. A Love Supreme
3. Here Come the Warm Jets
5. London Calling
7. The Joshua Tree
</Life>

来自这些示例的 XSLT 样式表之后的转换消息应用于 XML 消息。

<XSL> 元素

定义 XSLTransform 政策。

默认值 不适用
是否必需？ 必需
类型 复杂对象
父元素 不适用
子元素 <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

<XSL> 元素具有以下特性：

属性 说明 是否必需？ 类型
name 政策的名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Apigee 界面会强制执行其他限制，例如自动移除非字母数字字符。 必需 字符串

子元素参考

本部分介绍 <XSL> 的子元素。

<OutputVariable>

存储转换输出的变量。您应将此元素设为自定义变量，然后再使用该变量。

默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <XSL>
子元素 无

<OutputVariable> 的值不能为 message 类型；也就是说，它不能是 message、request 或 response。

如需将消息内容替换为转换输出，请删除此元素。例如，如果您要将消息转换为 HTML，请勿添加此元素。

<Parameters>

在样式表中添加对 <xsl:param> 元素的支持。您可以将每个参数定义为该元素的 <Parameter> 子元素。

默认值 不适用
是否必需？ 可选
类型 <Parameter> 元素的数组
父元素 <XSL>
子元素 <Parameter>

<Parameters> 元素具有以下特性：

属性 说明 是否必需？ 类型
ignoreUnresolvedVariables 确定此政策是否会忽略 CALP 脚本说明中任何未解决的变量错误。默认值为 false，这意味着默认情况下，如果遇到变量错误，该政策将抛出错误。 可选 布尔值

<Parameter>

在 <Parameters> 元素中定义参数。

默认值 不适用
是否必需？ 可选
类型 复杂对象
父元素 <Parameters>
子元素 无

<Parameter> 元素具有以下特性：

属性 是否必需？ 类型 说明
name 必需 字符串

参数的名称。 Apigee 会将您在此处设置的值与样式表 <xsl:param> 元素上的 name 属性的值进行匹配。

例如，如果您输入 uid 的名称，XSL 可能如下所示：

<xsl:param name="uid" select="''"/>
ref 可选 字符串

指向用于保存参数值值的上下文变量。必须在评估本政策之前设置 ref 上下文变量的值。

例如，如果 uid 参数需要从名为 authn.uid 的变量中获取它的值，则 <Parameter> 元素将如下所示：

<Parameter name="uid" ref="authn.uid"/>

如果您使用此属性，请勿使用 value 属性。
value 可选 字符串

为参数指定硬编码值。例如，如果名为 answer 的参数值为 42，则 <Parameter> 元素将如下所示：

<Parameter name="answer" value="42"/>

如果您使用此属性，请勿使用 ref 属性。

该参数从 ref 属性或通过显式 value 获取其值。

如需查看示例和更多信息，请参阅如何在 PC 转换政策中使用可选参数？

<ResourceURL>

Apigee 用于转换消息的 XSL 文件。此元素的值是存储在 API 代理中 /resources/xsl 下的 XSL 样式表的名称。

默认值 不适用
是否必需？ 必需
类型 字符串
父元素 <XSL>
子元素 无

例如：

<ResourceURL>xsl://SubscriberNumbers-Request.xsl</ResourceURL>

如需了解详情，请参阅资源文件。

<Source>

指定已转换的消息。通常，此值会设置为 request 或 response，具体取决于要转换的消息是入站还是出站消息。

默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <XSL>
子元素 无

定义转换的 XSL 文件由 <ResourceURL> 定义。

  • 如果缺少源，则将其视为简单消息。例如：<Source>message</Source>
  • 如果源变量无法解析或解析为非消息类型，则转换步骤将失败。

错误参考信息

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.xsl.XSLSourceMessageNotAvailable 500 This error occurs if the message or string variable specified in the <Source> element of the XSLTransform policy is either out of scope (not available in the specific flow where the policy is being executed) or can't be resolved (is not defined).
steps.xsl.XSLEvaluationFailed 500 This error occurs if the input XML payload is unavailable/malformed or the XSLTransform policy fails/is unable to transform the input XML file based on the transformation rules provided in the XSL file. There could be many different causes for the XSLTransform policy to fail. The reason for failure in the error message will provide more information on the cause.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
XSLEmptyResourceUrl If the <ResourceURL> element in the XSLTransform policy is empty, then the deployment of the API proxy fails.
XSLInvalidResourceType If the resource type specified in the <ResourceURL> element of the XSLTransform policy is not of type xsl, then the deployment of the API proxy fails.

相关主题