اختبار العاملين باستخدام أنفاق التطوير

باستخدام أنفاق التطوير، يمكنك اختبار عامل Agent 365 الخاص بك باستخدام تطبيقات Microsoft 365 (مثل Teams أو Outlook أو Word) بينما يعمل عامل العامل محليا على جهاز التطوير. يُوفِّر هذا الأسلوب جسرًا بين التطوير المحلي والاختبار فِي البيئات الواقعية، بحيث يمكنك التحقق مِنْ سلوك العامل فِي بيئات Microsoft 365 الفعلية قبل نشره إلى السحابة.

المتطلبات

قبل استخدام Dev Tunnels، تأكد مِنْ تثبيت أداة Dev Tunnels لسطر الأوامر.

• Windows: winget install Microsoft.devtunnel
• نزِّل الأداة مِنْ macOS/Linux: aka.ms/devtunnels/download

إعداد Dev Tunnel

قم بتكوين Dev Tunnel لعرض نقطة نهاية العامل المحلي لخدمات Microsoft 365.

إنشاء نفق وتشغيله

1. سجِّل الدخول إلى Dev Tunnel:

   devtunnel user login
   

2. أنشئ نفقًا مستمرًا:

   devtunnel create --allow-anonymous
   

   هذا الأمر يعيد معرف النفق. احفظ هذا المعرّف لاستخدامه لاحقًا.

3. تكوين منفذ النفق:

   عيِّن المنفذ الذي يستخدمه خادم العامل (عادةً 3978):

   devtunnel port create <tunnel-id> -p <port-number>
   

4. ابدأ النفق:

   devtunnel host <tunnel-id>
   

   يعرض الأمر عنوان URL الخاص بالنفق (على سبيل المثال، https://abc123xyz.devtunnels.ms:3978). انسخ هذا الرابط للخطوة التالية.

تلميح

استخدم devtunnel list لعرض جميع الأنفاق و devtunnel delete <tunnel-id> لإزالة الأنفاق التي لم تعد بحاجة إليها.

تكوين نقطة نهاية رسائل عامل

سجل عنوان URL الخاص بنفق التطوير (على سبيل المثال، https://abc123xyz.devtunnels.ms:3978/api/messages) كنقطة نهاية رسائل عامل حتى يعرف Microsoft 365 أين يوجه الرسائل. لا تنسَ إضافة اللاحقة /api/messages إلى نقطة النهاية.

يُرجى الاطلاع على تعيين نقطة نهاية مراسلة العامل.

اختبار مَعَ Microsoft 365

مع تفعيل نفق التطوير وتسجيل نقطة النهاية، اختبر عاملك فِي تطبيقات Microsoft 365.

الاختبار فِي Microsoft Teams

1. ابدأ تشغيل العامل المحلي باستخدام التعليمات فِي تثبيت التبعيات وبدء تشغيل خادم تطبيق العامل.

2. تحقق مِنْ اتصال النفق:

   devtunnel list
   

   تحقق مِنْ أن النفق يعرض اتصالات المضيف النشطة. يجب أن يعرض العمود "Host Connections" رقمًا أكبر مِنْ 0.

3. تفاعل مَعَ العامل الخاص بك فِي Teams.:

   • افتح Microsoft Teams (إصدار الويب أو إصدار سطح المكتب).
   • في شريط البحث فِي Teams، ابحث عن العامل باستخدام اسمه أو عنوان بريده الإلكتروني.
   • ابدأ محادثة مَعَ العامل.
   • أرسل رسالة وتابع الرد
   • تحقق مِنْ وحدة التحكم المحلية لديك للطلبات الواردة ونشاط عامل

اختبار إشعارات البريد الإلكتروني

إذا كان عاملُك مهيأ لتلقي إشعارات البريد الإلكتروني:

1. أرسل رسالة إلكترونية إلى عنوان عاملِك
2. قم بتسجيل عاملك في سلسلة بريد إلكتروني
3. راقب وحدة التحكم المحلية بحثًا عن خطاف إشعارات الويب (notification webhook).
4. تحقق مِنْ معالجة عاملِك للبريد الإلكتروني وردّه عليه

اختبار التكامل مَعَ Word

للعوامل التي تستجيب لتعليقات Word:

1. افتح مستند Word يمكن للعامل الوصول إليه.
2. أضف تعليقًا تشير فيه إلى عاملِك.
3. تحقق مِنْ وحدة التحكم المحلية لديك بحثًا عن الإشعار.
4. تحقق مِنْ ظهور استجابة العامل فِي Word.

مراقبة نشاط الأنفاق

يوفر Dev Tunnels فحص حركة المرور للمساعدة فِي استكشاف أخطاء الاتصال وإصلاحها وفهم تدفق الطلبات:

devtunnel show <tunnel-id>

يعرض هذا الأمر:

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

يمكنك أيضًا مراقبة نشاط النفق فِي الوقت الفعلي مِنْ خلال متابعة المخرجات التي يعرضها الأمر devtunnel host.

الحفاظ على اتصالات الأنفاق

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

تحقق مِنْ حالة النفق

تحقق مما إذا كان نفقك نشطًا:

devtunnel list

يعرض الإخراج:

• معرّف النفق: معرف النفق الخاص بك
• اتصالات المضيف: عدد الاتصالات النشطة (يجب أن يكون واحدًا أو أكثر عندما يكون devtunnel host قيد التشغيل)
• المنافذ: المنافذ المُعدّة
• انتهاء الصلاحية: وقت انتهاء النفق

إذا أظهر Host Connections 0، فالنفق موجود لكنه غير مستضاف حاليا.

إعادة تشغيل نفق منقطع الاتصال

إذا انقطع اتصال النفق، أعد تشغيله باستخدام نفس معرف النفق:

devtunnel host <tunnel-id>

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

حافظ على تشغيل الأنفاق أثناء التطوير

للحفاظ على اتصالات مستقرة:

• أبقِ نافذة الوحدة الطرفية مفتوحة - لا تُغلق الوحدة الطرفية التي تُشغِّل الأمرdevtunnel host.
• منع الكمبيوتر مِنْ الدخول فِي وضع السكون - قم بتكوين نظامك ليظل يعمل أثناء جلسات الاختبار.
• تابع أخطاء الاتصال - راقب devtunnel hostمخرجات الطرفية لرصد رسائل الانقطاع.
• أعد التشغيل بعد تغييرات الشبكة - إذا قمت بتغيير الشبكة أو إعادة الاتصال بشبكة VPN، أعد تشغيل النفق.

تلميح

إذا كان النفق ينقطع الاتصال بشكل متكرر، تحقق مِنْ إعدادات الشبكة وقواعد جدار الحماية للتأكد مِنْ أنها لا تمنع الاتصال.

تنظيف

عندما تنتهي مِنْ الاختبار باستخدام أنفاق التطوير:

أوقف النفق

اضغط على Ctrl+C فِي الوحدة الطرفية التي تُشغِّل الأمر devtunnel host لإيقاف النفق.

يقوم هذا الأمر بإزالة عنوان URL الخاص بـ Dev Tunnel مِنْ نقطة نهاية الرسائل الخاصة بالعامل. عند النشر إلى بيئة الإنتاج، عيِّن عنوان URL لنقطة النهاية المستضافة على السحابة.

إشعار

يظل النفق متاحًا للاستخدام فِي المستقبل إلى أن تقوم بحذفه بشكل صريح باستخدام devtunnel delete <tunnel-id>.

القيود

ضع القيود التالية فِي الاعتبار عند الاختبار باستخدام Dev Tunnels:

• خاص بالتطوير: استخدم أنفاق التطوير للتطوير والاختبار فقط، وليس فِي بيئة الإنتاج.
• الأداء: توقَّع زمن استجابة أعلى مقارنةً بالعوامل المستضافة على السحابة بسبب توجيه حركة مرور الشبكة.
• استقرار الاتصال:قد يتم فقد الاتصال بالأنفاق بشكل متقطع، وقد يتطلب الأمر إعادة تشغيلها يدوياً.
• الاعتبارات الأمنية: علامة --allow-anonymous مناسبة للاختبار، لكن لا تستخدمها مَعَ البيانات الحساسة.
• إدارة الجلسة: قد يتعين عليك إعادة المصادقة بشكل دوري حسب مدة الجلسة.

الخطوات التالية

بعد نجاح اختبار نفق المطور:

• نشر عاملك على السحابة: قم بنشر الإرسال إلى Azure، أو تعيين نقطة نهاية رسائل العامل فِي AWS، أو تعيين نقطة نهاية رسائل العامل فِي GCP.
• تكوين نقاط نهاية رسائل العامل: نقطة نهاية مراسلة العامل.
• اتبع دورة حياة التطوير الكاملة: دورة حياة تطوير Agent 365..

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

إذا واجهت مشاكل أثناء الاختبار عبر أنفاق المطورين، ابدأ هنا لإصلاح الأنفاق الشائعة والاتصال ونقاط النهاية. للمزيد مِنْ استكشاف Agent 365 (الإعداد، المصادقة، والرسائل)، راجع استكشاف المشكلات .

فشل اتصال النفق

الأعراض:Dev Tunnel لا يبدأ أو ينقطع الاتصال فوراً.

الحلول‏‎:

• تحقق مِنْ أنك سجلت الدخول: devtunnel user login
• تحقق مما إذا كانت هناك عملية أخرى تستخدم نفس المنفذ
• تأكد مِنْ أن جدار الحماية يسمح باتصالات Dev Tunnel.
• احذف النفق وأعد إنشاؤه: devtunnel delete <tunnel-id> ثم أنشئ نفقًا جديدًا

لا تصل الرسائل إلى العامل المحلي.

الأعراض: يشير Microsoft 365 إلى أنه تم إرسال الرسالة، لكن عاملِك المحلي لم يستلمها.

الحلول‏‎:

• تأكد مِنْ أن عاملك يعمل محليًا
• تحقق مِنْ أن النفق نشط: devtunnel list يجب أن يظهر "متصل"
• تحقق مِنْ تكوين نقطة النهاية فِي a365.config.json وتأكد مِنْ أن عنوان Dev Tunnel الخاص بك مضبوط كنقطة نهاية للرسائل
• راجع سجلات نفق التطوير فِي النافذة الطرفية التي تشغل فيها devtunnel host بحثًا عن أخطاء الاتصال
• تأكد مِنْ أن المنفذ المحلي يطابق منفذ النفق (كلاهما يجب أن يكون 3978 افتراضيًا)

أخطاء المصادقة عبر Dev Tunnel

الأعراض: أخطاء 401 أو 403 عند الاختبار عبر Dev Tunnel.

الحلول‏‎:

• تحقق مِنْ تكوين المصادقة القائمة على العاملين (مصادقة الرمز المميز للمالك لا تعمل مَعَ أنفاق التطوير لتكامل Microsoft 365).
• تحقق مِنْ بيانات اعتماد مخطط العامل في a365.generated.config.json.
• تأكد مِنْ أن عاملك لديه الأذونات المطلوبة للعمليات التي تختبرها.
• تأكد مِنْ أن رموز المصادقة الخاصة بك لم تنتهِ صلاحيتها.

تم تغيير أو انتهاء صلاحية عنوان URL لنفق Dev

الأعراض: رابط النفق الذي كان يعمل سابقًا لم يعد يعيد التوجيه إلى عاملِك.

الحلول‏‎:

• تحقق مِنْ حالة النفق باستخدام devtunnel list.
• أعد تشغيل النفق باستخدام devtunnel host <tunnel-id>.
• قم بتحديث نقطة نهاية الرسائل إذا تغير عنوان الرابط باستخدام a365 setup blueprint --endpoint-only.