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