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>
  • 如果源变量无法解析或解析为非消息类型，则转换步骤将失败。

错误参考信息

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.xsl.XSLSourceMessageNotAvailable 500 如果在 XSLTransform 政策的 <Source> 元素中指定的消息或字符串变量超出范围（在执行政策的特定流程中不可用）或无法解决（未定义），则会发生此错误。
steps.xsl.XSLEvaluationFailed 500 如果输入 XML 载荷不可用/格式不正确，或者 XSLTransform 政策失败/无法根据 XSL 文件提供的转换规则转换输入 XML 文件，就会出现此错误。很多不同的原因可能会导致 XSLTransform 政策失败。错误消息中的失败原因提供了有关原因的更多信息。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因 修复
XSLEmptyResourceUrl 如果 XSLTransform 政策中的 <ResourceURL> 元素为空，则 API 代理的部署将会失败。
XSLInvalidResourceType 如果在 XSLTransform 政策的 <ResourceURL> 元素中指定的资源类型不是 xsl 类型，则该 API 代理的部署将会失败。

相关主题