بما أنّ Google Docs API هي خدمة مشترَكة، نفرض حصصًا وقيودًا لضمان استخدامها بشكل عادل من قِبل جميع المستخدمين وحماية سلامة نظام Google Workspace بشكل عام.
إذا تجاوزت حصة معيّنة، ستتلقّى بشكل عام استجابة برمز حالة HTTP
429: Too many requests. وفي هذه الحالة، عليك استخدام خوارزمية الرقود الأسي الثنائي وإعادة المحاولة لاحقًا.
يوضّح الجدول التالي حدود الطلبات:
| الحصص | |||||
|---|---|---|---|---|---|
| طلبات القراءة |
|
||||
| طلبات الكتابة |
|
||||
معالجة أخطاء الحصص المستندة إلى الوقت
بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (الحد الأقصى لعدد N من الطلبات خلال X دقيقة)، ننصحك بأن يرصد الرمز البرمجي الاستثناء ويستخدم رقودًا أسيًا ثنائيًا مقطوعًا لضمان عدم تحميل أجهزتك حملاً زائدًا.
الرقود الأسي الثنائي هو استراتيجية عادية لمعالجة الأخطاء في تطبيقات الشبكة. تعيد خوارزمية الرقود الأسي الثنائي محاولة إرسال الطلبات باستخدام أوقات انتظار متزايدة بشكل أسي بين الطلبات، وذلك حتى الحد الأقصى لوقت الرقود. إذا استمر تعذُّر إرسال الطلبات، من المهم زيادة حالات التأخير بين الطلبات بمرور الوقت إلى أن يتم إرسال الطلب بنجاح.
مثال على خوارزمية
تعيد خوارزمية الرقود الأسي الثنائي محاولة إرسال الطلبات بشكل أسي، ما يؤدي إلى زيادة وقت الانتظار بين عمليات إعادة المحاولة حتى الحد الأقصى لوقت الرقود. على سبيل المثال:
- أرسِل طلبًا إلى Google Docs API.
- إذا تعذّر إرسال الطلب، انتظِر 1 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - إذا تعذّر إرسال الطلب، انتظِر 2 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - إذا تعذّر إرسال الطلب، انتظِر 4 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - وهكذا، حتى وقت
maximum_backoff. - استمِر في الانتظار وإعادة المحاولة حتى عدد أقصى معيّن من عمليات إعادة المحاولة، ولكن لا تزد فترة الانتظار بين عمليات إعادة المحاولة.
حيث:
- وقت الانتظار هو
min(((2^n)+random_number_milliseconds), maximum_backoff), مع زيادةnبمقدار 1 لكل تكرار (طلب). random_number_millisecondsهو عدد عشوائي من الملّي ثانية أقل من أو يساوي 1,000. يساعد ذلك في تجنُّب الحالات التي تتم فيها مزامنة العديد من البرامج من خلال حالة معيّنة وإعادة المحاولة في الوقت نفسه، ما يؤدي إلى إرسال الطلبات في موجات متزامنة. تتم إعادة احتساب قيمةrandom_number_millisecondsبعد كل طلب إعادة محاولة.maximum_backoffهو عادةً 32 أو 64 ثانية. تعتمد القيمة المناسبة على حالة الاستخدام.
يمكن للبرنامج مواصلة إعادة المحاولة بعد بلوغ وقت maximum_backoff.
لا تحتاج عمليات إعادة المحاولة بعد هذه النقطة إلى مواصلة زيادة وقت الرقود. على
سبيل المثال، إذا كان البرنامج يستخدم وقت maximum_backoff يبلغ 64 ثانية، يمكنه بعد بلوغ
هذه القيمة إعادة المحاولة كل 64 ثانية. في مرحلة معيّنة،
يجب منع البرامج من إعادة المحاولة إلى أجل غير مسمّى.
يعتمد وقت الانتظار بين عمليات إعادة المحاولة وعدد عمليات إعادة المحاولة على حالة الاستخدام وظروف الشبكة.
الأسعار
إنّ جميع الاستخدامات العادية لـ Google Docs API متاحة بدون أي تكلفة إضافية. من المخطط أن يتم تحصيل رسوم من حساب الفوترة على Google Cloud في وقت لاحق من عام 2026 مقابل تجاوز حدود طلبات الحصة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نموذج Google Workspace الموحّد لأدوات الوكلاء وواجهات برمجة التطبيقات.
طلب زيادة الحصة
بناءً على استخدام مشروعك للموارد، قد تحتاج إلى طلب تعديل الحصة. تُعتبَر طلبات واجهة برمجة التطبيقات التي يرسلها حساب خدمة مستخدِمةً حسابًا واحدًا. لا يضمن التقدم بطلب للحصول على حصة معدَّلة الموافقة. قد تستغرق طلبات تعديل الحصة التي ستؤدي إلى زيادة قيمة الحصة بشكل كبير وقتًا أطول للموافقة عليها.
لا تتساوى الحصص في جميع المشاريع. مع زيادة استخدامك لـ Google Cloud بمرور الوقت، قد تحتاج إلى زيادة قيم الحصص. إذا كنت تتوقّع زيادة ملحوظة في الاستخدام في المستقبل القريب، يمكنك بشكل استباقي طلب تعديلات الحصة من صفحة الحصص وحدود النظام في Google Cloud Console.
لمزيد من المعلومات، يُرجى الاطّلاع على المَراجع التالية: