خط‌مشی XSLTransform

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

چه

خط‌مشی «تبدیل XSL» تبدیل‌های زبان برگه گسترش‌پذیر (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» را بااستفاده از عناصر زیر پیکربندی کنید.

نام فیلد شرح
نام (الزامی) نام خط‌مشی. نویسه‌هایی که می‌توانید در نام استفاده کنید به موارد زیر محدود می‌شود: A-Z0-9._\-$ %. بااین‌حال، «واسط کاربر مدیریت» محدودیت‌های بیشتری را اعمال می‌کند، مثل حذف خودکار نویسه‌هایی که الفبایی عددی نیستند.
منبع (اختیاری) حاوی پیامی است که اطلاعات باید از آن استخراج شود. معمولاً این مقدار روی request یا response تنظیم می‌شود، بسته به اینکه پیام تبدیل‌شونده ورودی است یا خروجی.
  • اگر منبع وجود نداشته باشد، به‌عنوان پیام ساده درنظر گرفته می‌شود. برای مثال، <Source>message</Source>
  • اگر متغیر منبع قابل‌حل نباشد یا به نوع غیرپیام حل شود، مرحله تبدیل ناموفق خواهد بود.
متغیر برونداد (اختیاری)

متغیری که برونداد گشتار را ذخیره می‌کند. ‫OutputVariable نمی‌تواند از نوع Message باشد، یعنی نمی‌تواند «پیام»، «درخواست»، یا «پاسخ» باشد. باید این عنصر را به‌عنوان متغیر سفارشی تنظیم کنید، و سپس از آن متغیر استفاده کنید.

برای جایگزین کردن محتوای پیام با برونداد تبدیل، این عنصر را حذف کنید. برای مثال، اگر پیامی را به HTML تبدیل می‌کنید، این عنصر را اضافه نکنید.
ResourceURL (الزامی) فایل XSLT که برای تبدیل پیام استفاده می‌شود.
پارامترها (اختیاری) ignoreUnresolvedVariables (اختیاری)
خطاهای متغیر حل‌نشده در دستورالعمل‌های دستورگان XSLT را نادیده می‌گیرد.
مقادیر معتبر: درست/غلط
مقدار پیش‌فرض: false
پارامتر (اختیاری) نام (الزامی)

پارامترها از استفاده از XSL param در برگه‌های سبک شما پشتیبانی می‌کنند، جایی که نامی که در اینجا در خط‌مشی اضافه می‌کنید نام XSL param است. برای مثال، اگر نام «uid» را وارد کنید، XSL شما ممکن است چیزی شبیه به این باشد: <xsl:param name="uid" select="''"/>).

پارامتر مقدارش را یا از مرجع متغیر زمینه‌ای (شناسایی‌شده با مشخصه ref) یا با value صریح دریافت می‌کند.

برای مثال و اطلاعات بیشتر، به پست انجمن مراجعه کنید.
‫ref (اختیاری)

مرجعی را مشخص می‌کند که مقدار را از متغیر منبع‌یابی می‌کند. برای مثال، اگر پارامتر «uid» باید مقدارش را از متغیری به‌نام «authn.uid» بگیرد، عنصر «پارامتر» به‌این شکل خواهد بود: <Parameter name="uid" ref="authn.uid"/>

اگر از این مشخصه استفاده می‌کنید، از مشخصه مقدار استفاده نکنید.
مقدار (اختیاری)

می‌توانید از این مشخصه برای کدبندی سخت مقدار پارامتر استفاده کنید.

اگر از این مشخصه استفاده می‌کنید، از مشخصه ref استفاده نکنید.

یادداشت‌های استفاده

‫XSLT در فایل .xsl مستقل پیاده‌سازی می‌شود که در پراکسی API تحت /resources/xsl ذخیره می‌شود. خط‌مشی XSL صرفاً به فایل XSL ارجاع می‌دهد. برای اطلاعات بیشتر، فایل‌های منبع را ببینید.

خط‌مشی XSL به دو ورودی نیاز دارد:

  • نام برگه‌سبک XSLT که حاوی مجموعه‌ای از قوانین تبدیل است و در کارگزار پراکسی API تحت /resources/xsl ذخیره شده است
  • منبع XML که باید تبدیل شود (معمولاً پیام درخواست یا پاسخ)

‫<xsl:include> و <xsl:import> پشتیبانی نمی‌شود.

‫Apigee Edge به پردازنده Saxon XSLTمتکی است و از XSLT 1.0 و 2.0 پشتیبانی می‌کند.

مرجع خطا

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای خط‌مشی رخ دهند.

کد خطا وضعیت HTTP علت رفع اشکال
steps.xsl.XSLSourceMessageNotAvailable ۵۰۰ این خطا زمانی رخ می‌دهد که متغیر رشته یا پیام مشخص‌شده در عنصر <Source> خط‌مشی «تبدیل XSL» خارج از محدوده باشد (در جریان خاصی که خط‌مشی در آن اجرا می‌شود دردسترس نباشد) یا قابل‌حل نباشد (تعریف نشده باشد).
steps.xsl.XSLEvaluationFailed ۵۰۰ این خطا زمانی رخ می‌دهد که بار XML ورودی دردسترس نباشد/بدشکل باشد یا خط‌مشی XSLTransform براساس قوانین تبدیل ارائه‌شده در فایل XSL نتواند فایل XML ورودی را تبدیل کند/نتواند تبدیل کند. دلایل مختلفی می‌تواند باعث شود خط‌مشی XSLTransform با خطا مواجه شود. دلیل عدم موفقیت در پیام خطا اطلاعات بیشتری درباره علت ارائه خواهد داد.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

نام خطا علت رفع اشکال
XSLEmptyResourceUrl اگر عنصر <ResourceURL> در خط‌مشی «تبدیل XSL» خالی باشد، استقرار پراکسی API ناموفق خواهد بود.
XSLInvalidResourceType اگر نوع منبع مشخص‌شده در عنصر <ResourceURL> خط‌مشی «تبدیل XSL» از نوع xsl نباشد، استقرار پراکسی API ناموفق خواهد بود.

موضوعات مرتبط