تعمل الحدود والحصص على حماية بنية Google الأساسية من العمليات التلقائية التي تستخدم Reports API بطريقة غير ملائمة. قد تنتج الطلبات المفرطة من واجهة برمجة التطبيقات عن خطأ إملائي غير ضار، أو قد تنتج عن نظام مصمّم بشكل غير فعّال يرسل طلبات غير ضرورية إلى واجهة برمجة التطبيقات. وبغض النظر عن السبب، من الضروري حظر عدد الزيارات من مصدر معيّن عند وصوله إلى مستوى معيّن للحفاظ على سلامة نظام Google Workspace بشكل عام. ويضمن ألا تؤثر إجراءات أحد المطوّرين سلبًا على المنتدى الأكبر.
في حال تعذُّر تنفيذ طلبك من واجهة برمجة التطبيقات، ستتلقّى استجابة رمز حالة HTTP. يتضمّن رمز الحالة 403 معلومات خطأ حول الإدخال غير الصحيح، ويتضمّن رمز الحالة 503 معلومات خطأ تشير إلى حصص واجهة برمجة التطبيقات التي تم تجاوزها. تسمح هذه الاستجابات لتطبيقك المخصّص برصد هذه الأخطاء واتّخاذ الإجراء المناسب.
إذا كانت طلباتك بحاجة إلى إكمالها خلال فترة زمنية ثابتة، أرسِل طلباتك بالتوازي أو استخدِم سلاسل محادثات متعددة في تطبيق Java أو C#. من الأمثلة على الطلبات المتوازية طلب مجموعات صغيرة من الرسائل الإلكترونية من مستخدمين مختلفين بدلاً من إضافة أو إزالة الكثير من الرسائل الإلكترونية من مستخدم واحد في الوقت نفسه. في ما يتعلّق بسلاسل المحادثات، جرِّب البدء بـ 10 سلاسل محادثات، أي سلسلة محادثات واحدة لكل عنوان بريد إلكتروني للمستخدم. يُرجى العِلم أنّ اقتراح سلسلة المحادثات له مزايا وعيوب، ولا يكون مفيدًا في جميع حالات استخدام واجهة برمجة التطبيقات. إذا ارتفع عدد الطلبات بشكل كبير، ستحدث أخطاء في الحصة.
بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (بحد أقصى N عنصر لمدة N ثانية لكل سلسلة محادثات)، وخاصةً أخطاء رمز الحالة 503، ننصح بأن يرصد الرمز الاستثناء، وأن ينتظر فترة تأخير قصيرة قبل إعادة محاولة إجراء المكالمة التي تعذّر إجراؤها، وذلك باستخدام خوارزمية التراجع الأسي. أحد الأمثلة على Reports API لموضوع واحد هو الانتظار لمدة 5 ثوانٍ ثم إعادة محاولة المكالمة التي تعذّر إجراؤها. إذا نجح الطلب، كرِّر هذا النمط لسلاسل التعليمات الأخرى. إذا لم ينجح الطلب الثاني، يجب أن يخفّض تطبيقك من معدّل تكرار الطلب إلى أن ينجح أحد الطلبات. على سبيل المثال، يمكنك زيادة فترة التأخير الأولية من 5 ثوانٍ إلى 10 ثوانٍ وإعادة محاولة الاتصال الذي تعذّر مرة أخرى. عليك أيضًا تحديد حدّ لإعادة المحاولة. على سبيل المثال، أعِد محاولة تنفيذ الطلب من 5 إلى 7 مرات مع فترات تأخير مختلفة قبل أن يعرض تطبيقك رسالة خطأ للمستخدم.
الحدود
| فئات حدود واجهة برمجة التطبيقات | الحدود |
|---|---|
| الإبلاغ عن معدّلات طلبات البحث في الثانية وطلبات البحث في اليوم | تفرض واجهة برمجة التطبيقات حدًا أقصى لعدد الطلبات التي يمكن إرسالها إلى مشروعك على Google Cloud.
القيمة التلقائية المضبوطة في وحدة تحكّم Google Cloud هي 2,400 طلب بحث في الدقيقة لكل مستخدم لكل مشروع في Google Cloud.
يمكنك زيادة هذا الحدّ من صفحة حصص واجهة برمجة التطبيقات Admin SDK في مشروعك على Google Cloud.
في حال تجاوز هذه الحدود، يعرض الخادم رمز حالة HTTP 503. استخدِم خوارزمية التراجع السريع للغاية عند إعادة محاولة إرسال طلباتك. |
حدود إضافية لـ activities.list |
تفرض واجهة برمجة التطبيقات activities.list حدًا إضافيًا يبلغ 250 طلب فلترة في الدقيقة (15,000 طلب فلترة في الساعة).
طلب البحث الخاص بالفلتر هو طلب بيانات من واجهة برمجة التطبيقات يحتوي على مَعلمة طلب بحث واحدة على الأقل من مَعلمات طلب البحث التالية:
|
| فئات حصص واجهة برمجة التطبيقات | الحصص |
| maxResults | يتراوح عدد السجلات المُدرَجة في كل صفحة من الردّ الذي تقدّمه واجهة برمجة التطبيقات بين 0 و1,000 سجلّ. القيمة التلقائية هي 1000 سجلّ. |
أنواع أخرى من الحدود
| أنواع أخرى من الحدود | القيود والإرشادات |
|---|---|
| تنسيق البيانات، الإعداد التلقائي | تنسيق البيانات التلقائي هو JSON. تتيح واجهة برمجة التطبيقات أيضًا استخدام تنسيق Atom. |
| الطلبات غير المصرّح بها | لا تسمح Google بالطلبات غير المصرّح بها إلى واجهة برمجة التطبيقات. يُعدّ الطلب غير مصرّح به إذا لم يتم تقديم رمز تفويض. لمزيد من المعلومات، يُرجى الاطّلاع على تفويض الطلبات. |
| رسائل التحذير |
|
أفضل الممارسات المتعلّقة بطريقة activities.list
من المتوقّع استخدام الطريقة activities.list في تحقيقات التدقيق.
للحصول على أفضل أداء، يجب أن يتضمّن طلبك نطاقًا زمنيًا باستخدام المَعلمتَين startTime وendTime. تؤدي النطاقات الزمنية الأضيق إلى تقليل مدة الاستجابة بشكل كبير.
لا يُنصح باستخدام هذه الطريقة لاسترداد عدد كبير من سجلات التدقيق. إذا كنت تستنفد حصة طلبات الفلترة في طريقة activities.list بانتظام، ننصحك باتّباع الخيارات التالية:
- يمكنك إعداد عملية تصدير سجلّات Google Workspace إلى BigQuery واستخدام واجهات برمجة التطبيقات للاستعلام الفعّالة في BigQuery لاسترداد البيانات التي تحتاج إليها وتحليلها بدون أي قيود على حصة واجهة برمجة التطبيقات.
- استخدِم طلبات غير فلترة مع النطاق الزمني ونفِّذ الفلترة من جهة العميل (أي نفِّذ منطق الفلترة في تطبيقك)، بدلاً من استخدام طلبات الفلترة. يتيح لك ذلك تجاوز الحدّ الأقصى البالغ 250 طلب بحث باستخدام الفلاتر في الدقيقة، ولكنك ستظل خاضعًا للحدّ الأقصى البالغ 2,400 طلب بحث في الدقيقة لكل مستخدم لكل مشروع على Google Cloud.