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

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

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

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

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

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

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

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

  1. تقديم طلب إلى واجهة برمجة التطبيقات
  2. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة
  3. الانتظار لمدة ثانية واحدة + random_number_milliseconds ثانية
  4. إعادة محاولة إرسال الطلب
  5. تلقّي ردّ يفيد بحدوث خطأ يتضمّن رمز خطأ يمكن إعادة المحاولة
  6. الانتظار لمدة 2 ثانية + 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.
المجموعة التي تمت إضافتها كعضو في مجموعة أخرى قد يحدث تأخير يصل إلى 10 دقائق قبل ظهور أعضاء المجموعة الفرعية كأعضاء في المجموعة الرئيسية. وقد يتغيّر هذا الحدّ الأقصى حسب سعة النظام.
الأجهزة الجوّالة

باستخدام Directory API، يمكنك تنفيذ ما يصل إلى:

  • 20 طلب إجراء في الثانية
  • 20 طلب حذف في الثانية
  • 10 طلبات الحصول في الثانية
  • 10 طلبات قوائم في الثانية
إعادة تسمية المستخدمين قد يستغرق نشر التغييرات في جميع الخدمات مدة تصل إلى 10 دقائق. قبل إعادة تسمية مستخدم، يُنصح بتسجيل خروج المستخدم من جميع جلسات المتصفّح والخدمات. لمزيد من التفاصيل، يُرجى الاطّلاع على تعديل المستخدمين.
إنشاء وحدات تنظيمية أو تعديلها
  • لا يمكنك إنشاء أو تعديل أكثر من وحدة تنظيمية واحدة لكل عميل في الثانية باستخدام Directory API.
  • يقتصر العرض الهرمي للوحدة التنظيمية للعميل على 35 مستوى.
  • يجب ألا يتجاوز إجمالي عدد الوحدات التنظيمية لكل عميل 40,000.
فئات الحصص في واجهة برمجة التطبيقات الحصص
أجهزة Chrome annotatedLocation، الحد الأقصى لعدد الأحرف الحد الأقصى لعدد الأحرف في معلومات الموقع الجغرافي للجهاز هو 200 حرف.
أجهزة Chrome notes، الحد الأقصى لعدد الأحرف الحد الأقصى لعدد الأحرف في معلومات ملاحظات الجهاز هو 500 حرف.
أجهزة Chrome، user حرف كحد أقصى الحد الأقصى لعدد الأحرف في اسم مستخدم الجهاز هو 100 حرف.
الحد الأقصى لعدد أسماء النطاقات المستعارة الحد الأقصى لعدد الأسماء المستعارة للنطاقات هو 20.
المجموعات والوصف الحد الأقصى لعدد الأحرف في الوصف هو 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 حدًا أقصى لعدد الرسائل التي يمكنك إرسالها في آنٍ واحد إلى المستلمين الخارجيين. إذا أرسلت رسالة إلى مجموعة، يتم احتساب كل عضو خارجي على أنّه مستلِم واحد. لمزيد من المعلومات، يُرجى الاطّلاع على حدود إرسال الرسائل الإلكترونية ومنع حظر الرسائل الإلكترونية المُرسَلة إلى مستخدمي Gmail أو إرسالها إلى مجلد الرسائل غير المرغوب فيها .
المجموعات التي تُرسِل رسائل "تعذُّر التسليم" لا يمكنك إرسال إيصالات عدم التسليم (NDR) أو إعادة توجيهها، وتُعرف أيضًا باسم "الرسائل المرتدة"، إلى مجموعة.
المجموعات التي أنشأها المستخدمون والقيود المفروضة عليها للاطّلاع على الحدود القصوى للمجموعات التي أنشأها المستخدم، يُرجى الانتقال إلى مركز مساعدة الإدارة.
الوحدة التنظيمية، تفعيل الخدمات أو إيقافها استخدِم "وحدة تحكّم المشرف" لإدارة تفعيل الخدمات وإيقافها لوحدة تنظيمية.
كلمات المرور يمكن أن يحتوي على أي مجموعة من الأحرف. يجب إدخال 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.