מדיניות XSLTransform

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מדיניות XSLTransform מחילה טרנספורמציות מותאמות אישית של שפת גיליונות סגנונות (XSLT) על הודעות XML, ומאפשרת לכם להמיר אותן מ-XML לפורמט אחר, כמו HTML או טקסט פשוט. המדיניות הזו משמשת לעיתים קרובות לשילוב אפליקציות שתומכות ב-XML, אבל נדרשים בהן פורמטים שונים שמבוססים על XML לאותם נתונים.

המדיניות הזו היא מדיניות שניתנת להרחבה, והשימוש בה עשוי להשפיע על העלויות או על הניצול, בהתאם לרישיון שלכם ל-Apigee. למידע על סוגי מדיניות והשלכות השימוש, אפשר לעיין במאמר בנושא סוגי מדיניות.

קלט

מדיניות ה-XSL מקבלת את הקלט הבא:

  • (חובה) השם של גיליון סגנונות XSLT, שמכיל קבוצה של כללי המרה שמאוחסנים ב-proxy ל-API בנתיב /resources/xsl.
  • (חובה) ה-XML שצריך להמיר (בדרך כלל בקשה או הודעת תגובה).
  • (אופציונלי) השם של משתנה שבו מאוחסן הפלט.
  • (אופציונלי) פרמטרים שתואמים לפרמטרים בגיליון הסגנונות של XSL.

מעבד ניתוח

‫Apigee מסתמך על מעבד Saxon XSLT ותומך ב-XSLT 1.0 וב-XSLT 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 פשוטה. בדוגמה הבאה מוצג גיליון הסגנונות של XSLT שאליו מתייחסת המדיניות (my_transform.xsl). הרכיב <Source> חשוב. לדוגמה, אם ה-XML שרוצים להמיר נמצא בתגובה, ההמרה לא תתבצע אלא אם מגדירים את <Source> ל-response (והמדיניות מצורפת לזרימת התגובה). אבל במקרה הזה, ה-XML שצריך להמיר נמצא בבקשה.

XSLT stylesheet -->

<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 אוכף הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים. חובה String

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הבן של <XSL>.

<OutputVariable>

משתנה שמאחסן את הפלט של הטרנספורמציה. כדאי להגדיר את הרכיב הזה כמשתנה מותאם אישית, ואז להשתמש במשתנה הזה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב אב <XSL>
רכיבי צאצא ללא

הערך של <OutputVariable> לא יכול להיות מסוג message, כלומר הוא לא יכול להיות message,‏ request או response.

כדי להחליף את תוכן ההודעה בפלט של ההמרה, צריך למחוק את האלמנט הזה: . לדוגמה, אם ממירים הודעה ל-HTML, לא כוללים את האלמנט הזה: .

<Parameters>

הוספת תמיכה ברכיב <xsl:param> בגיליונות הסגנונות. מגדירים כל פרמטר כרכיב צאצא <Parameter> של הרכיב הזה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <Parameter> אלמנטים
רכיב אב <XSL>
רכיבי צאצא <Parameter>

לרכיב <Parameters> יש את המאפיינים הבאים:

מאפיין תיאור חובה? סוג
ignoreUnresolvedVariables קובעת אם המדיניות מתעלמת משגיאות של משתנים לא פתורים בהוראות של סקריפט XSLT. ערך ברירת המחדל הוא false, כלומר כברירת מחדל המדיניות תציג שגיאות אם היא תיתקל במשתנים לא פתורים. אופציונלי בוליאני

<Parameter>

מגדיר פרמטר ברכיב <Parameters>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג אובייקט מורכב
רכיב אב <Parameters>
רכיבי צאצא ללא

לרכיב <Parameter> יש את המאפיינים הבאים:

מאפיין חובה? סוג תיאור
name חובה String

שם הפרמטר. מערכת Apigee משווה את הערך שהגדרתם כאן לערך של המאפיין name ברכיב <xsl:param> בגיליון הסגנונות.

לדוגמה, אם תזינו שם של uid, קובץ ה-XSL יכול להיראות כך: 

<xsl:param name="uid" select="''"/>
ref אופציונלי String

מצביע על משתנה הקשר שמכיל את הערך של הפרמטר. צריך להגדיר ערכים למשתני ההקשר ref לפני ההערכה של המדיניות הזו.

לדוגמה, אם פרמטר uid צריך לקבל את הערך שלו ממשתנה שנקרא authn.uid, רכיב <Parameter> ייראה כך:

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

אם משתמשים במאפיין הזה, אסור להשתמש במאפיין value.
value אופציונלי String

מציינים ערך מקודד לפרמטר. לדוגמה, אם לפרמטר בשם answer צריך להיות הערך 42, רכיב <Parameter> ייראה כך:

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

אם משתמשים במאפיין הזה, אסור להשתמש במאפיין ref.

הפרמטר מקבל את הערך שלו מהמאפיין ref או עם value מפורש.

דוגמה ומידע נוסף זמינים במאמר איך צריך להשתמש בפרמטרים האופציונליים במדיניות XSL Transform?

<ResourceURL>

קובץ ה-XSL שמשמש את Apigee לשינוי ההודעה. הערך של הרכיב הזה הוא השם של גיליון הסגנונות XSL שמאוחסן ב-proxy ל-API בנתיב /resources/xsl.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג String
רכיב אב <XSL>
רכיבי צאצא ללא

לדוגמה:

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

מידע נוסף זמין במאמר בנושא קובצי משאבים.

<Source>

מציינת את ההודעה שעוברת המרה. בדרך כלל הערך הזה מוגדר כ-request או כ-response, בהתאם לכך שההודעה שצריך לשנות היא דואר נכנס או דואר יוצא.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב אב <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.

נושאים קשורים