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

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

‫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 دقيقة)، ننصح بأن يرصد الرمز البرمجي الاستثناء ويستخدم خوارزمية الرقود الأسي الثنائي المقتطَع للتأكّد من أنّ أجهزتك لا تُنشئ حملاً زائدًا.

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

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

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

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

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

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

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

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

حِصص خادم MCP في Sheets

يستخدم خادم MCP في Sheets مقاييس طلبات القراءة والكتابة. يوضّح الجدولان التاليان تفاصيل الحِصص وتكلفة طلب البحث لكل طريقة من طرق خادم MCP في Sheets حسب القسم:

حِصص MCP في Sheets

يتم فرض نوعَين من الحِصص:

في الدقيقة لكل مشروع: هذه هي تكلفة طلب البحث في مشروعك على Google Cloud لمدة دقيقة واحدة.
في الدقيقة لكل مستخدم ولكل مشروع: هذه هي تكلفة طلب البحث في مشروعك على Google Cloud لمدة دقيقة واحدة يمكن لأي مستخدم معيّن استخدامها.

يوضّح الجدول التالي تفاصيل هذه الحِصص: