نشر العامل على Azure

لقد بنيت وكيلك البرمجي واختبرته محليًا. قم بتفعيلها في السحابة الآن. هذه الخطوة اختيارية. يمكنك تخطيه إذا قمت بالفعل بنشر وكيلك في بعض السحابة (لا يحتاج حتى إلى أن يكون Azure).

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

لتحديث نقطة نهاية المراسلة، راجع الموارد التالية. وهي توضح كيف يمكنك تحديث نقطة نهاية المراسلة إذا قمت بنشر وكيلك لموفري السحابة الآخرين مثل Amazon Web Services أو Google Cloud Platform:

• استخدم كود الوكيل المنشور في خدمات أمازون ويب
• استخدم كود الوكيل المنشور في منصة Google Cloud

المتطلبات الأساسية

قبل البدء، تأكد من أن لديك العناصر التالية:

الحسابات والأذونات المطلوبة

• اشتراك Azure مع صلاحية الوصول للمساهمين
• تعليمة برمجية للعامل تعمل مع نقطة نهاية للرسائل تكون صالحة ويمكن الوصول إليها. تأكد من اختبار الوكيل محليا واختياريا باستخدام Microsoft 365 باستخدام Dev Tunnels للتحقق من إمكانية إنشاء التعليمات البرمجية للعامل وتشغيلها كما هو متوقع.
• مخطط عامل صالح من خلال إكمال خطوة إعداد مخطط العامل.
• ملفات التكوين المحدثة a365.config.json و a365.generated.config.json وملف التكوين في التعليمات البرمجية (على سبيل المثال، ملف .env).

الأدوات المطلوبة

• تثبيت Azure CLI ومصادقته (تثبيت Azure CLI)

النشر إلى Azure

نشر التعليمات البرمجية لتطبيق العامل إلى Azure باستخدام أدوات Azure القياسية مثل Azure CLI أو مدخل Azure أو إجراءات GitHub.

نشر تطبيق الوكيل

استخدم الأمر Azure CLI az webapp deploy لنشر التطبيق الخاص بك:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

بالنسبة إلى إجراءات GitHub، استخدم إجراء نشر تطبيقات ويب Azure.

التحقق من النشر

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

✅ تم إكمال أمر النشر بدون أخطاء
✅ تطبيق ويب يعمل
✅ تظهر سجلات التطبيقات نجاح بدء التشغيل
✅ يتم تكوين متغيرات البيئة
✅ نقطة نهاية المراسلة تستجيب

تحقق من أمر النشر الذي اكتمل بدون أخطاء

بعد انتهاء النشر، تحقق من النجاح في سجلات النشر:

1. انتقل إلى تطبيق الويب الخاص بك في مدخل Microsoft Azure.
2. اذهب إلى إعدادات> الإعدادات للتحقق من إعدادات التطبيق.
3. تحقق من سجلات النشر في مركز النشر.

للاطلاع على تاريخ النشر التفصيلي:

1. انتقل إلى مدخل Azure > تطبيق الويب الخاص بك
2. النشر>مركز النشر
3. عرض سجلات أحدث نشر لك

إذا فشل البناء:

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

إذا تعطل التطبيق بعد النشر:

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

تحقق من تشغيل تطبيق الويب

استخدم الأمرaz webapp show للتحقق من تشغيل تطبيق الويب.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

الخرج المتوقع لهذا الأمر هو Running.

تحقق من أن سجلات التطبيقات تظهر نجاح بدء التشغيل

لعرض سجلات تطبيق الويب في مدخل Azure:

1. ابحث عن تطبيق الويب بالاسم في مدخل Azure.
2. اذهب إلى نظرة عامة>السجلات>تدفق السجلات.

بدلا من ذلك، يمكنك استخدام أمر PowerShell az webapp log tail لقراءة سجلات تطبيقات الويب:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

إذا ظهرت رسائل تعطل أو أخطاء في السجلات، راجع تعطل التطبيقات عند بدء التشغيل.

تحقق من تكوين متغيرات البيئة

في مدخل Azure:

1. انتقل إلى تطبيق الويب الخاص بك.
2. اذهب إلى إعدادات>متغيرات البيئة.
3. تحقق من وجود إعداداتك.

إذا لم تكن متغيرات البيئة محددة:

• أعد تشغيل عملية النشر لمزامنة ملف .env.
• أو قم بتعيينها يدويا في مدخل Microsoft Azure.
• انظر متغيرات البيئة غير محددة أو غير صحيحة.

تحقق من استجابة نقطة نهاية الرسائل

اختبر وجود نقطة النهاية التي تجدها في صفحة نظرة عامة على تطبيق الويب باستخدام PowerShell أو وسائل أخرى. وإلا، فشاهد 404 على نقطة نهاية المراسلة.

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

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

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

• مراقبة الأداء: استخدم ميزات الملاحظة لتتبع سلوك الوكلاء وتحسين الاستجابات.
• أضف المزيد من الأدوات: استكشف كتالوج الأدوات لتوسيع قدرات وكيلك.
• قم بالتكرار والتحسين: قم بتحديث كود الوكيل، وأعد النشر، وأعد النشر (تذكر زيادة رقم الإصدار!).
• توسع عبر منظمتك: شارك قصص نجاح وكيلك لتحفيز التبني.

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

يصف هذا القسم المشكلات الشائعة عند نشر العوامل على Azure.

فشل أمر النشر

عَرَض: فشل النشر إلى Azure.

الأسباب والحلول الشائعة:

• أخطاء البناء

  أعد بناء المشروع محليًا لرؤية أخطاء التجميع التفصيلية:

  # .NET
  dotnet clean
  dotnet build --verbosity detailed
  
  # Python
  uv build
  
  # Node.js
  npm install
  npm run build
  

• انتهت صلاحية المصادقة Azure

  سجل الدخول مرة أخرى Azure:

  az login
  az account show  # Verify correct subscription
  

• تطبيق ويب لم يتم إنشاؤه

  قائمة تطبيقات الويب لتأكيد وجود الهدف.

  # List Web Apps in resource group
  az webapp list --resource-group <your-resource-group> --output table
  

• تحقق من سجلات النشر

  استخدم الأمرaz webapp log tail لعرض سجلات النشر التفصيلية:

  az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
  

• التحقق:

  # Web App should be running
  az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
  # Expected: "Running"
  

تم إيقاف تطبيق الويب

عَرَض: ينجح النشر ولكن تطبيق الويب لا يعمل.

حل: استخدم az webapp start و az webapp show لبدء تشغيل تطبيق الويب والتحقق من أنه قيد التشغيل.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

تعطل التطبيق عند بدء التشغيل

عَرَض: يبدأ تشغيل تطبيق الويب ولكن يتعطل على الفور؛ تظهر السجلات الأخطاء.

الأسباب الشائعة:

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

الحل: استخدم أوامر az webapp log tail، az webapp config appsettings list، و az webapp config appsettings set لعرض السجلات، والتحقق من متغيرات البيئة، وتعيين المتغيرات المفقودة.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

خطأ 404 على نقطة نهاية المراسلة

عَرَض: تطبيق الويب يعمل لكن /api/messages عنوان الخدمة يُعيد 404.

الحل:

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

اختبر نقطة النهاية بإرسال GET طلب إلى الرابط. استخدم az webapp config show الأمر للتحقق من إعدادات تطبيقات الويب.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

متغيرات البيئة غير محددة أو غير صحيحة

عَرَض: النشر ينجح لكن العامل لا يعمل؛ أخطاء التكوين المفقودة في السجلات.

الحل: تحقق من متغيرات البيئة وحدثها. استخدم أوامر az webapp config appsettings list، و az webapp config appsettings set للتحقق من متغيرات البيئة، وتعيين المتغيرات المفقودة. ثم أعد نشر التطبيق.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

ينجح البناء محليًا ولكنه يفشل في Azure

Symptom: يتم بناء التعليمات البرمجية بنجاح على جهازك ولكنها تفشل أثناء النشر على منصة Azure.

الحلول‏‎:

• تحقق من وجود تبعيات خاصة بالمنصة

  • بعض الحزم تحتوي على بناءات خاصة بالمنصة.
  • يجب أن تضمن أن التبعيات تدعم Linux وأن تعمل Azure Web Apps على Linux بشكل افتراضي.

• تحقق من تطابق إصدارات وقت التشغيل

  شغَّل هذه الأوامر:

  # Check your local version
  dotnet --version  # .NET
  node --version    # Node.js
  python --version  # Python
  

  مقارنة مع وقت تشغيل Azure في المدخل: Settings>Configuration>إعدادات عامة>إعدادات الطبقة.

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