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

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

يتم تحديد الحدود من حيث وحدات الحصة، وهي وحدة قياس مجردة تمثّل استخدام موارد Google Drive.

حصص Drive API

يتم فرض ثلاثة أنواع من الحصص:

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

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

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

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

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

إذا تجاوزت حصة، ستتلقّى ردًا يتضمّن رمز حالة HTTP‏ 403: User rate limit exceeded. قد تؤدي عمليات التحقّق الإضافية من الحد الأقصى لعدد الطلبات في الخلفية في Drive إلى إنشاء استجابة 429: Rate limit exceeded أيضًا. في هذه الحالة، عليك استخدام خوارزمية الرقود الأسي الثنائي وإعادة المحاولة لاحقًا.

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

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

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

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

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

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

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

تكاليف وحدة الحصة لكل طريقة

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

طرق القراءة (5 وحدات من الحصة)

الطريقة
drive.about.get
drive.accessproposals.get
drive.apps.get
drive.approvals.get
drive.changes.get
drive.children.get
drive.comments.get
drive.drives.get
drive.files.get (without alt=media)
drive.parents.get
drive.permissions.get
drive.properties.get
drive.replies.get
drive.revisions.get (without alt=media)
drive.teamdrives.get

طرق عرض القوائم (100 وحدة من الحصة)

الطريقة
drive.accessproposals.list
drive.apps.list
‫drive.changes.list، drive.changes.watch
drive.children.list
drive.comments.list
drive.drives.list
‫drive.files.list، drive.files.watch
drive.parents.list
drive.permissions.list
drive.properties.list
drive.replies.list
drive.revisions.list
drive.teamdrives.list

طرق التعديل (50 وحدة من الحصة)

الطريقة
drive.approvals.decline
‫drive.children.delete، drive.children.insert
drive.comments.create، وdrive.comments.delete، وdrive.comments.insert، وdrive.comments.patch، وdrive.comments.update
drive.drives.create، وdrive.drives.delete، وdrive.drives.hide، وdrive.drives.insert، وdrive.drives.unhide، وdrive.drives.update
‫drive.files.copy، drive.files.create، drive.files.delete، drive.files.emptyTrash، drive.files.insert، drive.files.modifyLabels، drive.files.patch، drive.files.touch، drive.files.trash، drive.files.untrash، drive.files.update
‫drive.parents.delete، drive.parents.insert
drive.permissions.create، وdrive.permissions.delete، وdrive.permissions.insert، وdrive.permissions.patch، وdrive.permissions.update
drive.properties.delete، وdrive.properties.insert، وdrive.properties.patch، وdrive.properties.update
drive.replies.create، وdrive.replies.delete، وdrive.replies.insert، وdrive.replies.patch، وdrive.replies.update
‫drive.revisions.delete، drive.revisions.patch، drive.revisions.update
drive.teamdrives.create، وdrive.teamdrives.delete، وdrive.teamdrives.insert، وdrive.teamdrives.update

طرق التنزيل (200 وحدة حصة)

الطريقة
‫drive.files.download، drive.files.export، drive.files.get (with alt=media)
drive.revisions.get (with alt=media)

الطرق الأخرى (5 وحدات من الحصة)

الطريقة
drive.changes.getStartPageToken
drive.channels.stop
‫drive.files.generateCseToken، drive.files.generateIds، drive.files.listLabels
drive.operations.get
drive.permissions.getIdForEmail

قيود إضافية

يتم فرض القيود التالية عند العمل مع Drive API:

  • يمكن لمستخدمي Google Workspace تحميل 750 غيغابايت فقط يوميًا بين "ملفاتي" وجميع مساحات التخزين السحابي المشتركة، وينطبق هذا الحد أيضًا على النُسخ.

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

  • الحد الأقصى لحجم الملف الذي يمكن للمستخدمين تحميله هو 5 تيرابايت، ولا تكتمل عملية التحميل سوى للملف الأول الذي يتجاوز الحد الأقصى. الحد الأقصى لحجم الملف الذي يمكن للمستخدمين نسخه هو 750 غيغابايت.

  • الإشعارات التي يتم تسليمها إلى العنوان المحدد عند فتح قناة إشعارات لا يتم احتسابها ضمن حدود الحصة. ومع ذلك، يتم احتساب طلبات changes.watch وchannels.stop وfiles.watch من حصتك.

  • طالما أنّك تلتزم بالحصص المحدّدة لكل دقيقة، ليس هناك حدّ أقصى لعدد الطلبات التي يمكنك إجراؤها يوميًا.

  • وفقًا لنوع حسابك على Google Workspace، هناك حدود إضافية لمساحة التخزين في Drive.

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

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

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

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

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

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

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

الأسعار

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

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

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

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

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

حصص خادم MCP في Drive

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

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

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

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

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

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

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

حصص مجموعة أدوات MCP في Drive

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

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

/mcp/v1

copy_file

50

create_file

50

download_file_content

200

get_file_metadata

5

get_file_permissions

5

list_recent_files

100

read_file_content

200

search_files

100

لمزيد من المعلومات، يُرجى الاطّلاع على مرجع واجهة برمجة تطبيقات Drive MCP.