العمل مع المتغيرات

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

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

يمكنك تمرير المتغيرات إلى موضوعات أخرى وسيناريوهات Power Automate وإعادتها منها.

إنشاء متغير

تطبيق الويب

تقوم أي عقدة ترجع إخراجا، مثل عقدة السؤال ، تلقائيا بإنشاء متغير إخراج من النوع المناسب.

تلميح

أعد تسمية العقد لتسهيل التعرف عليها. حدد حقل اسم العقدة لتحديث الاسم مباشرة، أو حدد النقاط الثلاث (...) للعقدة وحدد Rename من القائمة. يمكنك أيضا إعادة تسمية العقد فِي محرر التعليمات البرمجية.

لا يمكن إعادة تسمية عقد المشغل والانتقال إلى عقد الخطوة .

يمكن أن يصل طول أسماء العقدة إلى 500 حرف.

قديم

1. انتقل إلى صفحة Topics لروبوت الدردشة الكلاسيكي الخاص بك وافتح الموضوع المطلوب.

2. حدد أيقونة إضافة عقدة ضمن العقدة التي تريد بعدها إضافة عقدة سؤال. ثم حدد طرح سؤال. Copilot Studio تلقائيا بإنشاء متغير لتخزين استجابة المستخدم.

   

اختيار كيان لاستخدامه

تطبيق الويب

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

قديم

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

إعادة تسمية متغير

تطبيق الويب

لتسهيل صيانة عواملك، استبدل الاسم الافتراضي لكل متغير باسم ذي معنى.

1. حدد المتغير. تظهر لوحة خصائص المتغير .

2. ضمن اسم المتغير، أدخل الاسم الذي تريده للمتغير الخاص بك.

قديم

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

تعيين متغير

عادة ما تستخدم عقدة Question لتخزين إدخال المستخدم في متغير. ومع ذلك، قد تحتاج إلى تعيين قيمة متغير بنفسك. في هذه الحالات، استخدم عقدة تعيين قيمة متغيرة .

1. حدد أيقونة Add node ضمن العقدة التي تريد بعدها إضافة عقدة قيمة متغيرة Set .

2. حدد إدارة المتغيرات>تعيين قيمة متغير. تظهر عقدة تعيين قيمة متغيرة على اللوحة.

3. حدد المربع ضمن تعيين متغير. تظهر لوحة Select a variable .

   • إذا كان المتغير الذي تريد تعيينه موجودا بالفعل، فحدده.

   • وإلا، فحدد إنشاء جديد. ينشئ هذا الإجراء متغيرا جديدا. نوعه غير معروف حتى تقوم بتعيين قيمة له.

     

4. بالنسبة إلى القيمة، قم بتعيين قيمة باستخدام أحد الخيارات التالية:

   • اكتب قيمة حرفية.

   • حدد متغيرا موجودا من نفس النوع.

   • استخدم صيغة Power Fx. تعد صيغ Power Fx مفيدة لأنواع أكثر تعقيدا حيث لا يمكن استخدام القيم الحرفية، مثل أنواع الجداول والسجلات.

استخدام المتغيرات في عقد العمليات

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

لمزيد من السياق، راجع أمثلة السيناريوهات في استدعاء تدفق عامل من موضوعواستخدام متغيرات الإدخال والإخراج لتمرير المعلومات.

استخدام القيم الحرفية للمدخلات المتغيرة

في عقدة حيث تقوم بتعيين قيمة لمعلمات الإدخال، يمكنك إدخال قيمة حرفية بدلا من تحديد متغير آخر كقيمة.

تحاول العقدة تفسير القيم الحرفية كسلسلة أو رقم أو قيمة منطقية. على سبيل المثال، يتم تفسير 123 على أنه رقم. إذا كنت تريد أن تفسر العقدة القيمة كسلسلة بدلا من ذلك، فغلف القيمة بعلامات اقتباس مزدوجة، مثل هذا: "123".

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

استخدام متغيرات البيئة للأسرار في مخزن مفاتيح Azure

يمكن أن يشير متغير البيئة إلى سر في Key Vault. متغيرات البيئة السرية هي حالة خاصة من متغيرات البيئة مع اعتبارات فريدة من نوعها.

لإنشاء متغير بيئة سرية في Power Apps، يجب تكوين مخزن Key Vault.

لتخويل Copilot Studio لقراءة مخزن Key Vault هذا، أكمل الإجراءات التالية:

1. تعيين دور Key Vault Secrets User إلى تطبيق Microsoft Copilot Studio Service.

2. لتخويل جميع العوامل من البيئة للوصول إلى السر، قم بإنشاء علامة AllowedEnvironments على السر وإضافة معرفات البيئة المسموح بها مفصولة بفواصل.

3. لتخويل وكلاء محددين فقط من البيئة لاستخدام هذا المخزن، قم بإنشاء علامة AllowedAgents ووضع معرف العامل بالتنسيق {envId}/{schemaName}. بالنسبة إلى قيم متعددة، افصل القيم بفواصل.

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

يقوم وقت تشغيل مربع الحوار بالتخزين المؤقت للقيمة السرية لمدة خمس دقائق. يقوم بالتخزين المؤقت للقراءات غير الناجحة لمدة 30 ثانية.

Warning

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

لوحة المتغيرات

تطبيق الويب

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

لفتح لوحة المتغيرات ، حدد المتغيرات على شريط القوائم للموضوع.

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

قديم

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

1. في شريط القوائم للموضوع، حدد المتغيرات.

   

2. لكل متغير من المتغيرات في الموضوع، حدد ما إذا كنت تريد تمرير القيم أو تلقيها أو كليهما بين الموضوعات.

   

لوحة خصائص المتغير

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

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

تمرير المتغيرات بين الموضوعات

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

تلقي القيم من مواضيع أخرى

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

تطبيق الويب

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

فيما يلي تدفق موضوع التحدث إلى العميل :

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

فيما يلي تدفق موضوع الترحيب :

كما هو موضح في لوحة الاختبار، إذا تم تشغيل هذا الموضوع أولا، فإنه يسأل المستخدم، "ما هو اسمك؟" يخزن القيمة في متغير سلسلة يسمى customerName. يرسل الموضوع الرسالة ، "يسرنا أن نلتقي بك، customerName!" ثم يعيد التوجيه إلى موضوع التحدث إلى العميل ، الذي يرسل الرسالة، "آمل أن يكون لديك يوم رائع، customerName!" ومع ذلك، لاحظ أن موضوع التحدث إلى العميل تخطي طلب اسم المستخدم مرة أخرى. بدلا من ذلك، استخدم قيمة المتغير الذي customerName تم تمريره من موضوع Greeting .

وأخيرا، إليك تلك المحادثة الثانية مرة أخرى، هذه المرة من منظور موضوع التحدث إلى العميل :

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

إعداد موضوع الوجهة

يتلقى موضوع الوجهة قيما من مواضيع أخرى. في هذا المثال، إنه التحدث إلى العميل.

1. أنشئ موضوعا جديدا وقم بتسمائه "التحدث إلى العميل".

2. أضف عبارات المشغل مثل "تحدث معي" و"تحدث معي" و"دردش معي".

3. أضف عقدة سؤال وأدخل "ماذا يجب أن أدعوك؟" للرسالة.

4. ضمن تحديد، حدد الكيان الذي تم إنشاؤه مسبقا اسم الشخص.

5. حدد اسم المتغير. يتم فتح جزء خصائص المتغير.

6. استبدل الاسم الافتراضي ب customerName، ثم حدد تلقي القيم من مواضيع أخرى.

   

7. أضف عقدة الرسالة.

8. في مربع الرسالة، أدخل "آمل أن يكون لديك يوم رائع، ".

9. حدد أيقونة إدراج متغير ({x})، ثم حدد اسم العميل.

10. حدد المسافة بعد المتغير وأدخل علامة تعجب (!).

11. احفظ الموضوع.

إعداد الموضوع المصدر

الموضوع المصدر هو الموضوع الذي يعيد التوجيه إلى موضوع آخر. يوفر القيمة ويمررها إلى موضوع الوجهة. في هذا المثال، إنها تحية.

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

2. أضف عقدة سؤال وأدخل "ما اسمك؟" للرسالة.

3. ضمن تحديد، حدد الكيان الذي تم إنشاؤه مسبقا اسم الشخص.

4. استبدل الاسم الافتراضي ب customerNameFromGreeting.

5. أضف عقدة الرسالة.

6. في مربع الرسالة، أدخل "سعيد بمقابلتك، ".

7. حدد الأيقونة Insert variable ({x})، ثم حدد customerNameFromGreeting.

8. حدد المسافة بعد المتغير وأدخل علامة تعجب (!).

9. أضف عقدة إعادة توجيه ، وحدد موضوع الوجهة التحدث إلى العميل.

10. حدد إضافة إدخال، ثم حدد المتغير من موضوع الوجهة الذي تريد تمرير قيمة إليه.

    

11. حدد الأيقونة > ، ثم حدد المتغير الذي تريد تمرير قيمته، customerNameFromGreeting، في هذا المثال.

    يجب أن تبدو عقدة إعادة التوجيه كما يلي:

    

12. احفظ الموضوع.

قديم

لتلقي القيم من مواضيع أخرى، قم بتعيين خاصية المتغير:

1. في عقدة السؤال ، حدد المتغير الذي تريد تلقي قيم من مواضيع أخرى.

2. في لوحة خصائص المتغير ، ضمن الموضوع (نطاق محدود) حدد تلقي القيم من مواضيع أخرى.

   

   ملحوظة

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

3. احفظ الموضوع.

4. انتقل إلى موضوع تريد إعادة التوجيه إليه. اتبع الخطوات الواردة في إعادة التوجيه إلى موضوع آخر لإعادة التوجيه إلى الموضوع الصحيح.

5. حدد إضافة إدخال لموضوع الوجهة.

   

6. حدد متغيرا في الموضوع المعاد توجيهه الذي تريد تمرير المتغير إليه.

   

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

   

   يظهر المتغير في العقدة التي تمت إعادة توجيهها.

   

إرجاع القيم إلى الموضوعات الأصلية

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

تطبيق الويب

دعونا نتابع المثال من القسم السابق. يمكنك طرح سؤال جديد في موضوع التحدث إلى العميل ، ثم إرجاع الإجابة إلى موضوع الترحيب .

إعداد الموضوع المصدر لمتغير تم إرجاعه

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

1. انتقل إلى الموضوع المصدر.

2. أضف عقدة سؤال وأدخل "ما المدينة التي تعيش فيها؟" للرسالة.

3. ضمن تحديد، اختر الكيان المطور مسبقاً مدينة.

4. حدد المتغير لفتح لوحة خصائص المتغير . قم بتسمية customerCity، ثم حدد إرجاع القيم إلى الموضوعات الأصلية.

   

5. أضف عقدة الرسالة.

6. حدد الأيقونة Insert variable ({x})، ثم حدد customerCity.

7. بعد المتغير في مربع الرسالة، أدخل " يجب أن يكون جميلا هذا الوقت من السنة!".

8. احفظ الموضوع.

إعداد موضوع الوجهة لمتغير تم إرجاعه

عند إرجاع متغير إلى موضوع، يتلقى موضوع الوجهة قيما من الموضوع الحالي. في المثال التالي، موضوع الوجهة هو Greeting.

1. انتقل إلى موضوع الوجهة.

2. يظهر المتغير الذي حددته في الموضوع المصدر على عقدة إعادة التوجيه كمتغير إخراج.

   

3. احفظ الموضوع.

قديم

لإرجاع متغير إلى الموضوع الأصلي، قم بتعيين خاصية المتغير:

1. في عقدة السؤال ، حدد المتغير الذي تريد إرجاعه إلى مواضيع أخرى.

2. في لوحة خصائص المتغير ، ضمن الموضوع (نطاق محدود) حدد إرجاع القيم إلى الموضوعات الأصلية.

   

   ملحوظة

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

3. احفظ الموضوع.

4. انتقل إلى موضوع تريد إعادة التوجيه إليه. اتبع الخطوات الواردة في إعادة التوجيه إلى موضوع آخر لإعادة التوجيه إلى الموضوع الصحيح.

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

   

تحليل القيم

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

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

تحول عقدة قيمة التحليل متغير السلسلة إلى متغير من النوع سجل. يوفر محرر Power Fx إكمال التعليمات البرمجية من IntelliSense واقتراحات لهذا النوع من الأكواد.

بالإضافة إلى تحليل سلاسل JSON، فإن الاستخدام الرئيسي لعقدة قيمة Parse هو تحليل الكائنات غير المحددة النوع في وقت التشغيل. حالة الاستخدام الأكثر شيوعا هي عندما تتلقى حدثا وتحتاج إلى تحليل قيمة الحدث. أو قد ترغب في تحليل الخاصية System.Activity.ChannelData ، والتي تختلف في وقت التشغيل حسب القناة.

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

لإضافة عقدة قيمة تحليل إلى موضوع:

1. حدد أيقونة إضافة عقدة ضمن العقدة التي تريد بعدها توزيع قيمة. أشر إلى إدارة المتغيرات، وحدد Parse value.

2. أضف عقدة قيمة تحليل ، وحدد المتغير الذي تريد تحليله.

   

3. بالنسبة لنوع البيانات، حدد من نموذج البيانات.

   

4. حدد Get Schema من Sample JSON، وأدخل مثال JSON المطلوب في المحرر الذي يفتح، وحدد Confirm.

   

5. حدد المتغير للاحتفاظ بالقيمة التي تم تحليلها. عادة ما تقوم بإنشاء متغير جديد.

   

   يحتوي متغير الإخراج الآن على النوع المتوقع: سجل.

   

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

• نظرة عامة على المتغيرات
• العمل مع المتغيرات العمومية
• استخدام الكيانات وملء الفتحات في الوكلاء
• تخصيص الشكل والمظهر للوكيل.