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

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

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

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

الرمز السبب الوصف الإجراء المقترَح
403 userRateLimitExceeded يشير إلى أنه تم تجاوز حد معدل المستخدمين. إنّ القيمة التلقائية المحدَّدة في Google Cloud Console هي 2,400 طلب بحث في الدقيقة لكل مستخدم لكل مشروع على Google Cloud. يمكنك زيادة الحدود لكل مستخدم من خلال صفحة حصص واجهة برمجة التطبيقات Admin SDK API في مشروعك على 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، بينما تتم زيادته بمقدار 1 لكل تكرار (كل طلب).

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

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

فئات حدود واجهة برمجة التطبيقات الحدود القصوى المسموح بها
إنشاء حسابات المستخدمين لا يمكنك إنشاء أكثر من 10 مستخدمين لكل نطاق في الثانية باستخدام واجهة برمجة التطبيقات للدليل.
تمت إضافة المجموعة كعضو إلى مجموعة أخرى. قد يكون هناك تأخير يصل إلى 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 أو إرسالها إلى مجلد الرسائل غير المرغوب فيها .
"مجموعات Google" وإرسال رسائل NDR لا يمكنك إرسال أو إعادة توجيه إيصالات عدم التسليم (NDR)، التي تُعرف أيضًا باسم "الرسائل المرتدة"، إلى مجموعة.
المجموعات التي أنشأها المستخدمون، القيود لمعرفة حدود المجموعات التي أنشأها المستخدم، يُرجى الاطّلاع على مركز مساعدة المشرف.
الوحدة التنظيمية، تفعيل الخدمات أو إيقافها يمكنك استخدام "وحدة تحكُّم المشرف" لإدارة تفعيل الخدمات وإيقافها لوحدة تنظيمية.
كلمات المرور يمكن أن يحتوي على أي مجموعة من الأحرف. يجب إدخال 8 أحرف على الأقل. الحد الأقصى لعدد الأحرف المسموح به هو 100 حرف.
صور Google في هذا الإصدار من واجهة برمجة التطبيقات، تكون الصورة هي أحدث صورة ملف شخصي للمستخدم في حساب 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.