توسيع وكيلك باستخدام أدوات من واجهة برمجة تطبيقات REST (معاينة)

[هذا المقال عبارة عن وثائق الإصدار التجريبي ويكون خاضع للتغيير.]

يمكنك استخدام واجهات برمجة تطبيقات REST (بما في ذلك OpenAI API) لتوصيل عامل تقوم بإنشائه مع الأنظمة الخارجية والوصول إلى البيانات المتاحة للاستخدام داخل وكيلك. يمكنك توصيل وكيلك بواجهة برمجة تطبيقات REST عن طريق تزويد Copilot Studio بثلاثة أشياء:

• مواصفات OpenAPI تحدد وظائف واجهة برمجة التطبيقات والإجراءات المتاحة
• تفاصيل حول نوع المصادقة المطلوبة وتفاصيل المصادقة للمستخدمين للاتصال بواجهة برمجة التطبيقات للوصول إلى النظام الخارجي
• أوصاف لمساعدة نموذج اللغة على تحديد وقت استدعاء واجهة برمجة التطبيقات لاستخدام البيانات

يمكنك إضافة واجهات برمجة تطبيقات REST إلى وكلاء Copilot والوكلاء المخصصين من خلال Copilot Studio.

مهم

تحتوي هذه المقالة على وثائق إصدار أولي Microsoft Copilot Studio وهي عرضة للتغيير.

ولا تُستخدم ميزات الإصدار الأولي في بيئة التشغيل وقد يتم تقيد بعض الوظائف بها. تتوفر هذه الميزات قبل الإصدار الرسمي حتى تتمكن من الحصول على وصول مبكر وتقديم التعليقات.

إذا كنت تقوم بإنشاء عامل جاهز للإنتاج، فشاهد نظرة عامة على Microsoft Copilot Studio.

تسمح عوامل Copilot للصانع بدمج مصادر بيانات متعددة مثل الموصلات وواجهات برمجة التطبيقات والمطالبات ومصادر المعرفة في عامل واحد. استخدم هذا العامل لتوسيع تجارب الوكيل ذات العلامة التجارية Microsoft مثل Microsoft 365 Copilot.

العوامل المخصصة هي عوامل مستقلة تحتوي على موصلات وواجهات برمجة تطبيقات ومطالبات ومصادر معارف. يمكنك استخدام وكلاء مخصصين مباشرة من خلال دمجهم في مواقع الويب أو القنوات الأخرى.

ملحوظة

يجب إنشاء أدوات REST API من مواصفات OpenAPI v2. يرجع هذا المطلب إلى سلوك Power Platform في معالجة مواصفات واجهة برمجة التطبيقات. إذا قمت بإرسال مواصفات v3، فإن عملية الإنشاء تترجمها تلقائيا إلى مواصفات v2.

Prerequisites

• بيانات الْاعتماد على مستوى المنشئ، وترخيص Copilot Studio.
• نسخة من مواصفات OpenAPI لواجهة برمجة تطبيقات REST التي تريد الاتصال بها
• معرفة نوع المصادقة اللازمة للاتصال بواجهة برمجة التطبيقات وتفاصيل المصادقة.

إضافة أداة REST API إلى وكيلك

لإضافة أداة REST API إلى عاملك، أكمل الخطوات التالية:

1. إضافة أداة عامل جديدة وتحديد REST API
2. توفير مواصفات واجهة برمجة التطبيقات ووصفها وحلها
3. توفير تفاصيل المصادقة
4. تحديد أدوات من واجهة برمجة التطبيقات
5. المراجعة والنشر

ترشدك الأقسام التالية خلال العملية خطوة بخطوة.

عملية إضافة واجهة برمجة تطبيقات REST هي نفسها لكل من العوامل المخصصة وعوامل Microsoft 365 Copilot.

إضافة أداة عامل جديدة وتحديد REST API

1. انتقل إلى صفحة نظرة عامة على وكيلك.

2. في قسم Tools ، حدد Add tool. يمكنك أيضا الانتقال إلى علامة التبويب أدوات وتحديد إضافة أداة.

   يتم عرض صفحة إضافة أداة .

3. حدد New tool>REST API.

توفير مواصفات واجهة برمجة التطبيقات ووصفها وحلها

1. قم بتحميل ملف مواصفات OpenAPI لواجهة برمجة تطبيقات REST التي تريد الاتصال بها. يمكنك إما سحب ملف المواصفات وإفلاته في شاشة Upload a REST API أو استعراض النظام لتحديد موقع الملف الذي ترغب في استخدامه.

   

   ملحوظة

   يجب أن تكون مواصفات OpenAPI عبارة عن ملف JSON بتنسيق الْإصدار 2. إذا قمت بإرسال مواصفات v3، فإن عملية الإنشاء تترجمها تلقائيا إلى مواصفات v2.

   بعد تحميل المواصفات، يتم تحديث الشاشة لإظهار اسم ملف المواصفات والتفاصيل.

   

   في الخطوات التالية، يستخدم الإجراء مثالا محددا على SunnyADO، وهو نظام إدارة تذاكر ADO. في المثال، الهدف هو السماح للمستخدمين باسترداد وتحديث تذاكرهم عبر العامل.

2. تحقق من التفاصيل، ثم حدد التالي.

   يتم تقديم صفحة تفاصيل المكون الإضافي لواجهة برمجة التطبيقات حيث يمكنك توفير معلومات إضافية حول واجهة برمجة التطبيقات.

   

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

   على سبيل المثال، الوصف الأولي المقدم هو: "خدمة بسيطة لإدارة التذاكر".

   أفضل وصف هو: "نظام يستخدم للحصول على التذاكر الموجودة من SunnyADO واستردادها والبحث عنها وعرضها. فهو يسمح للمستخدمين بتحديث التذاكر وتغييرها وإدارتها لتوفير المزيد من البيانات لتحسين السجلات."

3. أدخل وصفا محسنا ضمن حقل الوصف .

4. ضمن الحل، تسرد القائمة المنسدلة جميع الحلول المتوفرة داخل البيئة الحالية. حدد الحل الذي تريد استخدامه. تعرف على المزيد حول الحلول في مفاهيم الحل.

   

   إذا كان لديك حل مفضل، أو كان الموصل المحدد موجودا بالفعل في الحل، يتم تحديد هذا الحل تلقائيا.

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

   ملحوظة

   إذا كنت لا ترى الحل الافتراضي أو الحل الافتراضي ل CDS كخيار في هذه الحالة، أضف حلا مخصصا للإدارة السهلة. تعرف على المزيد في الحل الافتراضي مقابل الحل المخصص.

5. مع تحديد حل، حدد التالي للمتابعة.

توفير تفاصيل المصادقة

تظهر صفحة المصادقة . حدد نوع المصادقة المراد استخدامها لواجهة برمجة التطبيقات.

1. حدد أسلوب مصادقة من القائمة. حدد من بين ثلاثة خيارات:

   • بلا: لا توجد مصادقة مطلوبة للوصول إلى واجهة برمجة التطبيقات.
   • مفتاح API: حدد هذا الخيار إذا كانت واجهة برمجة التطبيقات تتطلب مفتاح API للمصادقة. في وقت التشغيل، عندما يريد العامل استخدام أداة API، يطالب العامل المستخدم بالمصادقة. يوفر المستخدم مفتاح API ويتصل العامل بواجهة برمجة التطبيقات باستخدام هذا المفتاح.
   • Auth 2.0: حدد هذا الخيار إذا كان خادم MCP يستخدم OAuth 2.0 للمصادقة. يتيح OAuth 2.0 للمستخدمين الفرديين المصادقة على واجهة برمجة التطبيقات عبر موفر الهوية. تتيح طريقة المصادقة هذه للمستخدم منح أذونات للتطبيق (العامل) دون مشاركة بيانات الاعتماد الخاصة به مع العامل.

2. أدخل الحقول المطلوبة لأسلوب المصادقة المحدد. تختلف الحقول استنادا إلى أسلوب المصادقة.

   • بلا: لا توجد معلومات لتوفيرها.
   • مفتاح واجهة برمجة التطبيقات:
     • تسمية المعلمة: تسمية نصية لمعلمة API لتقديمها للمستخدمين.
     • اسم المعلمة: الاسم الفعلي لمعلمة مفتاح API لاستخدامها إما في الرأس أو سلسلة الاستعلام.
     • موقع المعلمة: كيفية إرسال المفتاح لواجهة برمجة التطبيقات. حدد إما رأس أواستعلام.
   • Auth 2.0:
     • معرف العميل: معرف العميل الذي يصدره موفر الهوية عند تسجيل تطبيقك. يتيح معرف العميل لموفر الهوية معرفة التطبيق الذي يقوم بالطلب.
     • سر العميل: سر العميل الذي يصدره موفر الهوية عند تسجيل تطبيقك. يرسل وكيلك سر العميل مع معرف العميل لإثبات أن وكيلك مخول لطلب رموز الوصول المميزة لخادم MCP.
     • عنوان URL للتخويل: نقطة نهاية موفر الهوية حيث يعيد وكيلك توجيه المستخدم لتسجيل الدخول ومنح الأذونات إلى الوكيل (بطاقة الموافقة المقدمة في دردشة الوكيل). يصادق المستخدم هنا ثم يستجيب موفر الهوية مرة أخرى إلى العامل في عنوان URL لرد الاتصالبرمز تخويل.
     • عنوان URL للرمز المميز: نقطة النهاية حيث يتبادل الوكيل رمز التخويل (أو رمز التحديث المميز) لرمز مميز للوصولورمز التحديث المميز. يتيح الرمز المميز للوصول لعاملك استخدام خادم MCP نيابة عن المستخدم. تتيح الرموز المميزة للتحديث لوكيلك الحصول على رموز مميزة جديدة للوصول والتحديث من نقطة نهاية التحديث عند انتهاء صلاحية رمز الوصول السابق.
     • تحديث عنوان URL: نقطة النهاية لطلب رمز مميز جديد للوصول باستخدام رمز تحديث مميز (بحيث لا يتعين على المستخدم تسجيل الدخول مرة أخرى عند انتهاء صلاحية الرمز المميز).
     • النطاق: (اختياري): الأذونات التي يطلبها تطبيقك، كقائمة مفصولة بمسافة.
     • أي مؤسسة من Microsoft 365 يمكنها الوصول إلى نقاط النهاية: يحدد هذا الإعداد الوصول إلى المصدر إما لمؤسسة الصانع أو لجميع المؤسسات. حدد إما:
       • مؤسستي فقط
       • أي منظمات Microsoft 365
     • التطبيق (العميل) الذي يمكنه استخدام نقاط النهاية: GUID الذي يحدد نظام العميل الذي يمكن استخدامه للوصول إلى هذه البيانات. قد تتضمن التطبيقات Microsoft 365 Power Automate وخيارات أخرى.

3. عند إكمال كافة الحقول، حدد التالي.

   تظهر صفحة Select and configure your tool حيث يمكنك تحديد الأدوات لتمكينها من واجهة برمجة التطبيقات.

   

تحديد أدوات من واجهة برمجة التطبيقات

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

1. حدد أداة من القائمة لتكوينها.

   يتم عرض صفحة تكوين الأداة الخاصة بك .

   

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

3. بمجرد اكتمال الحقول، حدد التالي.

   يتم عرض صفحة مراجعة معلمات الْأداة الْخاصة بك .

   

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

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

5. بعد إكمال الأوصاف، حدد التالي.

   تم الآن تكوين الأداة الأولى وتظهر في قائمة الأدوات المحددة في صفحة تحديد أداة المكون الإضافي وتكوينها .

   

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

   يتم عرض صفحة مراجعة الأداة الخاصة بك . توفر الصفحة تفاصيل أداة REST API المكونة.

   

المراجعة والنشر

1. إذا كنت بحاجة إلى إجراء أي تحديثات، فحدد رجوع وقم بإجراء التغييرات. وإلا، فحدد التالي.

   تظهر شاشة تشير إلى أن الأداة الخاصة بك يتم نشرها أثناء العملية قيد التقدم. يتم إعلامك بمجرد اكتمال النشر.

2. حدد إنشاء اتصال للمتابعة. يتم إرجاعك إلى شاشة إضافة أداة .

3. حدد REST API في محدد نوع الأداة. يمكنك مشاهدة الأدوات التي تم إنشاؤها حديثا من واجهة برمجة التطبيقات الخاصة بك. يجب أن يكون هناك إدخال واحد لكل أداة أضفتها من واجهة برمجة التطبيقات.

4. لكل من الأدوات المكونة حديثا من واجهة برمجة التطبيقات، أنشئ أو حدد اتصالا بواجهة برمجة التطبيقات وأضف الأداة إلى وكيلك:

   1. في شاشة إضافة أداة ، حدد الأداة.
   2. ضمن اتصال، حدد اتصالا موجودا أو حدد إنشاء اتصال جديد.
   3. أدخل أي معلومات مطلوبة للاتصال، ثم حدد إنشاء لإنشاء الاتصال بالأداة.
   4. حدد إضافة وتكوين لإضافة الأداة إلى وكيلك.

   

الأدوات من واجهة برمجة تطبيقات REST متاحة الآن للاستخدام في وكيلك.

نصيحة

للعثور على الأداة بسهولة أكبر، استخدم شريط البحث لتحديد موقعها.