מדיניות 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>
  • אם אי אפשר לפתור את משתנה המקור, או שהוא נפתר לסוג שאינו הודעה, שלב הטרנספורמציה נכשל.

הפניה לשגיאה

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

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

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

שגיאות בהטמעה

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

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

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