XSLTransform 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

輸入內容

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

  • (必要) XSLT 樣式表的名稱，其中包含一組轉換規則，儲存在 /resources/xsl 下的 API Proxy 中。
  • (必填) 要轉換的 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。但在本例中，要轉換的 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 政策。

預設值 不適用
是否必要？ 必填
類型 複雜物件
上層元素 n/a
子元素 <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

<XSL> 元素的屬性如下：

屬性 說明 是否必要 類型
name 政策名稱。您可以在名稱中使用的字元僅限： A-Z0-9._\-$ %。不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元的字元。 必填 字串

子元素參照

本節將說明 <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 檔案。這個元素的值是 /resources/xsl 下 API 代理程式中儲存的 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 政策失敗的原因有很多。 錯誤訊息中的失敗原因會提供更多原因資訊。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
XSLEmptyResourceUrl 如果 XSLTransform 政策中的 <ResourceURL> 元素為空白，API Proxy 的部署作業就會失敗。
XSLInvalidResourceType 如果 XSLTransform 政策的 <ResourceURL> 元素中指定的資源類型不是 xsl 類型，則 API Proxy 的部署作業會失敗。

相關主題