حدود الاستخدام

‫Google Sheets API هي خدمة مشترَكة، ونحن نفرض حصصًا وقيودًا لحماية الأداء العام لنظام Google Workspace لجميع المستخدمين.

سقف الحصص

على الرغم من أنّ Sheets API لا يفرض حدودًا صارمة على حجم طلب بيانات من واجهة برمجة التطبيقات، قد يواجه المستخدمون حدودًا من مكوّنات معالجة مختلفة لا يتحكّم فيها جداول بيانات Google. لتسريع الطلبات، ننصح بحمولة قصوى تبلغ 2 ميغابايت.

تفرض Sheets API حصصًا في الدقيقة، ويتم إعادة تعبئتها كل دقيقة. على سبيل المثال، هناك حدّ أقصى لطلبات القراءة يبلغ 300 طلب في الدقيقة لكل مشروع. إذا أرسل تطبيقك 350 طلبًا في دقيقة واحدة، يتجاوز عدد الطلبات الإضافية البالغ 50 طلبًا الحصة المسموح بها ويؤدي إلى ظهور الردّ على رمز حالة HTTP 429: Too many requests. في هذه الحالة، عليك استخدام خوارزمية الرقود الأسي الثنائي. بعد دقيقة واحدة، يمكنك تنفيذ الطلبات مرة أخرى.

يوضّح الجدول التالي تفاصيل الحدود القصوى للطلبات:

الحصص
طلبات القراءة
في الدقيقة لكل مشروع 300
في الدقيقة لكل مستخدم في المشروع 60
طلبات الكتابة
في الدقيقة لكل مشروع 300
في الدقيقة لكل مستخدم في المشروع 60

لمعرفة تفاصيل حول الحدود القصوى للملفات، يُرجى الاطّلاع على الملفات التي يمكنك تخزينها في Google Drive.

السلوك والقيود

أثناء استخدام Sheets API، يُرجى العِلم بالسلوك والقيود التالية التي تؤثر في حصصك:

  • طلبات القراءة هي طلبات لأي طريقة تسترد البيانات من جدول بيانات، مثل get أو search. طلبات الكتابة هي طلبات لأي طريقة تغيّر جدول بيانات، مثل update أو clear أو copyTo.

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

  • يتم تطبيق جميع طلبات Sheets بشكل غير قابل للتجزئة. أي إذا لم يكن أي طلب صالحًا، لن ينجح التعديل بالكامل ولن يتم تطبيق أي من التغييرات (التي قد تكون معتمِدة على بعضها).

  • هناك حدّ أقصى للوقت المسموح به لمعالجة طلب واحد من واجهة برمجة التطبيقات. عندما يعالج Sheets طلبًا لأكثر من 180 ثانية، يعرض الطلب خطأ في المهلة.

  • طالما أنّك تلتزم بالحصص في الدقيقة، ليس هناك حدّ لعدد الطلبات التي يمكنك إرسالها في اليوم الواحد.

معالجة أخطاء الحصص المستندة إلى الوقت

بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (الحدّ الأقصى لعدد N من الطلبات خلال X دقيقة)، ننصح بأن يرصد الرمز البرمجي الاستثناء ويستخدم خوارزمية الرقود الأسي الثنائي المقتطَع للتأكّد من أنّ أجهزتك لا تُنشئ حملاً زائدًا.

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

مثال على الخوارزمية

تعيد خوارزمية الرقود الأسي الثنائي محاولة إرسال الطلبات بشكل أسي، ما يؤدي إلى زيادة وقت الانتظار بين عمليات إعادة المحاولة حتى الحدّ الأقصى لوقت الرقود. على سبيل المثال:

  1. أرسِل طلبًا إلى Google Sheets API.
  2. إذا تعذّر إرسال الطلب، انتظِر 1 + random_number_milliseconds وأعِد محاولة إرسال الطلب.
  3. إذا تعذّر إرسال الطلب، انتظِر 2 + random_number_milliseconds وأعِد محاولة إرسال الطلب.
  4. إذا تعذّر إرسال الطلب، انتظِر 4 + random_number_milliseconds وأعِد محاولة إرسال الطلب.
  5. وهكذا، حتى وقت maximum_backoff.
  6. استمر في الانتظار وإعادة المحاولة حتى عدد أقصى من عمليات إعادة المحاولة، ولكن لا تزد فترة الانتظار بين عمليات إعادة المحاولة.

حيث:

  • وقت الانتظار هو 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 Sheets API بشكل عادي بدون أي تكلفة إضافية. من المخطط أن يتم تحصيل رسوم من حساب الفوترة على Google Cloud في وقت لاحق من عام 2026 في حال تجاوز الحدود القصوى لطلبات الحصص. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نموذج Google Workspace الموحّد لأدوات الوكلاء وواجهات برمجة التطبيقات.

طلب زيادة الحصة

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

لا تتساوى الحصص في جميع المشاريع. مع زيادة استخدامك لـ Google Cloud بمرور الوقت، قد تحتاج إلى زيادة قيم الحصص. إذا كنت تتوقّع زيادة ملحوظة في الاستخدام في المستقبل القريب، يمكنك طلب تعديلات الحصص بشكل استباقي من صفحة الحصص وحدود النظام في Google Cloud Console.

لمزيد من المعلومات، يُرجى الاطّلاع على المَراجع التالية: