‫XSLTransform policy

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

הדף הזה רלוונטי ל-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 תיכשל.

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