Directory API: الحدود والحصص

تحمي الحدود والحصص بنية Google الأساسية من العمليات التلقائية التي تستخدم Directory API بطريقة غير ملائمة. قد تنتج الطلبات الزائدة من واجهة برمجة التطبيقات عن خطأ مطبعي غير ضار، أو قد تنتج عن نظام مصمّم بشكل غير فعّال يُجري طلبات بيانات غير ضرورية من واجهة برمجة التطبيقات. بغض النظر عن السبب، من الضروري حظر الزيارات الواردة من مصدر معيّن بعد وصولها إلى مستوى معيّن، وذلك للحفاظ على سلامة نظام Google Workspace بشكل عام. ويضمن ذلك عدم تأثير إجراءات مطوّر واحد سلبًا على المنتدى الأكبر.

في حال تعذّر طلب البيانات من واجهة برمجة التطبيقات، وهو أمر غير محتمل، تعرض واجهة برمجة التطبيقات رمز حالة HTTP وسبب الخطأ. بالإضافة إلى ذلك، يتضمّن نص الاستجابة وصفًا تفصيليًا لسبب الخطأ.

تعرض القائمة التالية رموز الأخطاء المحتملة وأسبابها وأوصافها المقابلة والإجراءات المقترَحة للأخطاء الناتجة عن بلوغ حدود الحصة.

الرمز	السبب	الوصف	الإجراء المقترَح
403	userRateLimitExceeded	يشير إلى أنّه تم تجاوز الحدّ الأقصى لمعدّل المستخدمين. القيمة التلقائية المحدّدة في وحدة تحكّم Google Cloud هي 2,400 طلب بحث في الدقيقة لكل مستخدم لكل مشروع على Google Cloud.	يمكنك زيادة الحدود لكل مستخدم من صفحة حصص واجهة برمجة تطبيقات مدير SDK في مشروعك على السحابة الإلكترونية على Google Cloud، أو خفض معدّل إرسال الطلبات باستخدام الانتظار الأسي.
403	quotaExceeded	يشير هذا الخطأ إلى أنّه تم بلوغ الحدّ الأقصى لعدد الطلبات المتزامنة لعملية معيّنة.	أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي، وعليك إبطاء معدّل إرسال الطلبات.
429	rateLimitExceeded	يشير هذا الخطأ إلى أنّه تم بلوغ الحدّ الأقصى لعدد الطلبات المتزامنة لعملية معيّنة.	أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. عليك إبطاء معدّل إرسال الطلبات. ينطبق هذا الحدّ على كل حساب Google Workspace، وليس على كل عميل واجهة برمجة تطبيقات أو كل مستخدم. ولا يمكن زيادة هذا الحد.

تنفيذ خوارزمية الرقود الأسي الثنائي

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

في ما يلي خطوات تنفيذ خوارزمية الرقود الأسي الثنائي البسيطة.

1. إرسال طلب إلى واجهة برمجة التطبيقات
2. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة فيه
3. الانتظار لمدة ثانية واحدة + random_number_milliseconds ثانية
4. إعادة محاولة إرسال الطلب
5. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة فيه
6. الانتظار لمدة ثانيتين + random_number_milliseconds ثانية
7. إعادة محاولة إرسال الطلب
8. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة فيه
9. الانتظار لمدة 4 ثوانٍ + random_number_milliseconds ثانية
10. إعادة محاولة إرسال الطلب
11. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة فيه
12. الانتظار لمدة 8 ثوانٍ + random_number_milliseconds ثانية
13. إعادة محاولة إرسال الطلب
14. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة فيه
15. الانتظار لمدة 16 ثانية + random_number_milliseconds ثانية
16. إعادة محاولة إرسال الطلب
17. إذا استمر ظهور الخطأ، توقَّف وسجِّل الخطأ.

في العملية أعلاه، يمثّل random_number_milliseconds عددًا عشوائيًا من الملّي ثانية أقل من أو يساوي 1000. وهذا أمر ضروري لتجنُّب بعض أخطاء القفل في بعض عمليات التنفيذ المتزامنة. يجب إعادة تحديد random_number_milliseconds بعد كل انتظار.

ملاحظة: تكون مدة الانتظار دائمًا (2 ^ n) + random_number_milliseconds، حيث n هو عدد صحيح يتزايد بشكل منتظم ويتم تحديده في البداية على أنّه 0. تتم زيادة n بمقدار 1 لكل تكرار (لكل طلب).

تم ضبط الخوارزمية على الإنهاء عندما تكون n تساوي 5. يتم وضع هذا الحدّ الأقصى فقط لمنع العملاء من إعادة المحاولة بشكل لا نهائي، ويؤدي إلى تأخير إجمالي يبلغ حوالي 32 ثانية قبل أن يتم اعتبار الطلب "خطأ غير قابل للإصلاح". ويمكن لعميل واجهة برمجة التطبيقات تنفيذ عدد أكبر من المحاولات إذا لزم الأمر.

حدود واجهة برمجة التطبيقات وحصصها

فئات حدود واجهة برمجة التطبيقات	الحدود
إنشاء حسابات المستخدمين	لا يمكنك إنشاء أكثر من 10 مستخدمين لكل نطاق في الثانية باستخدام واجهة برمجة التطبيقات Directory API.
حذف حسابات المستخدمين	يمكنك حذف ما يصل إلى 5 مستخدمين لكل نطاق في الثانية باستخدام واجهة برمجة تطبيقات الدليل. هذا الحدّ الأقصى لخدمة الخلفية لكل نطاق ولا يمكن تعديله في حصص مشاريع Google Cloud Console. عند إرسال طلبات مجمّعة، تأكَّد من أنّ إجمالي العمليات في جميع المجموعات يبقى أقل من 5 طلبات في الثانية.
حذف أعضاء المجموعة	يمكنك حذف ما يصل إلى 30 عضوًا في المجموعة لكل نطاق في الثانية باستخدام واجهة برمجة التطبيقات Directory API. هذا الحدّ الأقصى لخدمة الخلفية لكل نطاق ولا يمكن تعديله في حصص مشاريع Google Cloud Console. عند إرسال طلبات مجمّعة، تأكَّد من أنّ إجمالي العمليات في جميع الدفعات يظل أقل من 30 طلب بحث في الثانية.
تمت إضافة المجموعة كعضو إلى مجموعة أخرى	قد يحدث تأخير لمدة تصل إلى 10 دقائق قبل ظهور أعضاء المجموعة الفرعية كأعضاء في المجموعة الرئيسية. قد يتغيّر هذا الحدّ استنادًا إلى سعة النظام.
الأجهزة الجوّالة	باستخدام واجهة برمجة التطبيقات Directory API، يمكنك إجراء ما يصل إلى: ‫20 طلب إجراء في الثانية ‫20 طلب حذف في الثانية ‫10 طلبات استرداد بيانات باستخدام GET في الثانية ‫10 طلبات قائمة في الثانية
إعادة تسمية المستخدمين	قد يستغرق نشر التغييرات في جميع الخدمات مدة تصل إلى 10 دقائق. قبل إعادة تسمية مستخدم، يُنصح بتسجيل خروج المستخدم من جميع جلسات المتصفّح والخدمات. لمزيد من التفاصيل، يُرجى الاطّلاع على تعديل بيانات المستخدمين.
إنشاء الوحدات التنظيمية أو تعديلها	لا يمكنك إنشاء/تعديل أكثر من وحدة تنظيمية واحدة لكل عميل في الثانية باستخدام واجهة برمجة التطبيقات Directory API. يقتصر التدرّج الهرمي للوحدة التنظيمية للعميل على 35 مستوى من العمق. يجب ألا يتجاوز إجمالي عدد الوحدات التنظيمية لكل عميل 40,000 وحدة.
فئات حصص واجهة برمجة التطبيقات	الحِصص
أجهزة Chrome‏ annotatedLocation، الحد الأقصى لعدد الأحرف	الحد الأقصى لعدد الأحرف لمعلومات الموقع الجغرافي للجهاز هو 200 حرف.
أجهزة Chrome‏ notes، الحد الأقصى لعدد الأحرف	الحد الأقصى لعدد الأحرف في معلومات ملاحظات الجهاز هو 500 حرف.
أجهزة Chrome، ‏user حرف كحد أقصى	الحد الأقصى لعدد الأحرف في اسم مستخدم الجهاز هو 100 حرف.
الحد الأقصى لأسماء النطاقات المستعارة	الحدّ الأقصى لعدد أسماء النطاقات المستعارة هو 20.
"مجموعات Google"، الوصف	الحد الأقصى لعدد الأحرف في الوصف هو 4,096 حرفًا.
المجموعات لكل حساب	باستخدام حساب الإصدار المجاني القديم من G Suite، يقتصر عدد المجموعات على 10 مجموعات. أما الإصدارات الأخرى، فليس لها حد أقصى لعدد المجموعات.
المجموعات، عدد الأعضاء في كل مجموعة	باستخدام حساب الإصدار المجاني القديم من G Suite، يمكن أن تحتوي المجموعة على ما يصل إلى 100 عضو. لا تفرض الإصدارات الأخرى حدًا أقصى لعدد الأعضاء الذين يمكن أن تضمهم المجموعة. لمعرفة حدود عضوية المجموعة لكل مستخدم، يُرجى الاطّلاع على فهم سياسات "مجموعات Google" وحدودها
سلسلة طلب البحث maxResults	تعرض واجهة برمجة التطبيقات ما يلي: ‫Chrome والأجهزة الجوّالة: الإعداد التلقائي والحد الأقصى هو 100 إدخال لكل صفحة. المجموعات وأعضاء المجموعات: 200 إدخال تلقائي كحد أقصى لكل صفحة المستخدمون: 100 إدخال تلقائيًا و500 إدخال كحد أقصى لكل صفحة لا تستخدم موارد الوحدة التنظيمية والعنوان البديل للمستخدم تقسيم الاستجابة إلى صفحات. يتم عرض جميع عناوين البريد الإلكتروني الأساسية للمستخدمين بترتيب أبجدي، ولا يكون ترتيب الاستجابة حساسًا لحالة الأحرف.
نطاقات متعددة، الحد الأقصى لعدد النطاقات المسموح بها في الحساب	‫600 (نطاق أساسي واحد + 599 نطاقًا إضافيًا)
الوحدة التنظيمية، الحد الأقصى لعدد المستخدمين الذين تم نقلهم في وقت واحد	يمكن نقل 20 مستخدمًا في المرة الواحدة. ويجب أن تكون عناوين البريد الإلكتروني الرئيسية للمستخدمين متوفّرة في الحساب.
الأسماء البديلة للمستخدمين	الحد الأقصى لعدد العناوين البديلة المسموح بها لكل حساب مستخدم هو 30 عنوانًا.
العناوين البديلة للمستخدمين، باستخدام عنوان بديل محذوف	يمكن استخدام عنوان بديل للبريد الإلكتروني لمستخدم محذوف مرة أخرى على الفور.

أنواع أخرى من الحدود	القيود والإرشادات
الفوترة وإنشاء المستخدمين	بالنسبة إلى المستخدمين المشتركين في خطة مرنة في Google Workspace، سيؤدي إنشاء مستخدمين باستخدام واجهة برمجة التطبيقات هذه إلى تأثير مالي، وسيؤدي إلى فرض رسوم على حساب فوترة العميل. على سبيل المثال، إذا كنت مشتركًا في خطة مرنة في Google Workspace، سيؤدي إنشاء 10 مستخدمين إلى فرض رسوم مقابل 10 تراخيص في Google Workspace على حسابك، ويتم احتسابها بشكل نسبي من وقت إنشاء الحسابات. إذا كنت مشتركًا في خطة سنوية، تكون قد التزمت مسبقًا بالدفع مقابل عدد معيّن من التراخيص، ولا يمكنك إنشاء عدد من المستخدمين يتجاوز التزامك. لمزيد من المعلومات عن خطط الفوترة وحساب الفوترة، يُرجى الاطّلاع على مركز مساعدة الإدارة.
الاسم الأول واسم العائلة	يجب ألا يتجاوز الاسم الأول واسم العائلة 40 حرفًا. وهي تتيح استخدام أحرف Unicode/UTF-8، ويمكن أن تحتوي على مسافات وأحرف (a-z) وأرقام (0-9) وشرطات (-) وشرطات مائلة للأمام (/) ونقاط (.). لمزيد من المعلومات حول قواعد استخدام الأحرف، يُرجى الاطّلاع على مركز مساعدة المشرفين.
المجموعات، حذف	لا يؤدي حذف مجموعة إلى حذف حسابات مستخدمي أعضاء المجموعة.
المجموعات وأعضاء المجموعات، تغيير عنوان البريد الإلكتروني	في هذا الإصدار من واجهة برمجة التطبيقات، يمكن تغيير عنوان البريد الإلكتروني للمجموعة قبل تفعيل خدمة Google Workspace. استخدِم وحدة تحكّم المشرف في Google لتغيير عنوان البريد الإلكتروني لعضو في المجموعة. بعد التغيير، تعكس واجهة برمجة التطبيقات تلقائيًا التغييرات في عنوان البريد الإلكتروني.
المجموعات، الإعدادات	تتم إدارة إعدادات الوصول إلى المجموعات وخيارات المشاركة والمراقبة وأرشيف المناقشات باستخدام "وحدة تحكّم المشرف في Google". لمزيد من المعلومات حول إعدادات المجموعات، يُرجى الاطّلاع على مركز مساعدة الإدارة.
المجموعات، إرسال الرسائل	لمنع الرسائل غير المرغوب فيها وإساءة استخدام البريد الإلكتروني، تضع Google حدًا أقصى لعدد الرسائل التي يمكنك إرسالها في آنٍ واحد إلى مستلِمين خارجيين. إذا أرسلت رسالة إلى مجموعة، يتم احتساب كل عضو خارجي كمستلم واحد. لمزيد من المعلومات، يُرجى الاطّلاع على عدد الرسائل الإلكترونية المسموح بإرسالها ومنع حظر الرسائل الإلكترونية المُرسَلة إلى مستخدمي Gmail أو إرسالها إلى مجلد الرسائل غير المرغوب فيها.
"مجموعات Google"، إرسال رسائل تقرير عدم التسليم	لا يمكنك إرسال إشعارات بعدم التسليم (NDR)، والتي تُعرف أيضًا باسم "رسائل مرتدة"، أو إعادة توجيهها إلى مجموعة.
المجموعات التي ينشئها المستخدمون والقيود	لمعرفة الحدود القصوى للمجموعات التي ينشئها المستخدمون، يُرجى الاطّلاع على مركز مساعدة الإدارة
الوحدة التنظيمية، تفعيل الخدمات أو إيقافها	يمكنك استخدام "وحدة تحكّم المشرف في Google" لإدارة تفعيل الخدمات وإيقافها لوحدة تنظيمية.
كلمات المرور	يمكن أن يحتوي على أي مجموعة من الأحرف. يجب إدخال 8 أحرف على الأقل. الحد الأقصى للطول هو 100 حرف.
الصور	في هذا الإصدار من واجهة برمجة التطبيقات، تكون الصورة هي أحدث صورة للملف الشخصي للمستخدم في حساب Google.
أسماء المستخدمين	يمكن أن تحتوي أسماء المستخدمين على أحرف (a-z) وأرقام (0-9) وشرطات (-) وشرطات سفلية (_)، ويتعرّف Google Workspace على النقاط (.)، وهذا ليس هو الحال في Gmail. لا يجوز أن يحتوي اسم المستخدم على علامة يساوي (=) أو قوسين (<،>) أو أكثر من نقطة واحدة (.) في صف واحد. لمزيد من المعلومات، يُرجى الاطّلاع على مركز مساعدة الإدارة.
أسماء المستخدمين، إعادة التسمية	يتجاهل Google Hangouts جميع دعوات المحادثة المحفوظة بعد إعادة التسمية. على المستخدم طلب الإذن للدردشة مع الأصدقاء مرة أخرى. يتم الاحتفاظ باسم المستخدم القديم كعنوان بديل للبريد الإلكتروني لضمان استمرار تسليم الرسائل في حال ضبط إعدادات إعادة توجيه الرسائل الإلكترونية، ولن يكون متاحًا كاسم مستخدم جديد. للحصول على تفاصيل مهمة حول تأثير إعادة تسمية المستخدمين، يُرجى الانتقال إلى مركز مساعدة المشرفين. استخدِم عملية حذف عنوان بديل لمستخدم لإزالة العنوان البديل للبريد الإلكتروني بعد إعادة التسمية.
المستخدمون في نطاقات متعدّدة	يمكن أن يتضمّن حساب Google Workspace أيًا من نطاقاتك. في حساب النطاقات المتعددة، يمكن للمستخدمين في نطاق واحد مشاركة الخدمات مع المستخدمين في نطاقات الحساب الأخرى. مكوّنات النطاقات المتعددة هي: النطاق الأساسي: النطاق الأساسي لحسابك هو نطاق المشرف الذي وافق على اتفاقية بنود خدمة Google Workspace. يقع هذا النطاق على مستوى الحساب في الوحدة التنظيمية ذات المستوى الأعلى. عند الاشتراك في حساب Google Workspace، ننصحك باستخدام نطاق نشاطك التجاري كنطاق أساسي، والاحتفاظ بنطاقاتك الأخرى للاستخدامات المتخصصة، مثل الإصدارات التجريبية والاختبار. يمكن لجميع المشرفين المتميّزين إدارة الحساب بالكامل. لا يمكن لواجهة برمجة التطبيقات تغيير النطاق الأساسي لحساب Google Workspace أو نقله. ومع ذلك، يمكن لواجهة برمجة التطبيقات إعادة تسمية حساب مستخدم، وتغيير عنوان بريده الإلكتروني من نطاق إلى آخر. بالنسبة إلى حسابات Google Workspace، لديك 21 يومًا لإثبات ملكيتك للنطاق الأساسي. بالنسبة إلى النطاقات الإضافية، يجب إثبات ملكية نطاقك قبل استخدام النطاق لعنوان البريد الإلكتروني الرئيسي للمستخدم. وفي هذه الحالات، لا تسري فترة السماح التي تبلغ 21 يومًا. في هذا الإصدار من واجهة برمجة التطبيقات، تنطبق إعدادات النطاق الأساسي على جميع النطاقات المرتبطة بالحساب باستثناء وصول المستخدم إلى خدمات Google Workspace. نطاقات الحساب الإضافية: بعد إنشاء نطاقك الأساسي وإعداد حسابك، يمكنك إضافة نطاقاتك الإضافية إلى الحساب. بالنسبة إلى النطاقات الإضافية، عليك إثبات ملكيتك عند إعداد هذا النطاق وقبل استخدامه لعنوان البريد الإلكتروني الرئيسي للمستخدم. نطاق المستخدم الرئيسي: النطاق المستخدَم في عنوان البريد الإلكتروني الرئيسي للمستخدم هو نطاق المستخدم الرئيسي. يمكن أن يكون هذا النطاق أي نطاق في الحساب، بما في ذلك النطاق الأساسي. للاطّلاع على أحدث القيود المرتبطة بالنطاقات المتعددة، يُرجى مراجعة القيود المرتبطة بالنطاقات المتعددة. ويشمل ذلك معلومات عن أسماء النطاقات المستعارة ودمج الحسابات وما إلى ذلك.
التحذيرات، أعضاء المجموعة	‫GROUP_CANNOT_CONTAIN_CYCLE: لا تسمح واجهة برمجة التطبيقات بدورة في عضويات المجموعة. على سبيل المثال، إذا كانت المجموعة 1 عضوًا في المجموعة 2، لا يمكن أن تكون المجموعة 2 عضوًا في المجموعة 1.