قم بتحويل JSON وXML باستخدام قوالب Liquid كخرائط في سير العمل باستخدام Azure Logic Apps

ينطبق على: Azure Logic Apps (الاستهلاك + قياسي)

عندما تريد إجراء تحويلات JSON الأساسية في سير عمل تطبيقات المنطق الخاصة بك، يمكنك استخدام بيانات العمليات المدمجة مثل إجراء Compose أو إجراء Parse JSON. ومع ذلك، قد تتطلب بعض السيناريوهات تحويلات متقدمة ومعقدة تتضمن عناصر مثل التكرارات وتدفقات التحكم والمتغيرات. بالنسبة للتحويلات بين JSON إلى JSON أو JSON إلى نص أو XML إلى JSON أو XML إلى نص، يمكنك إنشاء قالب يصف التعيين أو التحويل المطلوب باستخدام لغة القالب Liquid ذو مصدر مفتوح. يمكنك تحديد هذا القالب عند إضافة إجراء مدمج في قالب Liquid إلى سير العمل الخاص بك. يمكنك استخدام إجراءات Liquid في مهام سير عمل تطبيق منطق الاستهلاك متعدد المستأجرين ومهام سير عمل التطبيق المنطقي القياسي أحادي المستأجر.

على الرغم من عدم توفر مشغّلات Liquid، يمكنك استخدام أي مشغّل أو إجراء لنقل محتوى JSON المصدر h, XML إلى سير العمل. على سبيل المثال، يمكنك استخدام مشغّل موصل مضمن أو مشغّل موصل مُدار أو مُستضاف على Azure متوفر لـ Azure Logic Apps أو حتى لتطبيق آخر.

توضح هذه المقالة كيفية إكمال المهام التالية:

• إنشاء قالب Liquid.
• حمّل القالب إلى حساب التكامل الخاص بك لسير عمل تطبيق منطق الاستهلاك أو إلى مورد تطبيق المنطق القياسي للاستخدام في أي سير عمل تابع.
• أضف إجراء Liquid إلى سير العمل الخاص بك.
• حدد القالب كخريطة تريد استخدامها.

لمعرفة مزيد من المعلومات، راجع الوثائق التالية:

• تنفيذ عمليات البيانات في Azure Logic Apps
• لغة القالب Liquid ذو مصدر مفتوح
• تطبيق منطق "الاستهلاك" مقابل تطبيق منطق "قياسي"
• موصلات حساب التكامل المضمنة
• نظرة عامة على الموصلات المدمجة لتطبيقات Azure Logic
• نظرة عامة على الموصلات المدارة أو المستضافة من Azure لتطبيقات Azure Logicوالموصلات المدارة أو المستضافة من Azure في Azure Logic Apps

المتطلبات الأساسية

• حساب واشتراك Azure. إذا لم يكن لديك اشتراك، فيجب التسجيل للحصول على حساب Azure مجاني.

• مورد تطبيق المنطق وسير العمل. لا تحتوي العمليات السائلة على أي مشغلات متوفرة، لذلك يجب أن يتضمن سير العمل الحد الأدنى من المشغل. لمزيد من المعلومات، يمكنك الحصول على الوثائق التالية:

  • إنشاء مثال سير عمل تطبيق منطق الاستهلاك في تطبيقات Azure Logic Apps متعددة المستأجرين

  • إنشاء مثال لسير عمل تطبيق المنطق القياسي في Azure Logic Apps أحادي المستأجر

• ستحتاج إلى مورد حساب تكامل استنادًا إلى ما إذا كنت تعمل على سير عمل لتطبيق منطق "قياسي" أو "استهلاكي". تحتاج عادة إلى هذا المورد عندما تريد تعريف الأدوات وتخزينها لاستخدامها في تكامل المؤسسة ومهام سير عمل تعاون B2B.

  هام

  يجب أن يتواجد كل من حساب التكامل ومورد تطبيق المنطق في نفس اشتراك Azure ومنطقة Azure ليعملا معاً.

  • إذا كنت تعمل على سير عمل تطبيق منطق الاستهلاك، فإن حساب التكامل الخاص بك يتطلب ارتباطًا إلى مورد تطبيق المنطق الخاص بك.

  • إذا كنت تعمل على سير عمل تطبيق منطق قياسي، يمكنك ربط حساب التكامل بمورد تطبيق المنطق الخاص بك، أو تحميل الخرائط مباشرة إلى مورد تطبيق المنطق الخاص بك، أو كليهما، استنادًا إلى السيناريوهات التالية:

    • إذا كان لديك بالفعل حساب تكامل مع البيانات الاصطناعية التي تحتاجها أو تريد استخدامها، يمكنك ربط حساب التكامل بموارد تطبيق منطق قياسي متعددة حيث تريد استخدام البيانات الاصطناعية. وبهذه الطريقة، لا يتعين عليك تحميل الخرائط إلى كل تطبيق منطق فردي. لمزيد من المعلومات، راجع ربط مورد تطبيق المنطق بحساب التكامل الخاص بك.

    • يتيح لك الموصل المضمن في Liquid تحديد المخطط الذي حملته مسبقاً إلى مورد تطبيق المنطق أو إلى حساب تكامل مرتبط ولكن ليس لكليهما. يمكنك بعد ذلك استخدام هذه البيانات الاصطناعية عبر جميع مهام سير عمل الفرعية داخل نفس مورد التطبيق المنطقي.

    لذلك، إذا لم يكن لديك حساب تكامل أو لا تحتاج إليه، يمكنك استخدام خيار التحميل. وإلا، يمكنك استخدام خيار الربط. يمكنك، في كلتا الحالتين، استخدام هذه الأدوات عبر جميع مهام سير العمل التابعة داخل نفس مورد تطبيق المنطق.

• معلومات أساسية حول لغة قالب Liquid. Azure Logic Apps تستخدم DotLiquid 2.0.361.

  إشعار

  يتبع الإجراء المسمي Liquid تحويل JSON إلى JSON تنفيذ DotLiquid لـ Liquid، والذي يختلف في حالات محددة عن تنفيذ Shopify لـ Liquid. لمزيد من المعلومات، راجع اعتبارات قالب Liquid.

• تثبيت أو استخدام أداة يمكنها إرسال طلبات HTTP لاختبار الحل الخاص بك، على سبيل المثال:

  • Visual Studio Code مع ملحق من Visual Studio Marketplace
  • استدعاء PowerShell-RestMethod
  • Microsoft Edge - أداة وحدة تحكم الشبكة
  • برونو
  • curl

  تنبيه

  بالنسبة للسيناريوهات التي يكون لديك فيها بيانات حساسة، مثل بيانات الاعتماد والأسرار ورمز الوصول المميزة ومفاتيح واجهة برمجة التطبيقات ومعلومات أخرى مشابهة، تأكد من استخدام أداة تحمي بياناتك باستخدام ميزات الأمان الضرورية، وتعمل دون اتصال أو محليا، ولا تقوم بمزامنة بياناتك مع السحابة، ولا تتطلب تسجيل الدخول إلى حساب عبر الإنترنت. وبهذه الطريقة، يمكنك تقليل المخاطر المتعلقة بكشف البيانات الحساسة للجمهور.

الخطوة 1: إنشاء القالب

قبل أن تتمكن من إجراء تحويل Liquid في سير عمل تطبيق المنطق، يجب أولاً إنشاء قالب Liquid الذي يحدد التعيين الذي تريده.

1. إنشاء قالب Liquid الذي تستخدمه كخريطة لتحويل JSON. يمكنك استخدام أي أداة تحرير تريدها.

   يستخدم مثال تحويل JSON إلى JSON في هذه المقالة نموذج القالب Liquid التالي:

   {%- assign deviceList = content.devices | Split: ', ' -%}
   
   {
      "fullName": "{{content.firstName | Append: ' ' | Append: content.lastName}}",
      "firstNameUpperCase": "{{content.firstName | Upcase}}",
      "phoneAreaCode": "{{content.phone | Slice: 1, 3}}",
      "devices" : [
         {%- for device in deviceList -%}
            {%- if forloop.Last == true -%}
            "{{device}}"
            {%- else -%}
            "{{device}}",
            {%- endif -%}
         {%- endfor -%}
      ]
   }
   

2. احفظ القالب باستخدام ملحق ملف قالب Liquid (.liquid). يستخدم هذا المثال SimpleJsonToJsonTemplate.liquid.

الخطوة 2: تحميل قالب Liquid

بعد إنشاء قالب Liquid، يجب عليك الآن تحميل القالب استنادًا إلى السيناريو التالي:

• إذا كنت تعمل على سير عمل تطبيق منطق الاستهلاك، فحمّل القالب إلى حساب التكامل الخاص بك.

• إذا كنت تعمل على سير عمل تطبيق منطق قياسي، يمكنك تحميل القالب إلى حساب التكامل الخاص بك، أو تحميل القالب الخاص بك إلى مورد تطبيق المنطق الخاص بك.

تحميل القالب إلى حساب التكامل

1. في مدخل Microsoft Azure، سجل الدخول باستخدام بيانات اعتماد حساب Azure.

2. في مربّع البحث بمدخل Azure، أدخل integration accounts وحدد Integration accounts.

   

3. ابحث عن حساب التكامل الخاص بك وحدده.

   

4. في قائمة تنقل حساب التكامل، ضمن Settings، حدد Maps.

   

5. في جزء Maps، حدد Add. قدم المعلومات التالية حول خريطتك:

   الخاصية	القيمة‬	‏‏الوصف
   الاسم	JsonToJsonTemplate	اسم الخريطة، وهو "JsonToJsonTemplate" في هذا المثال
   نوع الخريطة	Liquid	نوع الخريطة. لتحويل JSON إلى JSON، يجب عليك تحديد Liquid.
   الخريطة	SimpleJsonToJsonTemplate.liquid	قالب Liquid موجود أو ملف خريطة لاستخدامه للتحويل، وهو "SimpleJsonToJsonTemplate.liquid" في هذا المثال. للعثور على هذا الملف، يمكنك استخدام منتقي الملفات. للحصول على حدود حجم الخريطة، راجع الحدود والتكوين.

   

تحميل قالب إلى تطبيق المنطق القياسي

1. في مدخل Microsoft Azure، ابحث عن مورد تطبيق المنطق وافتحه. تأكد من أنك على مستوى المورد، وليس مستوى سير العمل.

2. في قائمة تنقل موارد التطبيق المنطقي، ضمن Artifacts، حدد Maps.

3. في شريط أدوات جزء Maps ، حدد Add.

4. في جزء Add Map، قم بتوفير المعلومات التالية حول القالب الخاص بك:

   الخاصية	القيمة‬	‏‏الوصف
   الاسم	JsonToJsonTemplate	اسم الخريطة، وهو "JsonToJsonTemplate" في هذا المثال
   نوع الخريطة	Liquid	نوع الخريطة. لتحويل JSON إلى JSON، يجب عليك تحديد Liquid.
   الخريطة	SimpleJsonToJsonTemplate.liquid	قالب Liquid موجود أو ملف خريطة لاستخدامه للتحويل، وهو "SimpleJsonToJsonTemplate.liquid" في هذا المثال. للعثور على هذا الملف، يمكنك استخدام منتقي الملفات. للحصول على حدود حجم الخريطة، راجع الحدود والتكوين.

5. عند الانتهاء، حدد موافق.

   بعد انتهاء تحميل ملف المخطط، يظهر المخطط في قائمة Maps . في صفحة Overview على حساب التكامل الخاص بك، ضمن Artifacts، يظهر المخطط الذي تم تحميله أيضًا.

الخطوة 3: إضافة إجراء تحويل السائل

توضح الخطوات التالية كيفية إضافة إجراء تحويل Liquid لسير عمل تطبيق المنطق الاستهلاكي والقياسي.

استهلاك

1. في مدخل Microsoft Azure، افتح سير عمل تطبيق المنطق في المصمم إذا لم يكن مفتوحاً بالفعل.

2. إذا لم يكن لسير العمل مشغّل أو أي إجراءات أخرى يحتاجها سير العمل، فأضف هذه العمليات أولًا. لا تحتوي العمليات السائلة على أي مشغّلات متوفرة.

   يستمر هذا المثال مع مشغل الطلب المسمى عند تلقي طلب HTTP.

3. على سير عمل المصمم، ضمن الخطوة التي تريد إضافة إجراء Liquid إليها، حدد خطوة جديدة.

4. ضمن مربع البحث Choose an operation، حدد All. في مربع البحث، أدخل Liquid.

5. من قائمة الإجراءات، حدد إجراء Liquid الذي تريد استخدامه.

   يستمر هذا المثال في استخدام الإجراء المسمى تحويل JSON إلى JSON.

   

6. في خاصية Content الخاصة بالإجراء، قدّم إخراج JSON من المشغّل أو إجراء سابق تريد تحويله من خلال اتباع هذه الخطوات.

   1. انقر داخل مربع المحتوى بحيث تظهر قائمة المحتوى الديناميكي.

   2. من قائمة المحتوى الديناميكي، حدّد بيانات JSON التي تريد تحويلها.

      على سبيل المثال، من قائمة "المحتوى الديناميكي"، ضمن "عند تلقي طلب HTTP"، حدد رمز "النص" المميز الذي يمثل إخراج محتوى النص من المشغّل.

      

7. من قائمة مخطط، حدد قالب Liquid.

   يستمر هذا المثال مع القالب المسمى JsonToJsonTemplate.

   

   إشعار

   إذا كانت قائمة المخططات فارغة، إما أن مورد تطبيق المنطق غير مرتبط بحساب التكامل أو أن حساب التكامل لا يحتوي على أي ملفات مخططات.

   عند الانتهاء، يبدو الإجراء مشابهاً للمثال التالي:

   

8. احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

قياسي

1. في مدخل Microsoft Azure، افتح سير عمل تطبيق المنطق في المصمم إذا لم يكن مفتوحاً بالفعل.

2. إذا لم يكن لسير العمل مشغّل أو أي إجراءات أخرى يحتاجها سير العمل، فأضف هذه العمليات أولًا. لا تحتوي العمليات السائلة على أي مشغّلات متوفرة.

   يستمر هذا المثال مع مشغل الطلب المسمى عند تلقي طلب HTTP.

3. على المصمم، ضمن الخطوة حيث تريد إضافة إجراء Liquid، حدد علامة الجمع (+)، ثم حدد إضافة إجراء.

4. في جزء "إضافة إجراء" الذي يظهر، ضمن مربع البحث، حدد "مضمن".

5. في مربع البحث، أدخل Liquid. من قائمة الإجراءات، حدد إجراء Liquid الذي تريد استخدامه.

   يستمر هذا المثال في استخدام الإجراء المسمى تحويل JSON إلى JSON.

   

6. في خاصية Content الخاصة بالإجراء، قدّم إخراج JSON من المشغّل أو إجراء سابق تريد تحويله من خلال اتباع هذه الخطوات.

   1. انقر داخل مربع المحتوى بحيث تظهر قائمة المحتوى الديناميكي.

   2. من قائمة المحتوى الديناميكي، حدّد بيانات JSON التي تريد تحويلها.

      على سبيل المثال، في قائمة المحتوى الديناميكي، ضمن عند تلقي طلب HTTP، حدد الرمز المميز للنص الأساسي، الذي يمثل إخراج محتوى النص الأساسي من المشغل.

      

   إشعار

   إذا لم تظهر خاصية النص في قائمة المحتوى الديناميكي، فحدد عرض المزيد بجوار تسمية القسم عند تلقي طلب HTTP. يمكنك أيضاً إدخال المحتوى مباشرة لفك ترميزه في مربع المحتوى.

7. من قائمة Source، حدد إما LogicApp أو IntegrationAccount كمصدر قالب Liquid.

   يستمر هذا المثال عن طريق تحديد IntegrationAccount.

   

8. من قائمة Name، حدد قالب Liquid.

   يستمر هذا المثال مع القالب المسمى JsonToJsonTemplate.

   

   إشعار

   إذا كانت قائمة الخرائط فارغة، فمن المحتمل ألا يكون مورد تطبيقك المنطقي مرتبطاً بحساب التكامل الخاص بك. تأكد من ربط تطبيق المنطق بحساب التكامل الذي يحتوي على قالب أو خريطة Liquid

   عند الانتهاء، يبدو الإجراء مشابهاً للمثال التالي:

   

9. احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

اختبار سير العمل

لتشغيل سير العمل، اتبع الخطوات التالية:

1. في مشغل الطلب ، ابحث عن خاصية HTTP POST URL ، وانسخ عنوان URL.

2. افتح أداة طلب HTTP واستخدم إرشاداتها لإرسال طلب HTTP إلى عنوان URL المنسخ، بما في ذلك الأسلوب الذي يتوقعه مشغل الطلب .

   يستخدم POST هذا المثال الأسلوب مع عنوان URL.

3. قم بتضمين إدخال JSON للتحويل، على سبيل المثال:

   {
      "devices": "Surface, Mobile, Desktop computer, Monitors",
      "firstName": "Dean",
      "lastName": "Ledet",
      "phone": "(111)0001111"
   }
   

4. بعد انتهاء تشغيل سير العمل، انتقل إلى محفوظات تشغيل سير العمل، وافحص مدخلات ومخرجات إجراء تحويل JSON إلى JSON، على سبيل المثال:

   

تحولات Liquid الأخرى

يمكنك استخدام Liquid لإجراء تحويلات أخرى، على سبيل المثال:

• JSON إلى نص
• XML إلى JSON
• XML إلى نص

تحويل JSON إلى نص

يعرض قالب Liquid التالي مثالاً لتحويل JSON إلى نص:

{{content.firstName | Append: ' ' | Append: content.lastName}}

يوضح المثال التالي نماذج الإدخالات والمخرجات:

تحويل XML إلى JSON

يعرض قالب Liquid التالي مثالاً لتحويل XML إلى JSON:

[{% JSONArrayFor item in content -%}
      {{item}}
  {% endJSONArrayFor -%}]

يعبر التكرار الحلقي JSONArrayFor عن آلية تكرار حلقي مخصصة لإدخال XML بحيث يمكنك إنشاء بيانات أساسية لـ JSON تتجنب الفاصلة اللاحقة. أيضاً، يستخدم شرط where آلية التكرار الحلقي المخصصة هذه اسم عنصر XML للمقارنة، بدلاً من قيمة العنصر، مثل عوامل تصفية Liquid الأخرى. لمزيد من المعلومات، راجع التعمق في نهج المجموعة - مجموعات الأشياء.

يوضح المثال التالي نماذج الإدخالات والمخرجات:

تحويل XML إلى نص

يعرض قالب Liquid التالي مثالاً لتحويل XML إلى نص:

{{content.firstName | Append: ' ' | Append: content.lastName}}

يوضح المثال التالي نماذج الإدخالات والمخرجات:

اعتبارات قالب Liquid

• تتبع قوالب Liquid حدود حجم الملف للخرائط في تطبيقات Azure Logic.

• يتبع إجراء تحويل JSON إلى JSON عملية تنفيذ DotLiquid لـ Liquid. يعبر هذا التنفيذ عن منفذ إلى ‎.NET Framework من تنفيذ Shopify لـ Liquid، ويختلف في حالات محددة.

  تصف القائمة التالية الاختلافات المعروفة:

  • يقوم إجراء تحويل JSON إلى JSON في الأصل بإخراج سلسلة، والتي يمكن أن تتضمن JSON وXML وHTML وما إلى ذلك. يشير الإجراء Liquid فقط إلى أن إخراج النص المتوقع من قالب Liquid هو سلسلة JSON. يرشد الإجراء تطبيق المنطق الخاص بك إلى توزيع الإدخال كعنصر JSON، ويطبق برنامج تضمين بحيث يمكن لـ Liquid تفسير بنية JSON. بعد التحويل، يوجه الإجراء تطبيق المنطق إلى تحليل إخراج النص من Liquid مرة أخرى إلى JSON.

    لا يفهم DotLiquid في الأصل JSON، لذا تأكد من الابتعاد عن الحرف المائل العكسي (\) وأي أحرف JSON محجوزة أخرى.

  • إذا كان القالب يستخدم عوامل تصفية Liquid، فتأكد من اتباع اصطلاحات تسمية DotLiquid وC# التي تستخدم كتابة الجملة. بالنسبة لجميع تحويلات Liquid، تأكد من أن أسماء التصفية في القالب تستخدم أيضاً كتابة الجملة. وإلا، لن تعمل عوامل التصفية.

    على سبيل المثال، عند استخدام عامل التصفية replace، استخدم Replace، وليس replace. تنطبق نفس القاعدة إذا جربت أمثلة في DotLiquid عبر الإنترنت. لمزيد من المعلومات، راجع عوامل تصفية Shopify Liquid وعوامل تصفية DotLiquid Liquid. تتضمن مواصفات Shopify أمثلة لكل عامل تصفية، لذلك للمقارنة، يمكنك تجربة هذه الأمثلة في DotLiquid - حاول عبر الإنترنت.

  • عامل التصفية json من عوامل تصفية ملحق Shopify غير مطبق حالياً في DotLiquid. عادةً، يمكنك استخدام عامل التصفية هذا لإعداد إخراج النص لتحليل سلسلة JSON، ولكن بدلاً من ذلك، تحتاج إلى استخدام عامل التصفية Replace بدلاً من ذلك.

  • عامل التصفية القياسي Replace في تنفيذ DotLiquid يستخدم مطابقة التعبير العادي (RegEx)، بينما تطبيق Shopify يستخدم مطابقة سلسلة بسيطة. يبدو أن كلا التطبيقين يعملان بنفس الطريقة حتى تستخدم حرفاً محجوزاً من RegEx أو حرف إلغاء في معلمة المطابقة.

    على سبيل المثال، للخروج من حرف الخروج للشرطة المائلة العكسية المحجوزة لـ RegEx (\) استخدم | Replace: '\\', '\\'، وليس | Replace: '\', '\\'. توضح هذه الأمثلة كيفية تصرف عامل التصفية Replace بشكل مختلف عند محاولة الخروج من حرف الشرطة المائلة العكسية. بينما يعمل هذا الإصدار بنجاح:

    { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\\', '\\' | Replace: '"', '\"'}}"}

    مع هذه النتيجة:

    { "SampleText": "The quick brown fox \"jumped\" over the sleeping dog\\\\"}

    فشل هذا الإصدار:

    { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\', '\\' | Replace: '"', '\"'}}"}

    مع هذا الخطأ:

    { "SampleText": "Liquid error: parsing "\" - Illegal \ at end of pattern."}

    لمزيد من المعلومات، راجع استبدال عامل التصفية القياسي يستخدم مطابقة نمط RegEx....

  • يقوم عامل التصفية Sort في تنفيذ DotLiquid بفرز العناصر في صفيف أو مجموعة حسب الخاصية ولكن مع هذه الاختلافات:

    • يتبع سلوك sort_natural لـ Shopify، وليس سلوك فرز Shopify.

    • يتم الفرز بترتيب أبجدي رقمي للسلسلة فقط. لمزيد من المعلومات، راجع الفرز الرقمي.

    • يستخدم ترتيباً غير حساس لحالة الأحرف، وليس ترتيباً حساساً لحالة الأحرف. لمزيد من المعلومات، راجع عامل تصفية الفرز لا يتبع سلوك الكتابة من مواصفات Shopify.

الخطوات التالية

• لغة Shopify Liquid وأمثلة عليها
• DotLiquid
• DotLiquid - التجربة عبر الإنترنت
• DotLiquid GitHub
• مشكلات DotLiquid GitHub
• تعرف على المزيد عن الخرائط