מדיניות XSLTransform

אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעבור אל מסמכי התיעוד של Apigee X. מידע

מה

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

דוגמאות

בדוגמאות הבאות מוצגים כל המשאבים בתהליך של טרנספורמציית XSL.

מדיניות XSL ->

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

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

שם השדה תיאור
שם (חובה) שם המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל: A-Z0-9._\-$ %. עם זאת, בממשק המשתמש לניהול יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.
מקור (אופציונלי) מכיל את ההודעה שממנה צריך לחלץ מידע. בדרך כלל הערך הזה מוגדר כ-request או כ-response, בהתאם לכך שההודעה שצריך לשנות היא דואר נכנס או דואר יוצא.
  • אם המקור חסר, ההודעה נחשבת להודעה פשוטה. לדוגמה, <Source>message</Source>
  • אם אי אפשר לפענח את משתנה המקור, או אם הפענוח שלו מוביל לסוג שאינו הודעה, שלב הטרנספורמציה נכשל.
OutputVariable (אופציונלי)

משתנה שמאחסן את הפלט של הטרנספורמציה. המשתנה OutputVariable לא יכול להיות מסוג Message, כלומר הוא לא יכול להיות 'message',‏ 'request' או 'response'. כדאי להגדיר את הרכיב הזה כמשתנה מותאם אישית, ואז להשתמש במשתנה הזה.

כדי להחליף את תוכן ההודעה בפלט של ההמרה, מוחקים את האלמנט הזה. לדוגמה, אם אתם משנים הודעה ל-HTML, אל תכללו את הרכיב הזה.
ResourceURL (חובה) קובץ ה-XSLT שבו ישתמשו כדי לבצע טרנספורמציה של ההודעה.
פרמטרים (אופציונלי) ignoreUnresolvedVariables (אופציונלי)
המערכת מתעלמת משגיאות לא פתורות במשתנים בהוראות של סקריפט XSLT.
ערכים אפשריים: true/false
ערך ברירת המחדל: false
פרמטר (אופציונלי) name (חובה)

הפרמטרים תומכים בשימוש ב-XSL param בגיליונות הסגנון, כאשר השם שמוסיפים כאן במדיניות הוא השם של XSL param. לדוגמה, אם מזינים את השם uid, קובץ ה-XSL יכול להיראות כך: <xsl:param name="uid" select="''"/>).

הערך של הפרמטר מתקבל מהפניה למשתנה הקשר (שמזוהה על ידי המאפיין ref) או על ידי הגדרה מפורשת של value.

דוגמה ומידע נוסף זמינים בפוסט לקהילה.
ref (אופציונלי)

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

אם משתמשים במאפיין הזה, לא משתמשים במאפיין הערך.
value (אופציונלי)

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

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

הערות שימוש

ה-XSLT מוטמע בקובץ .xsl עצמאי, שמאוחסן ב-API proxy בתיקייה /resources/xsl. מדיניות ה-XSL רק מפנה לקובץ ה-XSL. מידע נוסף זמין במאמר בנושא קבצי משאבים.

מדיניות ה-XSL דורשת שני קלטים:

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

אין תמיכה ב-<xsl:include> וב-<xsl:import>.

‫Apigee Edge מסתמך על מעבד Saxon XSLT, ותומך ב-XSLT 1.0 וב-XSLT 2.0.

הפניה לשגיאה

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד שגיאה סטטוס HTTP סיבה תיקון
steps.xsl.XSLSourceMessageNotAvailable 500 השגיאה הזו מתרחשת אם משתנה ההודעה או המחרוזת שצוינו ברכיב <Source> של מדיניות ה-XSL Transform הם מחוץ להיקף (לא זמין בתהליך הספציפי שבו המדיניות מופעלת) או שלא ניתן לפענח אותם (לא מוגדר).
steps.xsl.XSLEvaluationFailed 500 השגיאה הזו מתרחשת אם המטען הייעודי (payload) ב-XML של הקלט אינו זמין או שפורמטו שגוי, או אם מדיניות XSLTransform נכשלת או שלא ניתן לבצע טרנספורמציה של קובץ ה-XML של הקלט בהתאם לכללי הטרנספורמציה שצוינו בקובץ ה-XSL. יכולות להיות סיבות רבות לכישלון של מדיניות XSLTransform. סיבת הכשל בהודעת השגיאה תספק מידע נוסף על הסיבה.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

שם השגיאה סיבה תיקון
XSLEmptyResourceUrl אם הרכיב <ResourceURL> במדיניות XSL Transform ריק, הפריסה של שרת ה-proxy של ה-API תיכשל.
XSLInvalidResourceType אם סוג המשאב שצוין באלמנט <ResourceURL> של מדיניות XSL Transform אינו מסוג xsl, הפריסה של שרת ה-proxy של ה-API תיכשל.

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