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

بما أنّ Google Sheets API هي خدمة مشتركة، نطبّق الحصص والقيود للتأكّد من استخدامها بشكل عادل من قِبَل جميع المستخدمين ولحماية السلامة العامة لنظام Google Workspace.

حدود الحصة

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

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

يتم تطبيق جميع طلبات "جداول بيانات Google" Atomy. ويعني ذلك أنّه إذا لم يكن أي طلب صالحًا، لن يتم تنفيذ التعديل بالكامل ولن يتم تطبيق أي من التغييرات (التي من المحتمل أن تكون مرتبطة).

يوضِّح الجدول التالي تفاصيل حدود الطلب. بشرط أن تبقى في نطاق حصص كل دقيقة، لن يكون هناك حدّ أقصى لعدد الطلبات التي يمكنك تقديمها في اليوم.

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

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

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

بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (بحد أقصى عدد الطلبات من 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" بدون أي تكلفة إضافية. لا يؤدي تجاوز حدود طلب الحصة إلى فرض رسوم إضافية، ولا يتم تحصيل رسوم من حسابك.

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

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

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

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