مقدمة

  • 4 دقائق

تستخدم موصلات Microsoft Power Platform المخصصة OpenAPI (تعرف أيضا باسم Swagger) لوصف المصادقة والإجراءات والمشغّلات والمعلمات الخاصة بها. تسمح لك مواصفات OpenAPI بتعريف الملحقات التي تزيد التعريف الأساسي لمعالجة سيناريوهات محددة. قامت Microsoft بتعريف العديد مِن الملحقات إلَى تعريف OpenAPI للسماح لك بتكوين ميزات محددة مدعومة بواسطة موصلات مخصصة.

يمكنك تعريف كل ملحق عن طريق البحث عن x-ms-<name> فِي تعريفات OpenAPI. لقد استخدمت بالفعل بعض هذه التعريفات عندما قمت بتكوين رابط مخصص مع المصمم، مثل إدخال ملخص عَلى معلمة الإجراء التي تستخدم امتداد x-ms-summary لتخزين القيمة فِي التعريف. يمكن تحرير ملحقات متعددة إما مباشرة مِن خلال محرر Swagger الخاص بالمصمم أو عن طريق تصدير تعريفات الموصل ثم تحريرها واستيرادها مره أخرى. يمكنك العثور عَلى قائمة كاملة بالملحقات المعتمدة للموصل المخصص.

توضح هذه الوحدة النمطية الملحقات التالية واستخداماتها:

  • x-ms-capabilities - يستخدم عَلى تعريف مستوى العملية والموصل للإشارة إلَى الميزات التي تم تقديمها.

  • x-ms-encoding - يحدّد الترميز لمعلمة مسار.

  • x-ms-dynamic-values وx-ms-dynamic-list - يوفر قائمة بالخيارات الخاصة بالمستخدم لتحديد معلمات الإدخال لإحدى العمليات.

  • x-ms-dynamic-schema - يسمح لك بجعل المعلمات والاستجابة حيوية استنادًا إلَى نتائج المخطط الذي يتم استرداده مِن عملية عَلى واجهة API.

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

خذ فِي الاعتبار أن بعض الملحقات تتطلب أيضًا دعمًا مِن API. على سبيل المثال، يتطلب المخطط الديناميكي مِن واجهة API دعم عملية استرداد المخطط. في الحالات التي لا تتحكم فِي واجهة API (API)، قد لا يمكن تكوين هذه الأنواع مِن الملحقات.

تكوين الملحقات

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

  • استيراد OpenAPI - عند استيراد ملف OpenAPI، بإمكان هذا الملف أن يحتوي عَلى ملحقات Microsoft OpenAPI.

  • Microsoft Power Platform Connectors CLI - باستخدام أداه سطر الأوامر paconn، يمكنك تنزيل ملف تعريف API وتحريره باستخدام محرر JSON المفضل. عند الانتهاء مِن التحرير، يمكنك استخدام paconn لتحميل التعريفات المعدلة مرة أخرى إلَى البيئة الخاصة بك. يعتبر هذا الأسلوب هو الأفضل عندما تحتاج إلَى اجراء تغييرات أخرى علي ملف خصائص API لمعلمات الاتصال، عَلى سبيل المثال.

  • Microsoft Power Platform Connectors CLI - باستخدام أداه سطر الأوامر paconn، يمكنك تنزيل ملف تعريف API للموصلات المخصصة باستخدام محرر JSON المفضل. عند الانتهاء مِن التحرير، يمكنك استخدام CLI لتحميل التعريفات المعدلة مرة أخرى إلَى الحل الخاص بك. يعتبر هذا الأسلوب هو الأفضل عندما تحتاج إلَى اجراء تغييرات أخرى علي ملف خصائص API لمعلمات الاتصال، والموصل المخصص فِي الحل.

  • محرر Swagger المضمن - يحتوي مصمم الموصل المخصص عَلى محرر OpenAPI، مضمن وهو أسرع طريقة لإضافة ملحقات OpenAPI.

استخدام محرر Swagger

يمكنك جعل محرر سواجير مرئيا عن طريق تشغيل مفتاح التبديل محرر Swagger لأي مِن الخطوات الموجودة فِي المصمم المخصص.

لقطة شاشة توضح كيفية تمكين محرر Swagger.

عندما يكون المحرر مقصوداً، فان تعريف OpenAPI بلغة YAML Ain't Markup Language (YAML)‎ سيتم عرضه عَلى اليسار، وسيتم عرض رسائل التحقق مِن الصحة (ان وجدت) وقائمة العمليات عَلى اليمين.

لقطة شاشة لمحرر Swagger قيد الاستخدام مع YAML علي اليسار وقائمة عمليات عَلى اليمين.

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

تحتوي معظم التغييرات التي ستقوم بها عَلى مثال للبدء منه. يعد المكان المناسب حيث يمكن البحث عن التغييرات فِي YAML موجوداً فِي الموصلات الأخرى الموجودة فِي مستودع GitHub لموصل Microsoft Power Platform. على سبيل المثال، إذا كنت ترغب فِي تطبيق ملحق x-ms-capability، يمكنك البحث فِي المستودع ومشاهدة كيفية تكوين الموصلات الأخرى.

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

لقطة شاشة تظهر أخطاء فِي عملية التحقق مِن الصحة فِي المحرر.

تلميحات للعمل مع YAML فِي محرر swagger:

  • المسافة البادئة مهمة - المسافة البادئة هي جزء مِن مواصفات YAML؛ ولذلك، لاحظ كيفية استخدام المسافة البادئة لتوفير تفاصيل التكوين.

  • الأقواس المفتوحة والمغلقة {} - إذا كان لديك قوس مفتوح {، فيجب أن يكون لديك قوس مغلق }.

  • الأقواس المفتوحة والمغلقة [] - إذا كان لديك قوس مفتوح، فيجب أن يكون لديك قوس مغلق .

  • Ctrl + F للبحث -يسمح لك مفتاح الاختصار هذا بالبحث داخل YAML.

  • Ctrl + Z للتراجع - إذا لاحظت أنك قمت بخطأ ما، فان استخدام اختصار لوحة المفاتيح Ctrl + Z سيتراجع عن التغيير الأخير.

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