概要
XSL 変換ポリシーは、カスタム Extensible スタイルシート言語変換(XSLT)を XML メッセージに適用し、XML、HTML、書式なしテキストなどの別の形式に変換します。このポリシーは、XML 対応のアプリケーションを統合する際によく使用されていますが、同じデータに対して異なる XML 形式が必要になります。
サンプル
以降のサンプルでは、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><Life></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></Life></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 Transformation ポリシーを構成します。
フィールド名 | 説明 | |||
---|---|---|---|---|
Name(必須) |
ポリシーの名前。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。
|
|||
Source(省略可) |
情報の抽出元からのメッセージが格納されます。通常、この値は変換するメッセージが受信か送信かに応じて request または response に設定されます。
|
|||
OutputVariable(省略可) |
変換の出力結果が保存される変数。OutputVariable はメッセージ タイプにできません。つまり、'message'、'request'、'response' にはできません。この要素をカスタム変数に設定し、その変数を使用する必要があります。 メッセージのコンテンツを変換の出力で置き換えるには、この要素を削除します。たとえば、メッセージを HTML に変換する場合は、この要素を使用しないでください。 |
|||
ResourceURL(必須) | メッセージの変換に使用される XSLT ファイル。 | |||
Parameters(省略可) | ignoreUnresolvedVariables(省略可) |
XSLT スクリプトの命令で未解決変数のエラーを無視します。
有効な値: true / false
デフォルト値: false
|
||
Parameter(省略可) | name(必須) |
Parameters は、スタイルシートでの XSL param の使用を許可します。ポリシーのここで追加した名前が XSL param の名前になります。たとえば、"uid" という名前を入力した場合、XSL は param は、コンテキスト変数( 例と詳細については、http://community.apigee.com/questions/1860/how-should-the-the-optional-parameters-on-the-xsl.html#answer-1864 をご覧ください。 |
||
ref(省略可) |
変数に格納された値の参照元を指定します。たとえば、"uid" パラメータが authn.uid"という変数から値を取得する必要がある場合、Parameter 要素は この属性を使用した場合は、value 属性を使用しないでください。 |
|||
value(省略可) |
この属性を使用すると、パラメータの値をハードコートできます。 この属性を使用する場合は、ref 属性を使用しないでください。 |
使用上の注意
XSLT はスタンドアロンの .xsl
ファイルで実装され、API プロキシの /resources/xsl
の下に保存されます。XSL ポリシーは XSL ファイルを参照するだけです。詳細については、リソース ファイルをご覧ください。
XSL ポリシーには 2 つの入力が必要です。
- API プロキシの
/resources/xsl
の下に保存されている一連の変換ルールが含まれる XSLT スタイルシートの名前 - 変換する XML のソース(通常は、リクエストまたはレスポンス メッセージ)
<xsl:include>
と <xsl:import>
はサポートされていません。
Apigee Edge は Saxon XSLT プロセッサに依存し、XSLT 1.0 と 2.0 をサポートします。
エラー リファレンス
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 | 解決方法 |
---|---|---|---|
steps.xsl.XSLSourceMessageNotAvailable |
500 |
このエラーは、XSL Transform ポリシーの <Source> 要素で指定されたメッセージまたは文字列変数がスコープ外である(ポリシーが実行されている特定のフローで使用できない)か、解決できない(定義されていない)場合に発生します。 |
build |
steps.xsl.XSLEvaluationFailed |
500 | このエラーは、入力 XML ペイロードが使用できない、または不正な形式の場合、または XSLTransform ポリシーが XSL ファイルに指定された変換ルールに基づいた入力 XML ファイルの変換に失敗する、または変換できない場合に発生します。XSLTransform ポリシーは、さまざまな原因で失敗します。エラー メッセージに含まれている失敗の理由から、原因についてより詳しい情報を得ることができます。 | build |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
エラー名 | 原因 | 解決方法 |
---|---|---|
XSLEmptyResourceUrl |
XSL Transform ポリシーの <ResourceURL> 要素が空の場合、API プロキシのデプロイは失敗します。 |
build |
XSLInvalidResourceType |
XSL Transform ポリシーの <ResourceURL> 要素に指定されたリソースタイプが xsl でない場合、API プロキシのデプロイは失敗します。 |
build |