مقدمة

  • 12 دقائق

تستكشف هذه الوحدة النمطية الموصلات المخصصة وتوضح كيفية تكوينها واستخدامها مع Microsoft Power Apps وMicrosoft Power Automate وMicrosoft Azure Logic Apps.

في هذه الوحدة النمطية، ستقوم بما يلي:

  • تعرّف على دور الموصلات المخصصة.

  • قم ببناء موصل واستخدمه في تدفق Power Automate.

تساعد الموصلات على تسهيل قيام صانعي التطبيقات والتدفقات بالاتصال بالتطبيقات والبيانات والأجهزة الأخرى في المجموعة بالطرق التالية:

  • إجراء الاتصال بطريقة متناسقة وقابلة للتكرار ويمكن اكتشافها من قبل الصانعين.

  • تحتوي الموصلات على إجراءات تسمح للصانعين بالتحكم في الوقت الذي يتم فيه تنفيذ العملية.

  • يمكن أن يكون للروابط مشغلات تسمح ببدء تشغيل التنفيذ التلقائي عند حدوث الحدث المشغل.

رسم تخطيطي مع واجهة برمجة التطبيقات في المركز، محاطاً بالموصل ثم Power Automate وPower Apps وLogic Apps.

الموصل هو وكيل أو برنامج تضمين حول واجهة API‏ يسمح لتطبيقات Power Automate وPower Apps و"التطبيقات المنطقية من Azure" بالتواصل مع الخدمة الأساسية. العديد من الموصلات تكون معرفة مسبقاً ومتاحة للاستخدام دون الحاجة إلى تعريف أي شيء. وتتضمن تعريفات الموصلات المضمنة هذه خدمات من Microsoft وغيرها. عندما لا تحتوي الخدمة أو API التي تريد استخدامها على موصل تم إنشاؤه مسبقاً، يمكنك إنشاء الموصل المخصص الخاص بك. إذا كان الموصل الذي تم إنشاؤه مسبقاً لا يعرض كافة المشغلات والإجراءات التي تحتاجها من API، يمكنك إنشاء موصل مخصص بالإضافة إلى المتطلبات الإضافية المتوفرة لمعالجة هذه المتطلبات الإضافية. بعد تعريف الموصل المخصص، يصبح متوفراً للاستخدام عند إنشاء التطبيقات والتدفقات في تلك البيئة، والتي تشبه الموصلات المضمنة.

العملية عالية المستوى هي تعريف أو إنشاء API، ووصف API، واستخدام موصل وترخيص مصدر مفتوح.

تعريف أو إنشاء واجهة API

الهامة الأولى هي التحقق من مرجع الموصل لتحديد ما إذا كان يوجد بالفعل موصل مناسب للخدمة/API. في حالة عدم وجود موصل مناسب بالفعل، يمكنك إنشاء الموصل المخصص الخاص بك. يمكنك تحديد الموصل المخصص لوصف أي واجهة برمجة تطبيقات REST عامة (متوفرة على الإنترنت) أو خاصة (متوفرة فقط على الشبكة الداخلية). تتطلب واجهات API الخاصة بوابة البيانات الداخلية للوصول إلى الموارد الداخلية.

إذا كانت API المتوافقة غير موجودة بالفعل، يمكن للمطورين بناء واحدة باستخدام أي تقنية من اختيارهم قادرة على استضافة واجهة برمجة تطبيقات REST، بما في ذلك دالات Microsoft Azure وAzure App Services. يمكنك أيضا استخدام إدارة واجهة Azure API لزيادة إمكانية إدارة واجهات Azure API وحوكمتها.

وصف API

بالنسبة لـ Power Apps وPower Automate من أجل اكتشاف المشغلات والإجراءات المتوفرة من API، يجب عليك تعريفها عند إنشاء الموصل المخصص. يمكنك إنجاز هذه الهامة بتحرير تعريف الموصل في مدخل الصانع يدوياً أو عن طريق استيراد تعريف بتنسيق معتمد. تتضمن هذه العملية تعريف متطلبات المصادقة لـ API.

استخدام الموصل

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

ترخيص ومشاركة الموصل كمصدر مفتوح

ونظرا لأن الموصلات المخصصة تكون متاحة فقط في البيئات التي يوجد بها تعريفاتها، فلن تكون متوفرة لعملاء Microsoft الآخرين. عن طريق مشاركة تعريف موصل مخصص كمصدر مفتوح، فإنك تجعله متاحاً في GitHub للعملاء الآخرين ليقوموا باستيراده إلى بيئاتهم. ومن خلال ترخيص الموصل الخاص بك، يمكنك جعل الموصل المخصص الذي قمت بإنشائه متوفراً كموصل تم إنشاؤه مسبقاً في كافة بيئات العملاء. يتطلب ترخيص الموصل أن تكون لديك واجهة API أو لديك إذن صريح لنشر موصل من مالك واجهة API.

للحصول على مزيد من المعلومات، راجع عملية المصادقة.

تعتبر هذه الخطوة في العملية اختيارية وتكون مطلوبة فقط إذا كنت ترغب في مشاركة الموصل وإدراجه في قائمة الموصلات المصدقة. لا تحتاج الموصلات الخاصة بالواجهة الداخلية إلى إكمال عملية المصادقة هذه.

وصف الموصل

لتحديد إجراءات الموصل ومشغلاته، تحتاج إلى وصف الموصل. يمكن تعريف موصل مخصص عن طريق وصف مشغلات وإجراءات API التي تحتاجها فقط. على سبيل المثال، إذا كانت واجهة API تحتوي على 100 إجراء و10 مشغلات متوفرة، يمكنك إنشاء موصل مخصص مع إجراء واحد. كما يمكنك وصف لاحقاً حسب عدد الاحتياجات التي تتغير.

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

  • الإنشاء يدويا في المدخل عند استخدام هذا الأسلوب، يمكنك استخدام وثائق API وأمثلة على الإدخالات والإخراجات ثم قم بتعريف كل اجراء ومشغل. هذا الأسلوب مناسب لواجهات API البسيطة حيث لا تملك القدرة على استيراد التعريف. يمكنك أيضاً استخدام هذا الأسلوب لتنقيح التعريفات بعد استيرادها.

  • استيراد تعريف OpenAPI الخاص - OpenAPI هي عبارة عن مواصفات تصف REST، من خلال تبسيط مهام تطوير API واستخدامها من خلال تعيين كافة الموارد والعمليات المقترنة بها بفاعلية. العديد من الخدمات/واجهات API تقوم بنشر تعريف OpenAPI، ويمكنك استيراده لوصف واجهة API في الموصل المخصص. يتم دعم استيراد الإصدار 2.0، ولكن الإصدار 3.0 غير مدعوم حالياً. يعتبر هذا الأسلوب مفيداً في حالة توفر تعريف OpenAPI من ناشر API أو، إذا كنت تقوم بتطوير API، يمكنك نشر واحدة.

  • استيراد من GitHub - قم باستيراد الموصلات من مستودع موصلات Power Platform. هذه هي أفضل طريقة عندما يكون هناك بالفعل موصل منشور في المستودع وتريد استيراده لتعديله أو استخدامه كموصل مخصص.

  • تصدير من Azure - إذا كانت واجهة API الخاصة بك مبنية كخدمة تطبيق Azure أو دالات Microsoft Azure أو تتم إدارتها بواسطة إدارة API من Microsoft Azure، فيمكنك التصدير من هذه الخدمات وستقوم تلقائياً بإنشاء تعريف الموصل المخصص الأولي.

العمل باستخدام واجهات API المصدقة

بنية الموصل المخصص تدعم استخدام واجهات API المصدقة. عند تعريف الموصل المخصص، ستقوم بتعريف كيفية المصادقة على API. تعتمد اختيارات المصادقة الوصول المجهول والمحمي بكلمة مرور وOAuth 2.0 وباستخدام مفتاح API.

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

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

  • OAuth 2.0 - OAuth 2.0 هو البروتوكول القياسي في المجال للتخويل. يمكن تكوين هذا الخيار لأي واجهة API تستخدم OAuth 2.0. وتتوفر لك التكوينات التي تم إنشاؤها مسبقاً للاختيار من بينها لخدمات Microsoft، مثل Microsoft Entra ID، وGitHub، وAzure DevOps. وتتوفر التكوينات التي تم إنشاؤها مسبقاً المشابهة لخدمات أخرى، مثل Dropbox وSlack وStripe وغيرها. تبسط التكوينات التي تم إنشاؤها مسبقاً ما تحتاج إلى توفيره لتكوين موفر الهوية.

  • مفتاح API - يعتبر مفتاح API رمزاً مميزاً يوفره العميل عند اجراء استدعاءات API. ويوفر أيضاً ناشر API المفتاح عادة، ويجب تضمينه في كل طلب من الموصل المخصص.

تساعد الموصلات المخصصة على تسهيل استخدام واجهات API/خدمات لصانعي التطبيقات والتدفق. في أغلب الأحيان، يمكن للصناع استدعاء API مباشرة بدون موصل؛ ومع ذلك، سيكون عليهم معرفة كيفية تأليف الطلب وتفسير النتائج ثم معالجة المصادقة. يجب إكمال هذه العملية في كل مرة يستخدم فيها التطبيق أو التدفق موصلات مخصصة.

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

توضح الوحدة التالية كيفية إنشاء موصل مخصص.