التَمرين: إنشَاء واجهة برمجة تطبيقات (API)‏ مخصصة

  • 15 دقائق

فِي هذا التَمرين، ستقوم بإنشَاء واجهة API مخصصة فِي Dataverse لتطبيق بعض المِنطق المخصص. بعد ذلك، ستستخدم واجهة API المخصصة مِن خطوة فِي تدفق Power Automate.

هام

استخدم بيئة اختبار مع توفِير Microsoft Dataverse. إذا لم يكن لديك واحدة، يمكنك الاشتراك فِي خطة المجتمع.

المهمة 1: إنشَاء مشروع واجهة API المخصصة

  1. تنزيل وتثبيت Power Platform CLI.

  2. قم بتشغيل الملف powerapps-cli لبدء التثبيت.

  3. استخدم معالج الإعداد لإكمال الإعداد وحدد إنهاء.

  4. افتح موجه الأوامر.

  5. شغّل الأمر التالي لإنشَاء مجلد جَديد يسمى CustomAPILab.

    md CustomAPILab

  6. قم بتغيير الدليل إلى المجلد الذي قمت بإنشائه.

    cd CustomAPILab

  7. مِن المفترض أن تكون الآن فِي المجلد CustomAPIlAB. شغّل الأمر أدناه لتهيئة مكتبة فئات جَديدة للمكون الإضافِي Dataverse.

    pac plugin init

  8. يجب أن يكون إنشَاء مكتبة فئات المكون الإضافِي Dataverse ناجحاً.

    لقطة شاشة توضح مكتبة فئات المكون الإضافِي التي تم إنشاؤها.

  9. شغّل الأمر أدناه لفتح المشروع فِي Visual Studio.

    start CustomAPILab.csproj

  10. مِن المفترض أن يفتح المشروع فِي Visual Studio.

  11. انقر بزر الماوس الأيمِن فوق ملف Plugin1.cs وأعد تسميته إلى MatchPlugin.cs.

  12. حدد نعم لإعادة تسمية حوار ملف.

  13. انقر بزر الماوس الأيمِن فوق المشروع CustomAPILab وحدد إدارة حزم NuGet.

  14. ابحث عن System.Text.RegularExpressions وحدد تثبيت.

    لقطة شاشة توضح حزمة NuGet التي تم تثبيتها.

  15. افتح الملف MatchPlugin.cs.

  16. أضف العبارة التالية أدناه.

    using System.Text.RegularExpressions;

  17. أضف الأسطر التالية داخل أسلوب ExecuteDataversePlugin وبعد سطر السياق var. تحصل هذه الأسطر عَلى القيمة مِن معلمات الإدخال التي تمّ تمريرها عَلى استدعاء واجهة API المخصصة.

    string input = (string)context.InputParameters["StringIn"];

    string pattern = (string)context.InputParameters["Pattern"];

  18. أضف السطر التالي للحصول عَلى خدمة التتبع.

    ITracingService tracingService = (ITracingService)localPluginContext.ServiceProvider.GetService(typeof(ITracingService));

  19. أضف السطر أدناه لكتابة قيمة الإدخال فِي التتبع.

    tracingService.Trace("Provided input: " + input);

  20. قم بإضافة السطر التالي لاحقًا لاستدعاء طريقة Regex.Match.

    var result = Regex.Match(input, pattern);

  21. اكتب النتيجة لتتبعها.

    tracingService.Trace("Matching result: " + result.Success);

  22. وأخيرًا، قم بإضافة السطر التالي لتعيين معلمة الإخراج باعتبارها "مطابقة".

    context.OutputParameters["Matched"] = result.Success;

  23. يجب أن تبدو طريقة التطبيق الخَاصة بك الآن كالتالي.

    لقطة شاشة تعرض أسلوب تطبيق المكون الإضافِي.

  24. حدد بناء > بناء حل.

  25. يجب أن يتم بناء المشروع بنجاح.

المهمة 2: تسجيل المكون الإضافِي لواجهة API المخصصة

  1. افتح موجه الأوامر وقم بتشغيل الأمر أدناه لتشغيل Plugin Registration Tool.

    pac tool prt

  2. حدد + إنشَاء اتصال جَديد.

  3. حدد Office 365، وقدم بيانات اعتمادك، ثم حدد تسجيل الدخول.

  4. حدد البيئة الصحيحة.

  5. اختر تسجيل | تسجيل تجميع جَديد.

    لقطة شاشة تظهر النقر فوق

  6. حدد ... ثم تصفح إلى المجلد CustomAPILab\bin\Debug\net462 folder.

  7. حدد CustomAPILab.dll.

  8. حدد مُوَافق.

    لقطة شاشة تُظهر مربع حوار

  9. حدد تسجيل المكونات الإضافِية المُحددة.

  10. حدد مُوَافق فِي رسَالة النجاح. المكون الإضافِي الخَاص بك جاهز للاتصال بواجهة API المخصصة التي سنقوم بإنشائها فِي المهمة التالية.

المهمة 3: إنشَاء واجهة API المخصصة

  1. انتقل إلى Power Apps Maker Portal وتأكد مِن وجودك فِي البيئة الصحيحة.

  2. حدد الحلول فِي جزء التنقل الأيمِن.

  3. حدد + حل جَديد.

  4. أدخل معمل واجهة API مخصصة فِي اسم العرض.

  5. حدد ناشر CDS الافتراضي فِي القائمة المِنسدلة "الناشر".

  6. حدد إنشَاء. يؤدي هذا إلى إنشَاء حل مُخصص يشتمل عَلى مكوناتنا.

  7. حدد + جَديد | المزيد | أخرى | API مخصصة

  8. أدخِل المعلومات التالية:

    • الاسم الفريد: contoso_match

    • الاسم: تطابق

    • اسم العرض: تطابق

    • الوصف: تطابق سلسلة

    • نوع الربط: عمومي

  9. فِي "نوع المكون الإضافِي" حدد رمز البحث وحدد موقع المكون الإضافِي.

    لقطة شاشة تظهر حوار واجهة API المخصصة مع ملء الحقول.

  10. حدد حفظ وإغلاق.

  11. حدد تم.

  12. حدد +جَديد | المزيد | أخرى | معلمة طلب واجهة API المخصصة.

  13. بالنسبة لـ واجهة API المخصصة، حدد الرمز بحث وحدد مطابقة (واجهة API المخصصة الخَاصة بك).

  14. أدخل StringIn للاسم الفريد، والاسم، واسم العرض، والوصف مِن أجل البساطة.

  15. حدد سلسلة للنوع.

  16. حدد حفظ وإغلاق.

  17. حدد تم.

  18. كرر الخطوات 13-17 وأضف معلمة طلب واجهة API مخصصة أخرى باسم النمط.

  19. حدد جَديد | المزيد | أخرى | خاصية استجابة واجهة API المخصصة.

  20. بالنسبة لـ واجهة API المخصصة، حدد الرمز بحث وحدد مطابقة (واجهة API المخصصة الخَاصة بك).

  21. أدخل تمت المطابقة للاسم الفريد، والاسم، واسم العرض والوصف مِن أجل البساطة.

  22. حدد مِنطقة لـ النوع.

  23. حدد حفظ وإغلاق.

  24. يجب أن تبدو قائمة مكون الحل لديك كالتالي.

    لقطة شاشة تظهر مكونات الحل بعد إنشَاء جميع معلمات واجهة API والطلب والاستجابة.

المهمة 4: استخدَام واجهة API مخصصة مِن Power Automate

  1. فِي الحل حدد + جَديد | التطبيق التلقائي | Cloud Flow | فوري.

    لقطة شاشة تظهر الزر إنشَاء Cloud Flow فوري.

  2. أدخل مطابقة السلسلة للاسم Flow، ثم حدد المشغّل تشغيل تدفق يدوياً، وحدد إنشَاء.

  3. حدد + خطوة جَديدة.

  4. ابحث عن التطبيق واختر تطبيق إجراء غير مرتبط.

    لقطة شاشة تظهر اختيار التطبيق وإجراء غير مرتبط.

  5. فِي قائمة "اسم الإجراء"، حدد contoso_match.

  6. أدخل أي عنوان بريد إلكتروني صالح فِي StringIn.

  7. أدخل التعبير العادي التالي فِي "النمط". هذا هو نمط بسيط للبريد الإلكتروني. تتوفر أمثلة أخرى.

    ^\w+@[a-zA-Z_]+?\.[a-zA-Z]{2,3}$

  8. يجب أن يبدو التَدفُّق الخَاص بك كالتالي.

    لقطة شاشة تظهر التَدفُّق مع زر التشغيل وخطوة تطبيق إجراء غير مرتبط.

  9. حدد حفظ.

  10. بعد اكتمال الحفظ، حدد اختبار.

  11. حدد يدوياً ثم حدد اختبار.

  12. حدد تشغيل التَدفُّق.

  13. حدد تم.

  14. بعد اكتمال التَدفُّق، حدد تطبيق إجراء غير مرتبط للتوسيع ورؤية النتائج.

    لقطة شاشة تُظهر نتائج تشغيل التَدفُّق.

لقد أكملت الآن إنشَاء إجراء مخصص واستخدَامه مِن تدفق Power Automate. يتوفر الآن إجراء واجهة API المخصصة contoso_match أيضا للاستدعاء مباشرة باستخدَام واجهة API للنظام الأساسي.