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

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

إذا تجاوزت الحصة، ستتلقّى بشكل عام استجابة برمز حالة HTTP ‏429: Too many requests. في حال حدوث ذلك، عليك استخدام خوارزمية الرقود الأسي الثنائي وإعادة المحاولة لاحقًا.

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

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

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

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

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

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

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

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

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

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

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

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

حصص خادم MCP في "مستندات Google"

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

حصص بروتوكول سياق النموذج (MCP) في "مستندات Google"

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

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

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

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

حصص مجموعة أدوات بروتوكول سياق النموذج (MCP) في "مستندات Google"

يوضّح الجدول التالي تكلفة طلب البحث لكل مجموعة أدوات من docsmcp.googleapis.com:

نقطة نهاية الأداة تكلفة طلب البحث
/mcp/v1 read_doc طلب قراءة واحد
update_doc طلب كتابة واحد

لمزيد من المعلومات، يُرجى الاطّلاع على مرجع Docs MCP API.