استخدام السياسات لتحويل البيانات
يُمكن استخدام قوالب السياسات من أجل تحويل البيانات من بنية إلى أُخرى. ويتم إجراء هذه العملية عادة من أجل تبسيط مهمة الصانع لاستخدام مُوصل مُخصص من أجل توفير البيانات للإجراءات، أو للعمل باستخدام بيانات الاستجابة من نتائج الإجراء. فمثلاً، قد تُوفر واجهة برمجة التطبيقات (API) قائمةً مفصولةً بفواصل تشمل المُستخدمين الذين يحق لهم الوصول إلى السجل. قد يجعل تحويل هذه القائمة إلى مصفوفة من الأسهل استخدام القائمة في تطبيق، أو تدفق. قوالب السياسات التالية التي تدعم حاليًا تحويل بنيات البيانات:
تحويل مصفوفة إلى كائن
تحويل كائن إلى مصفوفة
تحويل سلسلة مُحددة إلى مصفوفة كائنات
يُمكن تشغيل كل سياسة مُقابل الطلب (بيانات الإدخال)، أو الاستجابة (بيانات الإخراج) من إجراء واحد أو أكثر. عندما تُشغل سياسة عند الطلب، فأنت تُشكّل البيانات التي يُوفرها الصناع من أجل تحديد كيف تريد واجهة برمجة التطبيقات رؤيتها. فمثلاً، يستخدم مُوصّل Microsoft Planner مصفوفة التحويل لكائن على إجراء تفاصيل مهمة التحديث. يُتيح هذا الإجراء للمُستخدم توفير مصفوفة من الارتباطات المرجعية الخارجية ثم إقرانها بالهامة. يتم تزويد المُستخدمين بواجهة سهلة الاستخدام تُتيح لهم إضافة ارتباطات مُتعددة عن طريق تحديد إضافة عنصر جديد من خلال السماح للصانع بتحديدها باعتبارها مصفوفة.
يُمكنك رؤية كيفية تنظيم البيانات وسيتم تقديمها إلى واجهة برمجة التطبيقات إذا لم يتم إجراء أي تحويلات بواسطة قوالب السياسة على المُوصّل، وذلك إذا كنت تستخدم ميزة نظرة خاطفة في خطوة الإجراء.
إذا نظرت إلى واجهة API Microsoft Planner المستندات لهذه العملية، لاحظ أنها تريد تنظيم البيانات مثل المثال التالي.
يتم تكوين المُوصّل إلى قوالب سياسات مُتعددة لتحويل البيانات، وذلك من أجل تحويل ما تم توفيره بواسطة إجراء التدفق إلى ما تتوقعه واجهة برمجة التطبيقات. يتم استخدام قوالب السياسة على النحو التالي:
تعيين - لتعيين الحقل previewPriority إلى "!"
تعيين الخاصية - لتعيين التعبير @odata.type
تحويل المصفوفة إلى كائن - لإعادة تشكيل المصفوفة، وتضمين النوع والاسم المستعار كخصائص
قد تشبه سياسة تحويل مصفوفة المثال التالي.
تُتيح لك قوالب السياسة التي تعمل على الاستجابة إعادة تشكيل الناتج من واجهة برمجة التطبيقات. مثلاً، تتضمن استجابة Contoso Invoicing من إجراء الحصول على فاتورة الخاص بها قائمة علامات مفصولة بفاصلة منقوطة باعتبارها جزءًا من كائن الفاتورة. تُشبه البيانات التي يتم إرجاعها من واجهة برمجة التطبيقات لقطة الشاشة التالية.
تُعتبر أي سلسلة ذات قيم مُتعددة أصعب لعمل التطبيقات والتدفقات معها من أي مصفوفة. يُمكنك استخدام قالب سياسة تحويل سلسلة مُحددة في الاستجابة، من أجل تحسين إمكانية الاستخدام. يعرض المثال التالي قالب السياسة الذي قد تكونه.
سيؤدي هذا الإجراء إلى إضافة مصفوفة جديدة باسم taglist إلى الاستجابة، حسبما هو موضح في الصورة التالية.
يُمكنك الآن مُراجعة بعض تفاصيل التكوين الرئيسية بعد أن استكشفت بعض الأمثلة على قوالب السياسة قيد الاستخدام. تُحدّد المعلمة عمل السياسة بناءً على إذا ما كانت السياسة تنطبق على الطلب، أو الاستجابة. إذا كنت بحاجة إلى كليهما، فستحتاج إلى تكوين قالبين للسياسة.
يحتوي كل قالب سياسة تحويل على كائن مُستهدف أو معلمة تحصيل. يمنح هذا العامل نقطة البداية، حيث سيحصل منطق السياسة على البيانات التي يتعين تحويلها. تتمثل نقطة البداية الأكثر شيوعًا في استخدام التعبير @body()؛ الذي يُشير إلى نص الطلب، أو الاستجابة. يُعد التعبير @body() في المثال التالي كائنًا وله خاصية تُسمى علامات.
بدلاً من ذلك، إذا كانت الاستجابة عبارة عن كائن ذي خاصية تُسمى الفواتير التي كانت عبارة عن مصفوفة من كائنات الفواتير، وكل منها ذات خاصية علامات، قد يكون التكوين مُشابهًا للصورة التالية.
تأكد من تطبيق السياسات فقط على الإجراءات من خلال بيانات الطلب/الاستجابة التي تُطابق هذه التكوينات في أثناء تكوينك للسياسات. فمثلاً، قد يحتاج الإجراء الحصول على فاتورة، الذي يُرجع كائن فاتورة واحد، إلى قوالب سياسة مُختلفة مُطبقة بخلاف الإجراء إدراج فاتورة، الذي يُرجع مصفوفة من كائنات الفاتورة. إذا كنت تُضيف قوالب سياسة إلى مُوصّل حالي مع تمكين جميع الإجراءات، فتأكد من اختبار جميع الإجراءات والمحفزات لضمان أنها تعمل مع السياسة الجديدة.
تأكد من إعادة استيراد بيانات العينات في استجابة الإجراء، بعد تكوين قوالب سياسة الاستجابة. هذه الخطوة مطلوبة حتى تتمكن التطبيقات والتدفقات من رؤية البيانات المُحولة.
إذا أدى تكوينك لنموذج سياسة إلى إنشاء خطأ، فسترى عادةً في المُختبر كحالة HTTP من 500 أو سيفشل في إجراء أي مُعالجة. على الرغم أنه من غير المُمكن تعطيل سياسة، يُمكنك إزالة إجراء من قائمة العمليات للسماح للاختبار بالعزل إذا كانت السياسة تتسبب في حدوث مُشكلات. تُوضح الصورة التالية عمليتين مُحددتين فقط.
توفر قوالب سياسة التحويل نهجًا يُركز على التكوين من أجل تحويل البيانات إلى واجهة APIك الأساسية ومنها. يُمكن استخدامها لجعل استخدام إجراءات المُوصّل الخاص بك أسهل.