XSLTransform 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

XSLTransform 政策會對 XML 訊息套用自訂的可延伸樣式表語言轉換 (XSLT)，讓您將 XML 轉換為其他格式，例如 HTML 或純文字。這項政策通常用於整合支援 XML 的應用程式，但這些應用程式需要使用不同的 XML 格式來處理相同資料。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

輸入內容

XSL 政策會採用下列輸入內容：

  • (必要) XSLT 樣式表的名稱，其中包含儲存在 API Proxy /resources/xsl 下的一組轉換規則。
  • (必要) 要轉換的 XML (通常是要求或回應訊息)。
  • (選用) 儲存輸出的變數名稱。
  • (選用) 與 XSL 樣式表中的參數相符的參數。

剖析處理器

Apigee 採用 Saxon XSLT 處理器，並支援 XSLT 1.0 和 2.0。

不支援的 XSL 元素

XSL 政策不支援下列 XSL 元素：

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

範例

下列範例顯示 XSL 轉換流程：

XSL 政策 -->

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

簡單的 XSL 政策。請參閱下一個範例，瞭解政策 (my_transform.xsl) 中參照的 XSLT 樣式表。<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 決定政策是否要忽略 XSLT 指令中任何未解決的變數錯誤。預設值為 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。

如需範例和更多資訊，請參閱「XSL 轉換政策的選用參數應如何使用？」。

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

相關主題