إتقان آلية التحقق من صحة الاتصال في Microsoft Graph

By Mirko Peters · 2026-08-11

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

Titelbild: Mastering the Microsoft Graph Validation Handshake

مرحبًا بعودتكم إلى المدونة المرافقة للبودكاست! نتناول في هذه المقالة بعمق الآليات التقنية لإشعارات التغيير وWebhooks في Microsoft Graph. إذا سبق لك إعداد اشتراك Webhook ثم اكتشفت أنه لا يُطلق أي حدث على الإطلاق، فأنت بالتأكيد لست وحدك. معظم تطبيقات Graph المتوقفة تفشل منذ البداية تمامًا، أثناء عملية التحقق من صحة الاتصال. عندما يحاول تطبيقك لأول مرة إنشاء اشتراك، يرسل Microsoft Graph طلب اختبار للتأكد من أن نقطة النهاية لديك تعمل، وقادرة على استقبال حركة المرور، ومُهيأة بشكل صحيح. وإذا فاتتك هذه الخطوة الحاسمة أو أضفت عبئًا غير ضروري، فلن يدخل اشتراكك حيز التشغيل، وستتساءل عن سبب غياب المشغّلات الحيوية لأعمالك.

وللتغلب على هذه العقبة once and for all، سنفصّل المتطلبات الدقيقة للتحقق من صحة الاتصال، وكيفية تأمين نقطة النهاية الخاصة بك، وتطبيق آليات مرونة متينة، والحفاظ على دورة حياة اشتراكك. لنستكشف معًا كل ما تحتاج إلى معرفته لبناء بنية تحتية قوية لـ Webhooks في Microsoft Graph.

ما الذي يتضمنه المحتوى

فخ التحقق من Webhook: لماذا لا يرسل Graph أي حدث أول بسبب إخفاقات عملية التحقق من الاتصال.
نقاط نهاية آمنة تقبل فعليًا طلبات Graph من خلال فحوصات صارمة لجمهور JWT والنطاقات.
أساسيات المرونة: إدارة مهلات الانتظار، واستراتيجيات التراجع المتدرج، وتحديد رموز الحالة التي تُفعّل إعادة المحاولة التلقائية.
سلامة دورة الحياة: تجديد اشتراكاتك قبل انتهائها، واكتشاف الاتصالات المنقطعة، والتنبيه المبكر.

العقبة الأولى: التحقق من صحة الاتصال

عند تقديم طلب اشتراك جديد إلى واجهة Microsoft Graph API، يجب عليك تحديد عنوان URL للإشعارات. وقبل أن يحفظ Graph هذا الاشتراك ويفعّله، يرسل طلب HTTP من نوع GET أو POST إلى عنوان URL الخاص بك، يحتوي على معامل في سلسلة الاستعلام أو في الجسم يسمى validationToken. وهنا يقع معظم المطورين في الخطأ.

يرسل Graph طلبًا إلى نقطة النهاية الخاصة بك يتضمن سلسلة validationToken فريدة.
يجب على شيفرتك أن ترد بالسلسلة نفسها تمامًا في نص الاستجابة. والأهم من ذلك، ألا يكون هناك أي تغليف بصيغة JSON، ولا تنسيق HTML، ولا أحرف سطر جديد زائدة في النهاية.
يجب أن تتم الاستجابة بسرعة، خلال أقل من 5 ثوانٍ. فأي تأخير في الشبكة، أو إعادة توجيه HTTP، أو فحص وسيط للمصادقة، أو تنسيق إضافي في الجسم، سيُفشل الاشتراك فورًا.

مثال مبسّط (شيفرة تخطيطية):

Request: GET /webhook?validationToken=abc123
Response: 200 OK
Body: abc123
Content-Type: text/plain

نصائح عملية لنجاح التحقق من الاتصال:

نفّذ مسارًا مختصرًا في الشيفرة خاصًا بطلبات التحقق فقط. تجاوز قاعدة البيانات، وتخطَّ فحوصات المصادقة الثقيلة، وتجنب عبء التسجيل (Logging).
تأكد من أن جدار تطبيقات الويب (WAF) أو شبكة توصيل المحتوى (CDN) يسمح بعناوين IP الخاصة بـ Microsoft Graph ووكلاء المستخدم الخاصين به على مسار التحقق.
تعامل مع روتين التحقق كفحص صحة أساسي: يجب أن يكون خفيفًا وفوريًا وخاليًا تمامًا من أي عوائق.

تأمين نقطة النهاية (الثقة والرموز)

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

اشترط HTTPS مع شهادة SSL/TLS صالحة وموثوقة. لا تسمح أبدًا بحركة HTTP غير المشفرة، وتأكد من تعطيل خوارزميات التشفير الضعيفة.
تحقق من رمز الحامل (Bearer token) للتفويض في كل حمولة إشعار واردة دون استثناء:
- تحقق من التوقيع التشفيري مقابل مجموعة مفاتيح الويب JSON (JWKS) الرسمية الخاصة بـ Microsoft.
- تحقق من مُصدِر الرمز (issuer)، والجمهور المستهدف (audience) مع التأكد من تطابقه مع معرّف تطبيقك، والمستأجر المستهدف، ووقت انتهاء الصلاحية.
- طبّق النطاقات (scopes) والأدوار المطلوبة للتطبيق على المورد المحدد الذي يتم تعديله.
اتبع مبدأ أقل الامتيازات: امنح فقط الأذونات المحددة التي يحتاجها اشتراكك فعليًا. لا تطلب وصولًا على مستوى المستأجر بأكمله عندما تكفي أذونات موقع واحد أو صندوق بريد واحد.
احرص على الأطر البرمجية للويب التي قد تُزيل الترويسات دون قصد أو تُخفي ترويسة Authorization وراء الإعدادات الافتراضية. تأكد دائمًا من أن البرمجية الوسيطة (middleware) لديك تحافظ على الترويسات الواردة.

المرونة والمحاولات المتكررة بأعلى درجات المتانة

تحدث أعطال الشبكة بين حين وآخر، وتتعرض خدمات السحابة لانقطاعات مؤقتة، وقد تمتلئ قوائم انتظار المعالجة في الخلفية أحيانًا. الطريقة التي يستجيب بها نقطة النهاية لديك لـ Microsoft Graph في مثل هذه اللحظات هي ما يحدد ما إذا كان التكامل سيبقى سليمًا أم سينهار.

لرموز الاستجابة أهمية كبيرة:
- تُخبر رموز 200 OK أو 202 Accepted الخدمة Graph بأن الإشعار قد تم تسليمه واستلامه بنجاح.
- تُخبر رموز الحالة 503 أو 504 أو 429 الخدمة Graph بأن خدمتك غير متاحة مؤقتًا، فتعيد المحاولة لتسليم الإشعار. استخدم هذه الرموز بحذر، ولا تدع نظامك يدور في حلقة لا نهاية لها.
- تعامل Graph رموز الحالة من فئة 4xx (مثل 400 أو 401 أو 403) على أنها أعطال دائمة، أي أنها ستُسقط الإشعار فورًا دون إعادة المحاولة.
طبّق التراجع الأُسّي (Exponential Backoff) لمعالجة أي أخطاء عابرة في الأنظمة اللاحقة، وخزّن الحمولات الفاشلة بأمان في قائمة الرسائل المتعذّرة (Dead-Letter Queue) لإعادة معالجتها لاحقًا.
سجّل كل شيء: التقط معرّف الطلب، ومعرّف الاشتراك، وزمن الاستجابة للمعالجة، ورمز حالة HTTP، وأي استثناءات تُرمى أثناء التنفيذ.

نمط خاطئ مقابل أفضل الممارسات:

❌ استخدام عدد ثابت من المحاولات المتكررة (3 مرات)، وإسقاط الحمولات بصمت، وعدم تخزين أي شيء محليًا.
✅ تطبيق تراجع ذكي، ومخزن مخصص للرسائل غير المسلَّمة، وتنبيهات استباقية، ووظيفة إعادة تشغيل مصممة مع مراعاة الخاصية الخالية من الآثار الجانبية (idempotency) بالكامل.

دورة حياة الاشتراك (لا تدع الاشتراك ينتهي دون علمك)

على خلاف الخطافات (webhooks) في منظومات أخرى التي تبقى صالحة إلى أجل غير مسمى، تأتي اشتراكات Microsoft Graph بمدد صلاحية قصيرة بشكل معروف، إذ تدوم غالبًا بضع ساعات فقط أو بضعة أيام كحد أقصى حسب نوع المورد. وإذا لم تُدِر دورة حياتها بفاعلية، فستتعطل تكاملاتك بصمت خلال عطلة نهاية الأسبوع.

لاشتراكات Graph مدد صلاحية قصيرة، ولذلك يجب أن تبني آليات تجديد تلقائية وقوية.
أتمت عملية التجديد قبل وقت كافٍ من انتهاء الصلاحية، وأعدّ تنبيهات تُفعَّل إذا فشل التجديد بسبب انحراف الأذونات أو سحب موافقة المسؤول.
مراقبة الحالة الصحية ضرورية لراحة البال. تابع ما يلي:
- عدد الإشعارات المستلمة في الساعة، مجمّعةً حسب معرّف الاشتراك.
- معدلات الفشل وتفصيل لأكثر رموز حالة HTTP شيوعًا التي تُرجعها نقطة النهاية لديك.
- زمن التسليم من طرف إلى طرف، من لحظة إرسال Graph للخطاف (webhook) حتى لحظة معالجته من قِبل العامل الخلفي.
- فحوصات سلامة الحمولة للتأكد من وجود جميع الحقول المتوقعة في بنية البيانات الواردة.

قائمة التحقق للتنفيذ

تصميم المسارات
- /webhook/validate ← يُرجع رمز التحقق فورًا وبشكل سليم.
- /webhook/notify ← يتولى المصادقة، ويحلل الحمولات، ويدفع الرسائل إلى قائمة الانتظار، ويؤكد الاستلام بسرعة.
الأمان
- HTTPS فقط، والتحقق الصارم من JWT (الجهة المُصدِرة، والجمهور المستهدف، وانتهاء الصلاحية)، وأدوار التطبيق بأقل الامتيازات الضرورية.
الأداء
- أكّد استلام الإشعارات بسرعة عبر وضع العمل في قائمة انتظار بشكل غير متزامن، ونقل المعالجة الثقيلة إلى عمال خلفيين.
الموثوقية
- استخدم استراتيجيات تراجع مناسبة عند الأخطاء 503 و504 و429، وحافظ على تخزين الرسائل غير المسلَّمة، وابنِ وظائف إعادة التشغيل.
قابلية الرصد
- استفد من Application Insights أو Log Analytics للحصول على مقاييس شاملة وتتبعات وتنبيهات قابلة للتنفيذ.
دورة الحياة
- نفّذ وظيفة تجديد مجدولة، وأعدّ تنبيهات للتحذير من انخفاض وقت البقاء (TTL) المتبقي.
العمليات
- احتفظ بدليل تشغيل موثّق للتعامل مع الاشتراكات المنتهية الصلاحية، وحافظ على لوحة معلومات تعرض مقاييس الحالة الصحية لكل اشتراك.

اختبار ذاتي سريع (تدقيق لمدة 10 دقائق)

هل تستطيع نقطة نهاية الخطاف لديك إرجاع validationToken بنجاح في أقل من ثانية واحدة؟
هل تتحقق بدقة من JWT والجهة المُصدِرة والجمهور المستهدف والمستأجر في كل طلب إشعار دون استثناء؟
هل تضع الحمولة في قائمة الانتظار وتُرجع رمز 200 أو 202 بسرعة، أم أن نقطة النهاية تتوقف أثناء معالجة منطق الأعمال الثقيل؟
هل تُرجع 503 أو 429 بشكل صحيح (بدلًا من أخطاء نطاق 400) عند مواجهة مشكلات داخلية مؤقتة؟
هل لديك مهمة تجديد تلقائي تعمل إلى جانب التنبيهات الاستباقية؟
هل يمكنك بسهولة عرض رسم بياني لعمليات التسليم خلال آخر 24 ساعة لكل اشتراك على حدة في نظامك؟

الأخطاء الشائعة وطرق معالجتها

يضيف إطار العمل غلاف JSON إلى استجابات التحقق ← الحل هو التأكد من أن المسار يعيد نص عادي بسيط دون أي تسلسل للكائنات.
غياب ترويسة Authorization بسبب وكيل عكسي (reverse proxy) أو بوابة API ← الحل هو ضبط الوكيل صراحةً لتمرير جميع الترويسات الواردة إلى تطبيقك.
استخدام أذونات عامة للتسهيل ← الحل هو تحديد نطاق الأذونات بدقة على مواقع أو صناديق بريد فردية، والاستفادة من الموافقة الخاصة بالمورد (RSC) حيثما أمكن.
بدايات باردة تسبب زمن استجابة يتجاوز 5 ثوانٍ ← الحل هو تهيئة الدوال بدون خادم مسبقاً (pre-warming) أو استضافة تطبيق الويب الخاص بك على خطة استضافة مخصصة من فئة premium.
انتهاء صلاحية صامت خلال عطلة نهاية الأسبوع ← الحل هو جدولة عمليات التجديد اليومية وإعداد تنبيهات تلقائية كلما انخفض العمر الافتراضي للاشتراك (time-to-live) إلى أقل من 24 ساعة.

يتطلب إتقان آلية التحقق من Microsoft Graph وخط معالجة إشعارات التغيير انتباهاً للتفاصيل، لكن المكافأة تكامل مرن ومتين لا يفوّت أي تحديث. للاستماع إلى نقاش شامل حول هذا الموضوع والحصول على مزيد من النصائح من الخبراء، تأكد من الاطلاع على الحلقة البودكاست ذات الصلة: Fix Microsoft Graph Change Notifications and Webhooks. طبّق هذه الاستراتيجيات اليوم، وودّع خطافات الويب المعطّلة (webhooks) إلى الأبد!