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

تخضع واجهة برمجة التطبيقات 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.

المواضيع ذات الصلة

• طلبات مجمّعة
• نصائح بشأن الأداء
• الحدود المسموح بها لإرسال الرسائل الإلكترونية وتلقّيها
• عدد الرسائل المسموح بإرسالها على Gmail في Google Workspace