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

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

سقف الحصص

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

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

يوضّح الجدول التالي حدود الطلبات:

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

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

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

أثناء استخدام ((sheets_api_short))، يُرجى الانتباه إلى السلوك والقيود التالية التي تؤثر في حصصك:

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

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

  • يتم تطبيق جميع طلبات "جداول بيانات Google" بشكل متزامن. وهذا يعني أنّه إذا كان أي طلب غير صالح، سيتعذّر إجراء التعديل بالكامل ولن يتم تطبيق أي من التغييرات (التي قد تكون مرتبطة ببعضها).

  • هناك حدّ زمني أقصى لمعالجة طلب واحد من طلبات البيانات من واجهة برمجة التطبيقات. عندما تعالج "جداول بيانات Google" طلبًا لمدة تزيد عن 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. واصِل الانتظار وإعادة المحاولة حتى الحد الأقصى لعدد المحاولات، ولكن لا تزد فترة الانتظار بين المحاولات.

where:

  • يبلغ وقت الانتظار 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 بمرور الوقت، قد تحتاج إلى زيادة قيم الحصة. إذا كنت تتوقّع زيادة كبيرة في الاستخدام قريبًا، يمكنك بشكل استباقي طلب تعديلات على الحصة من صفحة "الحصص" في Google Cloud Console.

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