إتقان المصادقة للتطبيقات فقط (App-Only) مع واجهات برمجة تطبيقات Microsoft Viva

By Mirko Peters · 2026-08-28

إذا سبق لك أن أمضيت ساعات في مواجهة أخطاء "Unauthorized" أو "Forbidden" المستعصية أثناء بناء نصوص برمجية آلية للصيانة لـ Microsoft Viva، فأنت لست وحدك. ...

Automatically translated with AI from the original post. Read the English original

إذا سبق لكم أن أمضيتم ساعات في مواجهة أخطاء "Unauthorized" أو "Forbidden" المستعصية أثناء بناء نصوص برمجية آلية للصيانة لـ Microsoft Viva، فأنتم لستم وحدكم. فكثير من عمليات نشر Microsoft 365 الحديثة تتوقف عند المرحلة الأولى، أي "فعّلها وأمل أن يكتشف المستخدمون طريقة استخدامها". ولتحقيق قابلية توسّع تشغيلية حقيقية، يجب على مالكي المنصات ومسؤولي النظام التخلي عن واجهة المستخدم الإدارية والتعمق مباشرة في واجهات برمجة التطبيقات. غير أن فتح أتمتة بلا مراقبة يتطلب نهجاً محكماً للمصادقة للتطبيقات فقط، ومعالجة دقيقة للطلبات، وبناءً متيناً لحمولات البيانات. يرشدكم هذا الدليل إلى إنشاء كيانات خدمة آمنة باستخدام بيانات اعتماد بالشهادات مخزّنة بأمان في Azure Key Vault، وطلب النطاقات الدقيقة الخاصة بالمورد التي تحتاجها بيئتكم، والتعامل مع مطالبات الرموز (token claims) بمهارة مطور متمرس.

للتعمق أكثر في هذه الاستراتيجيات المعمارية والاستماع إلى قصص تطبيق واقعية، تأكدوا من الاستماع إلى حلقة البودكاست المصاحبة لنا، Automate Viva Connections, Topics, Learning, and News. والآن، لنفصّل الخطة الدقيقة اللازمة للتغلب على عقبات أتمتة Viva لديكم.

تجاوز حاجز المصادقة

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

لبناء إعداد بسيط وآمن ويعمل للتطبيقات فقط بالكامل، ينبغي عليكم الالتزام بممارسات هوية صارمة:

• سجّلوا تطبيق Entra ID مخصصاً ليعمل ككيان خدمة (service principal) لديكم.
• فضّلوا دائماً بيانات الاعتماد بالشهادات المخزّنة في Azure Key Vault على أسرار العميل الثابتة والمعرّضة للاختراق.
• امنحوا أذونات التطبيقات المطلوبة فقط. فعلى سبيل المثال، يتطلب Viva Topics عادةً الإذن Topics.ReadWrite.All؛ ويحتاج Viva Learning إلى LearningContent.ReadWrite.All و LearningProvider.ReadWrite.All؛ ويعتمد Connections أو أخبار SharePoint بشكل كبير على Sites.ReadWrite.All إلى جانب أذونات الموقع المستهدف.
• تأكدوا من منح الموافقة الصريحة للمسؤول على النطاقات المطلوبة.
• عالجوا نهج الوصول المشروط (Conditional Access) إما باستثناء كيان الخدمة، أو بإنشاء نهج مخصص يسمح بأمان لكيانات الخدمة غير التفاعلية القادمة من شبكات الأتمتة الموثوقة لديكم.
• عند طلب الرموز، اطلبوا النطاق /.default تحديداً للمورد الذي تنوون استدعاءه. ولا تعيدوا استخدام رمز Graph عام مع نقطة نهاية لمورد خاص بالمنتج.

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

محتوى مخصص: أتمتة Viva Topics

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

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

للتوسع في هذه العملية بكفاءة، ابحث عن مصادر الحقيقة الخارجية لديك، مثل ويكي المؤسسة أو قوائم SharePoint أو سجلات المشاريع، ثم حوّل هذه البيانات إلى JSON منظم. طبّق استراتيجية تجميع الطلبات (Batching) مع مستوى تزامن متحكم فيه، واحترم دائماً استجابات تحديد المعدل HTTP 429 عبر الالتزام بترويسة Retry-After. طبّق مبدأ عدم التكرار (Idempotency) بإجراء upsert للسجلات استناداً إلى مفتاح خارجي لمنع التكرار، ونفّذ دائماً استعلام تحقق بعد النشر للتأكد من أن الموضوع قد اجتاز خط النشر فعلياً.

أفضل الممارسات التشغيلية لإدارة المعرفة

عند تشغيل مهام النشر الآلية، يُعد التسجيل (Logging) الدقيق عنصراً أساسياً. سجّل دائماً الطلبات الواردة إلى جانب معرّفات الارتباط (Correlation IDs) الخاصة بالاستجابات المقابلة لها. تعامل مع أي رمز حالة من فئة 4xx كمشكلة في صحة البيانات أو الأذونات، ووجّه أخطاء 5xx وحالات تحديد المعدل 429 إلى قائمة انتظار مخصصة لإعادة المحاولة مع تراجع أسي (Exponential Backoff).

من أنظمة LMS المعزولة إلى Viva Learning

تعاني المؤسسات غالباً من محتوى التعلم المحبوس في أنظمة متفرقة. الهدف الأساسي من أتمتة Viva Learning هو نشر الدورات الخارجية دفعةً واحدة، بحيث لا يحتاج موظفوك إلى البحث إلا في مكان واحد: داخل Viva نفسه.

لتحقيق استيعاب سلس، يجب أن يحتوي حمولة learningContent لديك على externalId ثابت، وعنوان واضح، ووصف تفصيلي، وعنوان webUrl صالح، وعنوان thumbnailUrl صالح، ومدة بتنسيق ISO 8601، ووسوم أو مهارات ذات صلة، واللغة المحلية الصحيحة. إن تحويل ملفات CSV المصدّرة من نظام إدارة التعلم القديم لديك إلى JSON صارم ومُتحقق منه أمر لا غنى عنه.

يجب أن يستورد خط معالجة الدفعات لديك البيانات المصدر، سواء كُتب بلغة PowerShell أو نُشر كدالة Azure Function، ثم يتحقق من الأعمدة المطلوبة، ويبني حمولات JSON مع ضوابط حماية مدمجة للقيم الفارغة، وينفّذ طلبات POST باستخدام الرموز المميزة (Tokens) الصحيحة، ويُدخل فترات انتظار محسوبة أو خطوات تراجع. سجّل دائماً رموز HTTP غير الناجحة مع أرقام الأسطر وأسبابها لبناء قائمة إعادة محاولة معالجة تلقائية.

أتمتة أخبار Viva Connections

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

يتطلب تكوين الخبر الموثوق عنواناً وملخصاً مرتبطين، ومؤلفاً محدداً بوضوح، وجمهوراً يُمرَّر كمصفوفة من معرّفات مجموعات Microsoft Entra ID، ورابط صورة متحقق منه، وروابط مباشرة تفتح داخل تطبيق Teams، بالإضافة إلى الأولويات وتواريخ الانتهاء المضبوطة. تأكد من أن جميع أسماء الخصائص تستخدم حالة camelCase الصحيحة، وأنها تُتحقق منها قبل الإرسال.

انشر هذه الأصول على نطاق واسع عبر جدولة المنشورات وفقاً للمناطق الزمنية المحلية، وتجميع الدفعات حسب الجمهور المستهدف. حلّل نصوص استجابات الأخطاء عند حدوث استثناءات 400 Bad Request حتى تتمكن من إصلاحها وإعادة إرسالها بسرعة. واحتفظ ببيانات قياس شاملة (Telemetry) توضح معرّفات المنشورات وأحجام الجمهور وحالات التسليم.

أنماط جاهزة للإنتاج

يتطلب بناء أتمتة موثوقة اعتماد أنماط هندسية بمستوى المؤسسات. لا تعتمد أبداً على تشغيل السكربتات يدوياً على جهاز محلي. بدلاً من ذلك، ابنِ واختبر ونشر خطوط الأتمتة لديك باستخدام GitHub Actions أو Azure DevOps. واحفظ جميع الأسرار التشغيلية بأمان ضمن مراجع Azure Key Vault بدلاً من تضمينها بشكل ثابت في السكربتات.

إمكانية المراقبة أمر بالغ الأهمية. ادمج مهام الأتمتة لديك مع Application Insights أو Log Analytics لتتبع نجاحات التنفيذ، وارتفاعات زمن الاستجابة، وأحداث تقييد المعدل (Throttling). طبّق خوارزميات التراجع الأسي مع عشوائية (Jitter)، واحترم ترويسات Retry-After بالتزام تام، واستخدم مفاتيح Idempotency لضمان ألا تؤدي إعادة محاولة مهمة فاشلة إلى إنشاء محتوى مكرر أبداً.

الأخطاء الشائعة وحلول سريعة

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

• إذا تلقيت أخطاء 401 أو 403 رغم أن الكود سليم، فغالباً ما يعني ذلك أن الجمهور المستهدف للرمز المميز (Token Audience) لا يطابق مورد واجهة البرمجة المستهدف. اطلب دائماً رمزاً مميزاً جديداً مصمماً خصيصاً للنقطة الطرفية التي تستدعيها.
• إذا أُنشئ الموضوع بنجاح لكنه لا يظهر في واجهة المستخدم، فتحقق من خاصية state للتأكد من أنها مُعلَّمة كمنشورة لا تزال في حالة مسودة معلّقة، وتأكد من أن البيانات الوصفية (Metadata) ليست فقيرة بشكل مفرط.
• المحتوى التعليمي الذي يُرفع ثم يختفي بشكل غامض يعاني عادةً من عدم تطابق في نوع البيانات أو من حقول مطلوبة مفقودة في مخطط الحمولة.
• منشورات الأخبار في Connections التي لا تظهر غالباً ما يكون فيها خاصية الجمهور (audience) مكتوبة بتنسيق خاطئ كنص بدلاً من مصفوفة، أو تحتوي على روابط صور غير صالحة وملخصات طويلة جداً.
• تشير الإخفاقات العشوائية التي تصيب مهامك على نطاق واسع إلى أنك تتجاوز حدود معدل الطلبات. قلّص أحجام الدفعات لديك، وأضف آليات تراجع (backoff) مناسبة.

مؤشرات الأداء الرئيسية لإثبات النجاح

لتبرير الجهد الهندسي المبذول في أتمتة منصة Microsoft Viva، تحتاج إلى تتبع مؤشرات أداء واضحة. قِس مدة الوقت من لحظة إنشاء ملف CSV حتى نشره وإتاحته مباشرةً. تابع معدلات النجاح لكل مئة استدعاء API عبر كل ميزة على حدة، وراقب معدلات أخطاء التقييد 429 و5xx قبل تطبيق آليات التراجع وبعده، وقيّم تغطية الموضوعات من خلال حساب نسبة المشاريع الداخلية والاختصارات التي لها موضوعات مباشرة ونشطة، وقارن اكتمال كتالوج التعلم مع بيانات LMS الرئيسية لديك، وقِس مقاييس تسليم Viva Connections، بما في ذلك نسب النشر في الوقت المحدد وإجمالي عدد الوصول إلى الجمهور.

البداية السريعة (هذا الأسبوع)

إذا كنت مستعداً لاتخاذ إجراء هذا الأسبوع، فاتبع خطة الإطلاق البسيطة التالية:

1. أنشئ مبدأ خدمة (service principal) مخصصاً مدعوماً بشهادة، ومنحه الحد الأدنى المطلوب تماماً من أذونات التطبيق، واحصل على موافقة المسؤول الصريحة.
2. أنشئ دالة Azure Function خفيفة أو نص برمجي محلي بـ PowerShell للأتمتة، مُعدّ لسحب أسراره بأمان من Azure Key Vault.
3. أتمِت سير عمل واحداً من البداية إلى النهاية، على سبيل المثال نشر دفعة من خمسة وعشرين موضوعاً من Viva Topics مع معالجة الأخطاء وإعادة المحاولات والتحقق بعد النشر.
4. فعّل التسجيل (logging) وابنِ لوحة مراقبة أساسية باستخدام Application Insights.
5. وثّق دليل التشغيل الخاص بك، وحدّد جهات الدعم، وجدول مهامك المؤتمتة لتعمل دون تدخل بشري.

بالتحول بعيداً عن الإدخال اليدوي واعتماد أتمتة API متينة مدعومة بمصادقة آمنة للتطبيق فقط، يمكنك تحويل بيئة Microsoft Viva لديك إلى منصة مؤسسية حيّة ونابضة بالحياة. وللمزيد من التعمّق والنصائح المتخصصة والشروح المعمارية، تابع الحلقة الكاملة من البودكاست، Automate Viva Connections, Topics, Learning, and News!