استخدام ملحقات OpenAPI

مكتمل

تستكشف هذه الوحدة كيفية استخدام ملحقات Microsoft OpenAPI ‏وهما x-ms-capabilities وx-ms-url-encoding فِي موصلاتك المخصصة.

يساعدك الملحق x-ms-features عَلى تكوين القدرات التي يوفرها الموصل عَلى مستوى الموصل ومستوى التشغيل. في الوقت الحالي، يمكن تكوين موصلات Microsoft Power Platform المخصصة للخيارات التالية:

• chunkTransfer - مستوى التشغيل

• testConnection - مستوى الموصل

تمكين نقل المجموعة

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

لكي يستخدم الموصل المخصص نقل المجموعة، يلزم توفر المعلمات التالية:

• يجب أن تدعم API التقسيم. لمزيد مِن المعلومات، راجع معالجة الرسائل المقسمة للموصلات.

• يجب أن يقوم الموصل المخصص بتمكين ملحق إمكانية نقل المجموعة فِي الإجراء.

• يجب أن يقوم الصانع الذي يستخدم إجراء الموصل لديك بتمكين نقل المجموعة لخطوة التدفق.

في تعريف الموصل المخصص الخاص بك، يمكنك إضافة المنطق التالي إلَى تعريف العمليات التي تريد تمكين نقل المجموعة لها.

{chunkTransfer: true}

إذا كنت تعمل مع ملف apiDefinition.swagger.json الذي تم تنزيله بدلاً مِن محرر YAML، فستقوم بإجراء التغيير الذي يظهر فِي لقطة الشاشة التالية.

بعد إجراء هذا التغيير، لن تظهر إشارة إلَى التغيير فِي مصمم الموصل المخصص. وعلى الرغم مِن ذلك، فعند استخدام الإجراء فِي التدفق، سيتم عرض الخيار السماح بالتقسيم التالي فِي إعدادات الخطوة.

بافتراض أن API تدعمه، فبعد تمكين التقسيم، ستعمل الرسائل الكبيرة الآن ويتم نقلها باستخدام التقسيم.

تكوين اتصال الاختبار

بشكل افتراضي، عند إنشاء اتصال باستخدام موصل مخصص، لا يتم التحقق مِن صحة الاتصال أم لا. على سبيل المثال، إذا قدمت عنوان URL لمضيف غير صالح أو مفتاح API غير صالح، فيمكنك إنشاء اتصال، لكنه سيفشل فِي النهاية عند استخدام الاتصال. باستخدام الملحق testConnection الخاص بـ OpenAPI، يمكنك تحديد عملية عَلى الموصل المخصص الذي سيتم تشغيله أثناء إنشاء الاتصال للتحقق مِن صحة التكوين المقدم.

لتنفيذ اختبار الاتصال، يجب أن تكون لديك عملية بسيطة محددة عَلى الموصل المخصص الذي يقوم بإرجاع HTTP 200 (نجاح). يمكن أن تكون هذه العملية عملية موجودة قمت بتكوينها بالفعل، أو يمكنك إنشاء واحدة خصيصاً لاختبار الاتصال. إذا قمت بتكوين عملية اختبار معينة، فإننا نوصي بوضع علامة عليها عَلى أنها داخلية حتى لا يحاول المستخدمون استخدامها. يمكنك أيضاً تمرير معلمات ثابتة للعملية. على سبيل المثال، إذا كان الإجراء الذي اتخذته يتطلب معلمة $top للحد مِن عدد السجلات التي تم إرجاعها، فيمكنك استخدام المعلمات لقصر النتائج عَلى سجل واحد.

يوضح المثال التالي عملية ListInvoices التي تم تعريفها وكيف سيتم استخدامها لاختبار الاتصال، ويظهر تكوين الملحق testConnection.

سيبدو تحرير apiDefinition.swagger.json مشابهاً للصورة التالية.

تكوين مسار الترميز

ينطبق الملحق x-ms-url-encoding عَلى المعلمات المضمنة فِي مسار عنوان URL للطلب.

على سبيل المثال، يمكنك تحديد إجراء لإعادة العملاء حسب البلد/المنطقة بالطلب التالي:

https://myapi.myservice.com/customers/{country}

في هذا الإجراء، ستصبح البلد معلمة يتم توفيرها بواسطة مستخدم الموصل. ولأن هذه المعلمات جزء مِن المسار، فيجب أن يتم ترميزها بعنوان URL. بشكل افتراضي، تكون معلمات المسار مرمزة بعنوان URL واحد. ومع ذلك، فِي سيناريوهات معينة، قد تتوقع API الأساسية أن تكون المعلمات مرمزة بعنوان URL مزدوج لحل الغموض المحتمل الذي يتم تقديمه بواسطة أحرف معينة مثل العلامة (@) والشرطة المائلة (/) والشرطة المائلة للخلف (\)، وهكذا.

لتكوين ترميز مزدوج عَلى معلمة مسار، يمكنك إضافة الخيار التالي إلَى المعلمة:

x-ms-url-encoding: double

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

عند تشغيل تدفق Microsoft Power Automate الذي يستدعي كلا الإجراءين بإدخال معقد، فإن الترميز المزدوج يمرر نفس قيمة النص إلَى واجهة برمجة التطبيقات، باستثناء أنه أصبح الآن مزدوج التشفير.

يبسط هذا الامتداد معالجة المعلمات حيث تتوقع API ترميز عنوان URL مزدوج لأن مستخدم الموصل لا يحتاج إلَى ترميز معلمات المسار عند استدعاء الإجراءات.