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