إعداد مصادقة Microsoft لاختبار Copilot Studio Kit

توفر هذه المقالة نظرة عامة على إطار عمل اختبار العامل وإرشادات خطوة بخطوة لإعداد مصادقة Microsoft لاختبار عوامل Copilot Studio باستخدام Agent Test Runner Power Apps Component Framework (PCF).

التصميم

توفر مصادقة Microsoft بنية SDK مبسطة من متصفح إلى وكيل تم تحسينها لاختبار السيناريوهات. يتيح هذا الأسلوب الاتصال الآمن بين بيئة الاختبار ووكلاء Copilot Studio دون الحاجة إلى بنية أساسية إضافية للمصادقة.

بنية التدفق

يوضح الرسم التخطيطي للتسلسل التالي تدفق تنفيذ المصادقة والاختبار.

بنية المكون

يوضح الرسم التخطيطي التالي المكونات الرئيسية المتضمنة في تدفق المصادقة لـ Microsoft لمشغل اختبار العامل.

إعداد مصادقة Microsoft

تتضمن عملية الإعداد تسجيل التطبيق في مدخل Azure، والحصول على معرفات العامل من Copilot Studio، وإنشاء سجل تكوين في Dataverse.

مدخل Azure

في مدخل Azure، أنشئ تسجيل تطبيق، وأضف عنوان URL لإعادة التوجيه، وقم بتكوين أذونات واجهة برمجة التطبيقات.

Note

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

1. إنشاء تسجيل تطبيق في مدخل Azure.

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

2. تكوين أذونات واجهة برمجة التطبيقات في مدخل Azure:

   1. في تسجيل التطبيق، اذهب إلى صلاحيات API.

   2. حدد إضافة إذن.

   3. حدد علامة التبويب APIs my organization uses.

   4. ابحث عن واجهة برمجة تطبيقات Power Platform.

      Note

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

   5. حدد الأذونات المفوضة.

   6. ضمن CopilotStudio، حدد CopilotStudio.Copilots.Invoke.

   7. حدد إضافة أذونات.

   8. امنح موافقة المسؤول عن طريق تحديد منح موافقة المسؤول لمؤسستك<>. إذا لم يكن الزر متوفرا، فقد تحتاج إلى مطالبة مسؤول المستأجر بالقيام بذلك نيابة عنك.

3. أضف عنوان URL لإعادة التوجيه وقم بتكوين إعدادات الرمز المميز في مدخل Azure:

   1. انتقل إلى المصادقة في تسجيل التطبيق.

   2. ضمن "Platform configurations"، حدد "Add a platform".

   3. حدد تطبيق أحادي الصفحة.

   4. أدخل عنوان URL للبيئة باستخدام التنسيق: https://[your-org].crm.dynamics.com

   5. حدد كلا من رموز الوصول المميزة (المستخدمة للتدفقات الضمنية) والرموز المميزة للمعرف (المستخدمة للتدفقات الضمنية والمختلطة).

   6. حدد التهيئة.

   7. تأكد من تعيين أنواع الحسابات المدعومة إلى الحسابات في هذا الدليل التنظيمي فقط.

Copilot Studio وDataverse

في Copilot Studio، احصل على معرف البيئة ومعرف العامل الخاصين بالعامل لإنشاء سجل تكوين عامل في Dataverse.

1. في Copilot Studio:

   1. تحقق من أنك في البيئة الصحيحة.

   2. حدد العامل الذي تريد اختباره وتأكد من نشره.

   3. من Settings، حدد Advanced>Metadata.

   4. انسخ قيم معرف البيئةواسم المخطط. اسم المخطط هو معرف العامل الخاص بك ويستخدم التنسيق cr123_agentname.

2. إنشاء سجل تكوين عامل في Dataverse مع القيم من الخطوات السابقة:

   الحقل	Value	مثال
   مصادقة المستخدم	مصادقة Microsoft
   معرف العميل	معرف التطبيق (الزبون) من الخطوة 1 ضمن بوابة Azure.	00001111-aaaa-2222-bbbb-3333cccc4444
   معرف المستأجر	معرف الدليل (معرف المستأجر) من الخطوة 1 ضمن بوابة Azure.	11112222-bbbb-3333-cccc-4444dddd5555
   معرف البيئة	معرف البيئة من الخطوة السابقة.	11111111-2222-3333-4444-555555555555
   معرف العامل	اسم المخطط من الخطوة السابقة.	cr123_testagent

استكشاف الأخطاء وإصلاحها

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

أخطاء المصادقة

خطأ: "AADSTS50011: عنوان URL للرد المحدد في الطلب غير متطابق"

• السبب: عدم تطابق URI لإعادة التوجيه في تسجيل التطبيق.

• الحل:

  1. في مدخل Azure، انتقل إلى App registrations وحدد Manage>Authentication.
  2. تأكد من أن عنوان URI لإعادة التوجيه يطابق عنوان URL للبيئة تماما.
  3. استخدم التنسيق: https://[your-org].crm.dynamics.com

خطأ: "AADSTS65001: لم يوافق المستخدم أو المسؤول"

• السبب: أذونات واجهة برمجة التطبيقات مفقودة أو موافقة المسؤول.

• الحل:

  1. في مدخل Azure، انتقل إلى App registrations وحدد أذونات Manage>API.
  2. تأكد من إضافة إذن CopilotStudio.Copilots.Invoke .
  3. حدد منح موافقة المسؤول.

تظهر النافذة المنبثقة لتسجيل الدخول في كل مرة

• السبب: لا يتم تخزين الحساب مؤقتا أو إعدادات المستعرض التي تمنع تخزين الرمز المميز.

• الحل:

  1. تأكد من أن المستعرض لديك يسمح بنوافذ منبثقة للمجال الخاص بـ Dynamics.
  2. تحقق من أن المستعرض الخاص بك في وضع التصفح المتخفي أو الخاص.
  3. تحقق من أن المستعرض لا يمنع ملفات تعريف الارتباط التابعة لجهات خارجية.
  4. قم بإلغاء تحديد ذاكرة التخزين المؤقت للمستعرض وحاول مرة أخرى.
  5. تحقق مما إذا كانت نهج المؤسسة تفرض إعادة المصادقة.

خطأ: "InteractionRequiredAuthError" في وحدة تحكم المستعرض

• السبب: السلوك العادي عند فشل المصادقة الصامتة وتشغيل تسجيل الدخول التفاعلي.

• السلوك المتوقع:

  • يحدث هذا الخطأ عند فشل المصادقة الصامتة.
  • يعرض النظام تلقائيا النافذة المنبثقة لتسجيل الدخول.

• الإجراء المطلوب: لا شيء.

أخطاء SDK للوكيل

خطأ: "لم يتم العثور على 404 - لم يتم العثور على العامل"

• السبب: معرف عامل غير صحيح أو معرف البيئة.

• الحل:

  1. تحقق من معرف العامل (اسم المخطط) في Copilot Studio ضمن إعدادات > Advanced > Metadata.
  2. تأكد من تطابق معرف البيئة مع البيئة حيث يتم نشر العامل.
  3. تأكد من أن الوكيل منشور ويمكن الوصول إليه.

خطأ: "401 غير مصرح به"

• السبب: مشكلات الرمز المميز للمصادقة.

• الحل:

  1. تحقق مما إذا كان المستخدم لديه حق الوصول إلى بيئة Copilot Studio.
  2. تحقق من أذونات تسجيل التطبيق.
  3. امسح ذاكرة التخزين المؤقت للمستعرض وأعد محاولة المصادقة.

خطأ: "403 ممنوع"

• السبب: أذونات غير كافية للوصول إلى العامل.

• الحل:

  1. تأكد من أن المستخدم لديه أدوار أمان مناسبة في Dataverse.
  2. تحقق مما إذا كان العامل يسمح بدور أمان المستخدم.
  3. تحقق من أذونات البيئة.

أخطاء التحكم في مشغل اختبار العامل

خطأ: "فشل تهيئة خدمة المصادقة"

• السبب: تكوين غير صالح في سجل تكوين العامل.

• الحل:

  1. تحقق من صحة جميع قيم التكوين الأربعة:
     • معرف العميل
     • معرف المستأجر
     • معرف البيئة
     • معرف العامل
  2. تحقق من وجود مسافات إضافية أو أحرف غير صالحة.

خطأ: "تم حظر استدعاء الخدمة الخارجية"

• السبب: استخدام خدمة خارجية غير موجود.

• الحل:

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

أخطاء الشبكة وCORS

خطأ: "نهج CORS: لا يوجد عنوان "Access-Control-Allow-Origin"

• السبب: تم حظر طلب عبر المنشأ.

• الحل:

  1. تأكد من أن عنوان URI لإعادة التوجيه في Azure يطابق المجال الدقيق.
  2. استخدم HTTPS لجميع عناوين URL.
  3. تحقق من عدم وجود مشاكل في المحتوى المختلط (HTTP/HTTPS).

خطأ: "فشل الإحضار"

• السبب: مشكلات اتصال الشبكة أو جدار الحماية.

• الحل:

  1. تحقق من اتصال الشبكة من أجل:
     • login.microsoftonline.com
     • api.powerplatform.com
  2. تحقق من أن جدار الحماية يسمح بحركة مرور HTTPS الصادرة.
  3. تحقق من إعدادات الوكيل إذا كان ذلك مناسبًا.

اختبار أخطاء التنفيذ

خطأ: "مهلة تنفيذ الاختبار"

• السبب: العامل يستغرق وقتا طويلا للاستجابة.

• الحل:

  1. تحقق من أداء الوكيل في Copilot Studio.
  2. تحقق من نشر العامل ووظيفته.

خطأ: "فشل إنشاء محادثة"

• السبب: فشل تهيئة SDK العامل.

• الحل:

  1. تحقق من نشر العامل.
  2. تحقق من تكوين العامل في Copilot Studio.
  3. تأكد من أن العامل يدعم سيناريو الاختبار.

نصائح التصحيح

1. تمكين أدوات مطور المستعرض:

   • اضغط على F12 لفتح أدوات المطور.
   • تحقق من علامة التبويب وحدة التحكم بحثا عن أخطاء JavaScript.
   • تحقق من علامة تبويب الشبكة بحثا عن الطلبات الفاشلة.

2. تحقق من تدفق المصادقة:

   • مراقبة علامة تبويب الشبكة أثناء تسجيل الدخول.
   • ابحث عن 200 استجابة من login.microsoftonline.com.
   • تحقق من الحصول على الرمز المميز في سجلات وحدة التحكم.

3. تصديق التكوين:

   • تحقق من جميع GUID والمعرفات.
   • تأكد من عدم وجود مسافات إضافية أو أحرف خاصة.
   • تحقق من إمكانية وصول ذوي الاحتياجات الخاصة إلى البيئة والعامل.

4. اختبار في عزلة:

   • جرب الوكيل مباشرة في استوديو كوبيلوت.

المعلومات ذات الصلة

• تكوين مصادقة المستخدم باستخدام Microsoft Entra ID