إضافة مصادقة المستخدم إلى المواضيع

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

إشعار

يتم تكوين العوامل الذين يتم إنشاؤهم في Copilot Studio وفي Microsoft Teams تلقائيا لمصادقة Microsoft Entra ID.

يمكنك أيضا ضبط تسجيل الدخول الواحد (SSO) بحيث لا يحتاج المستخدمون إلى تسجيل الدخول يدويا. لمزيد من المعلومات، راجع تكوين تسجيل الدخول الأحادي باستخدام Microsoft Entra ID.

المتطلبات

• نظرة عامة على المتغيرات
• قم بتكوين مصادقة الْمُسْتَخْدِم فِي Copilot Studio

تطبيق الويب

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

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

أنت بحاجة إلى تكوين المصادقة اليدوية باستخدام Microsoft Entra ID قبل أن تتمكن من استخدام المصادقة في مواضيعك.

اتبع الإرشادات الموجودة في تكوين مصادقة المستخدم باستخدام Microsoft Entra ID.

إضافة مصادقة المستخدم باستخدام موضوع النظام "تسجيل الدخول"

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

مهم

نوصي بأن يُستخدم موضوع تسجيل الدخول فقط لتوفير طريقة المصادقة التي يوفرها Copilot Studio. لا ينبغي تعديله لاستدعاء أي إجراءات أو تدفقات أخرى، أو طرق مصادقة أخرى.

1. افتح عاملك في Copilot Studio، واختر الإعدادات في أعلى الصفحة، ثم اختر الأمان.
2. حدد المصادقة.
3. اختر المصادقة يدويًا، ثم اختر طلب من المستخدمين تسجيل الدخول.
4. قم بتكوين جميع حقول المصادقة اليدوية، حسب الحاجة.
5. حدد حفظ..

إضافة مصادقة المستخدم ضمن موضوع مخصص

موضوع تسجيل الدخول يقوم بمصادقة المستخدم في بداية المحادثة. للسماح للمستخدم بتسجيل الدخول لاحقًا، يمكنك إضافة عقدة مصادقة إلى أي موضوع مخصص.

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

1. اختر الإعدادات في أعلى الصفحة، ثم اختر الأمان.

2. حدد لوحة المصَادقة‬.

   إشعار

   يجب عليك اختيار المصادقة يدويا لإضافة مصادقة المستخدم إلى موضوع مخصص.

3. حدد المصادقة اليدوية وقم بإلغاء تحديد مربع طلب تسجيل دخول المستخدمين.

4. قم بتكوين جميع حقول المصادقة اليدوية، حسب الحاجة.

5. حدد حفظ..

6. حدد المواضيع في الجزء العلوي من الصفحة.

7. حدد إضافة عقدة ( ) >متقدمة>مصادقة.

8. اختبر موضوعك مع مستخدم تم تكوينه مع مزود الهوية الخاص بك.

تلميح

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

متغيرات المصادقة

عند تكوين مصادقة المستخدم لعاملِك، يمكنك استخدام متغيرات المصادقة في مواضيعِك. يقارن الجدول التالي توفر هذه المتغيرات وفقًا لخيار المصادقة الذي اخترته.

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

متغير المصادقة	لا مصَادقة	مصَادقة مِن خلال Microsoft	مصَادقة يَدويَّة
User.DisplayName	غير متوفرة	المتوفر	المتوفر
User.FirstName	غير متوفرة	المتوفر	المتوفر
User.LastName	غير متوفرة	المتوفر	المتوفر
User.PrincipalName	غير متوفرة	المتوفر	المتوفر
User.Email	غير متوفرة	المتوفر	المتوفر
User.Id	غير متوفرة	المتوفر	المتوفر
User.IsLoggedIn	غير متوفرة	المتوفر	المتوفر
User.AccessToken	غير متوفرة	غير متوفرة	المتوفر
SignInReason	غير متوفرة	المتوفر	المتوفر

User.DisplayName

تحذير

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

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

يقوم Copilot Studio تلقائيًا بتعيين قيمة User.DisplayName من المطالبة name المقدمة من مزود الهوية، طالما تم تعريف نطاق profile عند إعداد المصادقة اليدوية. لمزيد من المعلومات حول النطاق، راجع تكوين مصادقة المستخدم باستخدام Microsoft Entra ID.

User.Id

تحذير

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

متغير User.Id يحتوي على معرف المستخدم المخزن في مزود الهوية. استخدم هذا المتغير في تدفقات Power Automate لاستدعاء واجهات برمجة التطبيقات التي تأخذ UserID كقيمة.

يقوم Copilot Studio تلقائيًا بتعيين قيمة User.DisplayName من مطالبة sub التي يوفرها موفر الهوية.

User.IsLoggedIn

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

User.AccessToken

تحذير

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

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

لا تستخدم User.AccessToken داخل عقد الرسائل أو في التدفقات غير الموثوقة.

SignInReason

SignInReason هو متغير من نوع الاختيار يحدد الوقت الذي يجب فيه على المستخدم تسجيل الدخول. يحتوي على قيمتين محتملتين:

• SignInRequired يدل على أن المستخدم يجب عليه تسجيل الدخول في بداية المحادثة باستخدام موضوع النظام تسجيل الدخول. يجب تفعيل متطلب تسجيل الدخول للمستخدمين.

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

قديم

متغيرات المصادقة

إذا تم تكوين عاملَك باستخدام خيارَي المصادقة مع Microsoft أو المصادقة اليدوية فستتوفر لديك مجموعة من متغيرات المصادقة ضمن مواضيعك. لمزيد من المعلومات حول كيفية تكوين المصادقة في عاملك، راجع تكوين مصادقة المستخدم في Copilot Studio.

يقارن الجدول التالي توفر متغيرات المصادقة حسب خيارات تكوين المصادقة:

متغير المصادقة	لا مصَادقة	مصَادقة مِن خلال Microsoft	يدوي
User.DisplayName	❌	✔️	✔️
User.Id	❌	✔️	✔️
User.IsLoggedIn	❌	❌	✔️
User.AccessToken	❌	❌	✔️

المتغير UserDisplayName

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

تُستخرج قيمة هذا الحقل من مطالبة في Microsoft Entra ID name. بالنسبة لموفري OAuth، يتم تخزين هذه القيمة في المطالبة name. يقوم Copilot Studio باستخراج هذا الحقل تلقائيًا إلى المتغير، لذا تأكد من إضافة profile ضمن إعداد نطاق المصادقة الخاص بك.

متغير UserID

يحتوي المتغير User.Id على معرف المستخدم المخزن في مزود الهوية. يمكن لتدفقات Power Automate استخدام هذه القيمة لاستدعاء واجهات برمجة التطبيقات التي تتطلب UserID كقيمة. تُستخرج قيمة هذا الحقل من مطالبة في Microsoft Entra ID sub. بالنسبة لموفري OAuth، يتم تخزين هذه القيمة في المطالبة sub. يستخرج Copilot Studio هذا الحقل تلقائيًا إلى المتغير.

تحذير

قد لا يتم ملء المتغيرين User.DisplayName وUser.Id، وبدلاً من ذلك قد تكون هذه المتغيرات سلاسل فارغة حسب تكوين المستخدم في مزود الهوية. اختبر مع مستخدم من مزود الهوية الخاص بك للتأكد من أن مواضيعك تعمل بشكل صحيح، حتى لو كانت هذه المتغيرات فارغة.

متغير IsLoggedIn

يشير المتغير User.IsLoggedIn إلى ما إذا كان المستخدم قد سجل الدخول (سواء نتيجة تسجيل الدخول أو لأنه كان قد سجل الدخول بالفعل، والمعروف أيضًا بمسار نجاح تسجيل الدخول) أو لم يسجل الدخول (ما يؤدي إلى مسار فشل تسجيل الدخول).

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

متغير User.AccessToken

متغير User.AccessToken يحتوي على رمز المستخدم الذي يُستخرج بعد تسجيل دخوله. يمكنك تمرير هذه المتغير إلى تدفقات Power Automate حتى تتمكن من الاتصال بواجهات برمجة التطبيقات الخلفية وجلب معلومات المستخدم، أو اتخاذ إجراءات نيابةً عن المستخدم.

تحذير

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

لا تستخدم User.AccessToken داخل عقد الرسائل أو في التدفقات غير الموثوقة.

اختبار متغيرات المصادقة

افتراضيًا، يستخدم جزء روبوت الاختبار حساب المستخدم المسجل حاليًا لملء المتغيرين User.DisplayName وUser.Id. ومع ذلك، عند اختبار المواضيع التي تستخدم المصادقة، قد ترغب في استخدام قيم أخرى لهذه المتغيرات (أو حتى قيمة فارغة).

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

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

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

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

المتغير	أمر القيمة المخصصة	أمر القيمة الفارغة (الفارغة)
User.DisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
User.Id	غير متوفرة	/debug set bot.UserID ""

مهم

لأسباب أمنية، لا يمكنك تعيين متغير User.Id بقيمة مخصصة (باستثناء القيمة الفارغة أو الخالية).

المصادقة عند استخدام "المصادقة مع Microsoft"

إذا تم تعيين خيار المصادقة الخاص إلى المصادقة باستخدام Microsoft، فلن تحتاج إلى إضافة مصادقة إلى مواضيعك صراحةً. في هذا التكوين، يتم تسجيل دخول أي مستخدم في Microsoft Teams تلقائيًا عبر بيانات اعتماد Teams الخاصة به، ولا يحتاج إلى تسجيل الدخول يدويًا باستخدام بطاقة مصادقة. إذا كان خيار المصادقة لديك مضبوطا على يدوية، فيجب عليك إضافة عقدة مصادقة (حتى لقناة Teams).

إشعار

إذا تم تعيين خيار الْمصادقة الْخاص إلى المصادقة مع Microsoft، فلا يمكنك إضافة مصادقة إلى مواضيعك صراحةً.

إضافة مصادقة المستخدم إلى المواضيع

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

بمجرد أن يدخل المستخدم اسم المستخدم وكلمة المرور في نافذة الإدخال (المستضافة من قبل موفر الهوية)، قد يُطلب منه إدخال رمز تحقق، وذلك حسب قناة . بعض القنوات، مثل Microsoft Teams، لا تتطلب رمز تحقق من المستخدم.

عندما يكون عاملك قد ضبط SSO، لا يطلب من المستخدم تسجيل الدخول.

لإضافة عقدة مصادقة إلى موضوعك:

1. انتقل إلى صفحة المواضيع للعامل الذي تريد تحريره.

2. افتح الموضوع الذي ترغب في إضافة قالب مصادقة إليه.

   إشعار

   إذا كان عاملك متصلا بـ Dynamics 365 Customer Service، فلا يمكن أن تكون عقدة المصادقة جزءا من مسار المحادثة الذي يتبعه العامل عند استقبال المستخدمين لأول مرة؛ وإلا، يتم عرض بطاقة تسجيل الدخول مرتين. بدلاً من ذلك، يجب عليك إضافة عقدة مصادقة إلى موضوع آخر يتم تفعيله عند رد المستخدم.

3. اختر إضافة عقدة (+) لإضافة عقدة رسالة. أدخل ما يجب أن يقوله عامل للإشارة إلى أن تجربة تسجيل الدخول على وشك الحدوث.

4. أسفل عقدة الرسالة، حدد إضافة عقدة (+)، وحدد استدعَاء إجراء، ثم حدد مصادقة.

   

   إشعار

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

   تظهر عقد جديدة تلقائيًا: عقدة أصل للمصادقة تليها عقدتان لمسار النجاح ومسار الفشل.

استخدام User.AccessToken دون وجود عقدة مصادقة

المتغيران User.IsLoggedIn وUser.AccessToken متوفران حتى لو لم تستخدم القالب المقدم من إدخال قائمة استدعاء إجراء. إذا قمت بتمرير المتغير User.AccessToken دون أن يمر المستخدم أولاً عبر عقدة المصادقة، سيُطلب من المستخدم تسجيل الدخول في تلك الخطوة.

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

إشعار

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

مسار تسجيل الدخول الناجح

يمثل مسار النجاح مكان User.IsLoggedIn = True ويشمل ذلك عند إتمام تسجيل دخول المستخدم بنجاح.

إذا كان لديك منطق يعتمد على المتغير User.AccessToken (على سبيل المثال، للاتصال بنظام خلفي باستخدام تدفق لاسترجاع معلومات المستخدم)، يُدرج ضمن هذا المسار.

مسار الفشل

مسار الفشل يعادل أي شرط غير IsLoggedIn = True. في معظم الحالات، يحدث مسار الفشل لأن المستخدم فشل في تسجيل الدخول، أو استخدم كلمة مرور خاطئة، أو ألغى تجربة تسجيل الدخول.

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

اختبار موضوعك

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

المحتوى ذو الصلة

يمكنك أيضا ضبط تسجيل الدخول الواحد (SSO) بحيث لا يحتاج المستخدمون إلى تسجيل الدخول يدويا. لمزيد من المعلومات، راجع تكوين تسجيل الدخول الأحادي باستخدام Microsoft Entra ID.