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

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

حصص Gmail API

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

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

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

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

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

للحصول على معلومات حول التعامل مع أخطاء الحدّ الأقصى، اطّلِع على حلّ الأخطاء.

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

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

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

ولا يمكنك طلب زيادة الحدّ الأقصى اليومي.

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

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

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

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

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

الطريقة وحدات الحصة
drafts.create 10
drafts.delete 10
drafts.get 20
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
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
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

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

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

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

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

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

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

  1. إرسال طلب إلى Gmail 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 ثانية بعد الوصول إلى هذه القيمة. في مرحلة ما، يجب منع البرامج من إعادة المحاولة إلى أجل غير مسمّى.

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

الأسعار

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

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

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

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

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