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

تخضع واجهة برمجة التطبيقات Gmail API لحدود استخدام تقيّد معدّل طلب طُرق واجهة برمجة التطبيقات. يتم تحديد الحدود من حيث وحدات الحصة، وهي وحدة قياس مجردة تمثل استخدام موارد Gmail.

حصص Gmail API

تفرض واجهة برمجة التطبيقات Gmail API نوعَين من الحصص:

  • في الدقيقة لكل مشروع: يشير ذلك إلى عدد وحدات الحصة التي يمكن لمشروعك على Google Cloud استخدامها في دقيقة واحدة.

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

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

نوع الحدّ الأقصى للاستخدام الحدّ
في الدقيقة لكل مشروع ‫1,200,000 وحدة حصة
في الدقيقة لكل مستخدم لكل مشروع ‫6,000 وحدة من الحصة

للحصول على معلومات عن معالجة أخطاء الحدود القصوى، يُرجى الاطّلاع على حلّ الأخطاء.

حد الفوترة اليومي

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

ولا يؤدي الاستخدام ضمن هذا الحدّ إلى فرض رسوم إضافية، ولا تتم فوترة حسابك على Google Cloud. ستشارك Google تفاصيل الفوترة الكاملة في وقت لاحق من عام 2026، وسترسل إشعارًا قبل 90 يومًا على الأقل من تطبيق أي تغييرات.

لا يمكنك طلب زيادة هذا الحدّ اليومي.

يوضّح الجدول التالي الحدّ الأقصى:

نوع الحد الأقصى الحدّ
في اليوم لكل مشروع ‫80,000,000 وحدة حصة

لمزيد من المعلومات، يُرجى الاطّلاع على النموذج الموحّد في Google Workspace لأدوات الوكلاء وواجهات برمجة التطبيقات.

استخدام الحصة لكل طريقة

يختلف عدد وحدات الحصة التي يستهلكها كل طلب حسب الطريقة التي تستدعيها ومعلمات طلب البحث. يوضّح الجدول التالي استخدام وحدات الحصة لكل طريقة:

الطريقة وحدات الحصة
drafts.create 10
drafts.delete 10
drafts.get ‫20 (60 عندما تكون قيمة format هي full أو raw أو html)
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get ‫20 (60 عندما تكون قيمة format هي full أو raw أو html)
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get ‫40 (120 عندما تكون قيمة format هي full)
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

عند استخدام Gmail API، هناك أيضًا حدّ أقصى يبلغ 500 مستلِم لكل رسالة إلكترونية.

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

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

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

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

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

  1. قدِّم طلبًا إلى Gmail API.
  2. إذا تعذّر تنفيذ الطلب، انتظِر لمدة ثانية واحدة + random_number_milliseconds وأعِد محاولة تنفيذ الطلب.
  3. إذا تعذّر تنفيذ الطلب، انتظِر لمدة ثانيتين + 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 ثانية. في مرحلة ما، يجب منع العملاء من إعادة المحاولة إلى أجل غير مسمى.

يعتمد وقت الانتظار بين عمليات إعادة المحاولة وعدد عمليات إعادة المحاولة على حالة الاستخدام وظروف الشبكة.

الأسعار

يتوفّر كل الاستخدام العادي لواجهة برمجة التطبيقات Gmail API بدون أي تكلفة إضافية. في حال تجاوز حدود طلبات الحصة، سيتم فرض رسوم على حساب الفوترة في Google Cloud في وقت لاحق من عام 2026. لمزيد من المعلومات، يُرجى الاطّلاع على النموذج الموحّد في Google Workspace لأدوات الوكلاء وواجهات برمجة التطبيقات.

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

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

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

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

الحصص المتاحة لخادم MCP في Gmail

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

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

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

  • في الدقيقة لكل مشروع: يشير ذلك إلى تكلفة طلب البحث لمشروعك على السحابة الإلكترونية في الدقيقة الواحدة.

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

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

نوع الحدّ الأقصى للاستخدام تكلفة طلب البحث
في الدقيقة لكل مشروع 1,200,000
في الدقيقة لكل مستخدم لكل مشروع 6,000

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

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

نقطة نهاية الأداة تكلفة طلب البحث

/mcp/v1

create_draft

10

get_thread

40

label_message

10

label_thread

10

list_drafts

5

list_labels

1

search_threads

10

unlabel_message

10

unlabel_thread

10

لمزيد من المعلومات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات لبروتوكول سياق النموذج (MCP) في Gmail.