Microsoft Graph يُرجع 429 Too Many Requests في النصوص البرمجية للعمليات الجماعية: ما الذي يجب تغييره
By Mirko Peters ·
يتباطأ نص Graph البرمجي إلى حدّ الزحف، أو يفشل بالخطأ 429 حتى عند إرسال طلب واحد كل عشر ثوانٍ. تعرّف على سبب أهمية الخصائص المكلفة والحصص المشتركة، وكيف تتراجع تدريجياً، وتقسّم الاستدعاءات، وتجمعها بأمان ضمن دفعات.
Automatically translated with AI from the original post. Read the English original
يقرأ نص برمجي بيانات المستخدمين من Microsoft Graph مستخدماً واحداً في كل مرة، وبمعدل بطيء ومتحفظ، ومع ذلك يتلقى 429 Too Many Requests. تصف سلسلة نقاش على Microsoft Q&A بتاريخ مايو 2026 هذه الحالة تماماً: استدعاء لمستخدم واحد، وقائمة $select طويلة تتضمن signInActivity، وخيار $expand=manager، وعميل يرسل طلباً واحداً كل عشر ثوانٍ مع طلب واحد قيد التنفيذ في كل مرة.
النقاط الرئيسية
- لا يحميك معدل ثابت للطلبات. فالحدود تعتمد على نوع الطلب والتطبيق والمستأجر. وتذكر Microsoft Learn أن طلب GET الخاص بـ signInActivity محدود بـ 10 طلبات في الدقيقة.
- انتظر العدد الذي تحدده الترويسة Retry-After، ثم أعد المحاولة. وتذكر Microsoft Learn أن Graph يستمر في تسجيل الاستخدام أثناء التقييد، لذا فإن إعادة المحاولة الفورية تزيد الأمر سوءاً.
- يخفض عدد الطلبات فصلُ الخصائص المكلفة عن استدعاءات كل مستخدم، والترقيم بصفحات أكبر باستخدام $top أعلى، واستخدام delta أو إشعارات التغيير.
- في استدعاء $batch يُقيَّم كل طلب على حدة. فقد يُرجع الاستدعاء الدفعي الرمز 200 بينما تفشل الطلبات الفردية داخله بالخطأ 429، ولن تُعاد محاولتها تلقائياً نيابةً عنك.
طرحت سلسلة ثانية من فبراير 2026 سؤالاً عن كيفية عمل التقييد عند قراءة محركات أقراص SharePoint وOneDrive كثيرة بالتوازي. وعند جمع السلسلتين معاً يتضح أن حدّ المعدل البسيط على جانب العميل غير كافٍ. يشرح هذا المقال ما توثّقه Microsoft Learn، وما اقتصرت عليه السلاسل من اقتراحات. وهو دليل لاستكشاف المشكلات وحلّها، وليس إجراءً رسمياً من Microsoft.
ما أفادت به السلاسل
سلسلة مايو 2026 (نقطة نهاية المستخدمين). تلقى السائل الخطأ 429 على GET /v1.0/users/{id} مع خصائص كثيرة، من بينها signInActivity، إضافة إلى $expand=manager. ولم يفد الترقيم أو المرشحات لأن كل استدعاء كان يُرجع مستخدماً واحداً. وأجاب مشرف من Microsoft بأن الخصائص المكلفة، لا معدل الطلبات وحده، هي ما يسبب التقييد. واقترح تقسيم الاستدعاءات (الملف الشخصي، ونشاط تسجيل الدخول، والمدير)، واحترام الترويسة Retry-After مع التراجع الأُسّي، والتخزين المؤقت، وقراءة نشاط تسجيل الدخول بوتيرة أقل. لم يُعلَّم هذا الجواب كإجابة مقبولة. أما الجواب المولَّد بالذكاء الاصطناعي، الذي عُلّم من السائل كإجابة مقبولة، فقد قال ما يقارب ذلك. ولم يذكر السائل ما إذا كانت أخطاء 429 قد توقفت.
سلسلة فبراير 2026 (driveItems). أراد صاحب السؤال أن يعرف هل تُطبَّق قيود الإنهاء (throttling) على مستوى الموقع أو على مستوى المحرك، وما مستوى التزامن الآمن. أجابت جهة مجهولة، وقبِل صاحب السؤال الإجابة، بأن الحدود تتوزع على طبقات: المستأجر والتطبيق والخدمة، وأن الطلبات الموجهة إلى مواقع مختلفة قد تستهلك الحصة نفسها، وأنه ينبغي احترام Retry-After، واستخدام $batch، وتفضيل الاستعلامات التفاضلية (delta queries) وإشعارات التغيير على الاستطلاع المتكرر. لم تذكر الإجابة أي رقم للتزامن. وقال صاحب السؤال إنها ساعدته.
الخطوة 1: اقرأ استجابة 429 بعناية
سجّل ثلاثة أشياء في كل فشل: عنوان URL للطلب، وقيمة Retry-After، والوقت. تقترح صفحة استكشاف أخطاء Graph PowerShell في Learn تشغيل الأمر مع -Debug لمشاهدة طريقة HTTP والعنوان URI ورمز الحالة، وتنص على تسجيل الترويستين request-id وdate إذا فتحت تذكرة دعم.
لم تذكر السلسلة المنشورة في مايو 2026 قيمة Retry-After. ومن دونها لا يستطيع أحد أن يحدد أي حد وصل إليه السكربت.
الخطوة 2: احترم Retry-After
صفحة الإنهاء (throttling) في Learn واضحة في هذا الشأن:
- انتظر عدد الثواني المذكور في الترويسة
Retry-After. - أعد إرسال الطلب.
- إذا فشل الطلب بالرمز 429 مرة أخرى، فاستمر في استخدام التأخير نفسه حتى ينجح.
يوضح Learn السبب: تواصل Microsoft Graph تسجيل استهلاك الموارد أثناء تعرّض العميل للإنهاء، لذلك فإن التراجع بحسب الترويسة هو أسرع طريقة للتعافي. أما إعادة المحاولة الفورية فتزيد من استهلاكك. وإذا لم تتضمن الاستجابة ترويسة Retry-After، توصي Learn باستخدام التراجع الأُسّي (exponential backoff).
تذكر Learn أن حزم تطوير البرمجيات (SDK) الخاصة بـ Microsoft Graph تتولى ذلك بالفعل. ولا تقول الشيء نفسه عن أوامر Graph PowerShell، فلا تفترض ذلك. وإذا كان السكربت يغلّف استدعاءات خام، مثل Invoke-MgGraphRequest، فابنِ آلية الانتظار بنفسك.
الخطوة 3: حدّد الاستدعاءات المكلفة
تتضمن صفحة الحدود الخاصة بكل خدمة في Learn قسمًا لتقارير الهوية والوصول. وهي تسرد هذه الأرقام، وقد تتغير:
- أي طلب ضمن هذه المجموعة: 122 طلبًا كل 10 ثوانٍ لكل تطبيق عبر جميع المستأجرين، و5 طلبات كل 10 ثوانٍ لكل تطبيق لكل مستأجر.
GET signInActivity: 10 طلبات في الدقيقة.
سكربتك الذي ينفّذ استدعاءً واحدًا كل عشر ثوانٍ يُجري 6 استدعاءات في الدقيقة، وهو أقل من 10 على الورق. لا تذكر السلسلة ما إذا كانت مهام أخرى من تسجيل التطبيق نفسه تعمل في الوقت ذاته. ستتشارك تلك المهام الحصة نفسها، لأن الحدود تُطبَّق لكل تطبيق ولكل مستأجر. وهذا استنتاج من جدول الحدود في Learn، وليس شيئًا تذكره السلسلة صراحةً.
تذكر Learn أيضًا أن $select=signInActivity في استدعاء List users قد يسبب إنهاءً أشد صرامة من الاستدعاءات القياسية. وتنصح بما يلي:
- استخدم
$top=500، وهو الحد الأقصى لحجم الصفحة عند تحديدsignInActivity، بدلًا من القيمة الافتراضية 100. - استخدم
$filterعلىcreatedDateTimeللاستعلام عن فترات زمنية أصغر. ابدأ بنحو ثلاثة أيام من البيانات، وضيّق الفترة إذا تعرضت للإنهاء. - تحتاج الخاصية
signInActivityإلى ترخيص Microsoft Entra ID P1 أو P2 والإذنAuditLog.Read.All، وفقًا لصفحة List users في Learn.
إذا احتجت إلى نشاط تسجيل الدخول لعدد كبير من المستخدمين، فإن استدعاء قائمة مثل GET /v1.0/users?$select=displayName,userPrincipalName,signInActivity&$top=500 يُرجع ما يصل إلى 500 مستخدم في الطلب الواحد. وهذا يعني طلبات أقل بكثير من استدعاء واحد لكل مستخدم. وتوثّق صفحة List users في Learn هذا الطلب مع signInActivity. ولا تذكر الصفحة ما إذا كان أخف على جانب الخدمة أيضًا، لذلك قِس الأمر بنفسك.
اقترح المشرف في سلسلة مايو قراءة signInActivity عبر نقطة النهاية beta. أما مرجع v1.0 الحالي في Learn فيوثّق signInActivity، لذلك لا ينبغي أن تحتاج إلى beta من أجله. تحقّق من توفر الخاصية في نقطة النهاية التي تستخدمها.
الخطوة 4: قلّل عدد الطلبات
تتفق أفضل الممارسات في Learn مع ذلك:
- قلّل عدد العمليات في كل طلب، وتكرار الاستدعاءات.
- تجنّب الاستطلاع المستمر والفحص المنتظم للمجموعات الكبيرة. استخدم تتبع التغييرات (الاستعلامات التفاضلية) وإشعارات التغيير متى توفرت.
- خزّن مؤقتًا البيانات التي لا تتغير كثيرًا، مثل علاقات المدير بالموظف. هذه نصيحة من المشرف في سلسلة مايو، وليست بيانًا من Learn.
الخطوة 5: استخدم $batch بحذر
يمكن للتجميع (batching) أن يقلل رحلات الذهاب والإياب على الشبكة. تفرض صفحة JSON batching في Learn حدًا قدره 20 طلبًا فرديًا في الدفعة الواحدة. وتذكر الصفحة أيضًا ما يلي:
- يُقيَّم كل طلب ضمن الدفعة وفق حدود التقييد (throttling) الخاصة به بشكل مستقل. إذا تجاوز أحدها الحدود، يفشل ذلك الطلب برمز 429، بينما تُرجع الدفعة نفسها 200. ويمكن أن يخضع عدة طلبات في الدفعة الواحدة للتقييد.
- أعد محاولة كل طلب فاشل باستخدام قيمة
retry-afterالواردة في نص الاستجابة لذلك الطلب تحديدًا. وتقول Learn إنه يمكنك إعادة محاولة جميع الطلبات في دفعة جديدة بعد أطول قيمةretry-after. - إذا كان SDK يعيد محاولة الطلبات المقيَّدة عندما لا تكون ضمن دفعة، فإن الطلبات المقيَّدة داخل الدفعة لا تُعاد محاولتها تلقائيًا.
لذا فإن الدفعات لا تُزيل الحد، بل تنقل منطق إعادة المحاولة إلى الشيفرة الخاصة بك.
الخطوة 6: تخطيط قراءات SharePoint وOneDrive
بالنسبة لعمليات فحص المحركات (drive scans)، تذكر صفحة Learn الخاصة بالتقييد في SharePoint أن SharePoint Online يُرجع 429 أو 503 مع ترويسة Retry-After، وأن الطلبات المقيَّدة تُحتسب ضمن الحدود. وتذكر الصفحة حدود التقييد على نطاق المستخدم والمستأجر والتطبيق، وأن حدودها الخاصة بكل موقع تقتصر على الروابط المجهولة وحركة المرور الصادرة المجهولة. لا تخطط وفق حصة منفصلة لكل موقع. نقاط أخرى من تلك الصفحة:
- تُعد حركة المرور التي لا تحمل معرّف تطبيق ولا سلسلة User-Agent غير مزوَّدة بمعلومات التعريف (undecorated). وتقول Learn إن الحركة المزوَّدة جيدًا تُمنح أولوية على الحركة غير المزوَّدة. وصيغ User-Agent الموثَّقة هي
ISV|CompanyName|AppName/VersionوNONISV|CompanyName|AppName/Version. - يكلّف الاستعلام عن عنصر واحد وحدة موارد واحدة، ويكلّف الاستعلام عن عدة عناصر أو عملية كتابة وحدتين، أما عمليات الأذونات، بما فيها
$expand=permissions، فتكلّف 5 وحدات. تجنّب توسيع الأذونات في عمليات الفحص الجماعي. - توصي Learn باستخدام Microsoft Graph بدلًا من CSOM وREST متى أمكن ذلك، لأنه يستهلك عادةً موارد أقل.
تطرّق الخيط الخاص بشهر فبراير أيضًا إلى 410 Gone في استعلامات delta. وذكرت الإجابة هناك أن ذلك يعني أنه لم يعد بالإمكان استخدام رمز delta، وأن على العميل أن يبدأ من جديد باستعلام delta أوّلي جديد. خطّط لذلك في أي مزامنة تزايدية.
التحقق
- سجّل عدد استجابات 429 وقيم
Retry-Afterلتشغيل واحد قبل تطبيق التغييرات وبعده. - شغّل السكربت وحده، دون أي مهمة أخرى تستخدم تسجيل التطبيق نفسه، لترى أثر استدعاءاتك أنت.
- إذا استمر التقييد مع تطبيق التراجع الصحيح وتقليل الاستدعاءات، فاجمع ترويستي
request-idوdateوافتح طلب دعم.
الحدود
- لا توجد نتيجة مؤكدة لخيط مايو 2026، وقد كانت الإجابة المقبولة فيه مولّدة بالذكاء الاصطناعي. وإرشادات Learn الواردة أعلاه هي الدليل المعتمد هنا.
- لم يُجَب في الخيط أبدًا عن سؤال صاحب الخيط حول المستخدمين الذين لا تحتوي حساباتهم على كتلة
signInActivity، ولا تصف Learn ذلك أيضًا، لذا تعامل مع غياب الكتلة على أنه غير معروف. لكن Learn تذكر أنlastSuccessfulSignInDateTimeلا تُستكمل بأثر رجعي قبل 1 ديسمبر 2023، لذا فإن القيمة الفارغة لا تثبت أن المستخدم لم يسجّل الدخول قط. - تُعلَن الحدود التي تسردها Learn على أنها قابلة للتغيير. تحقق من الصفحة المباشرة قبل أن تبني على أي رقم.
ذو صلة
المصادر
- Microsoft Learn: إرشادات التقييد في Microsoft Graph
- Microsoft Learn: حدود التقييد الخاصة بخدمات Microsoft Graph
- Microsoft Learn: دمج عدة طلبات باستخدام JSON batching
- Microsoft Learn: سرد المستخدمين
- Microsoft Learn: نوع المورد signInActivity
- Microsoft Learn: تجنب التعرض للتقييد أو الحظر في SharePoint Online
- Microsoft Learn: استكشاف الأخطاء الشائعة وإصلاحها في Microsoft Graph PowerShell
- Microsoft Q&A: مشكلة التقييد في نقطة النهاية users (مايو 2026)
- Microsoft Q&A: سلوك التقييد في Microsoft Graph عند معالجة driveItems بشكل متوازٍ (فبراير 2026)