حدود واجهة برمجة التطبيقات والحصص

تفرض Google Ads API قيودًا على عمليات واجهة برمجة التطبيقات، مثل عدد العمليات التي يمكن إرسالها في طلب تبديل واحد. يلخص الجدول أدناه بعض الحدود والحصص المهمة التي يجب أن تكون على دراية بها.

نوع الطلب وتحديده ورمز الخطأ
الطلبات المقسّمة على صفحات 10000 صف لكل صفحة INVALID_PAGE_SIZE
العمليات ذات الوصول الأساسي 15,000 عملية عبر واجهة برمجة التطبيقات في اليوم RESOURCE_EXHAUSTED
تبديل الطلبات 10,000 عملية لكل طلب TOO_MANY_MUTATE_OPERATIONS
طلبات خدمات التخطيط 1 QPS RESOURCE_EXHAUSTED
طلبات خدمة تحميل الإحالات الناجحة 2,000 إحالة ناجحة لكل طلب TOO_MANY_CONVERSIONS_IN_REQUEST
طلبات الفوترة وخدمة ميزانية الحساب عملية واحدة لكل طلب تبديل TOO_MANY_MUTATE_OPERATIONS

الحدود اليومية لعمليات واجهة برمجة التطبيقات

تستند الحدود اليومية للاستخدام لواجهة برمجة التطبيقات إلى عدد عمليات واجهة برمجة التطبيقات التي يتم إجراؤها لكل رمز مميز للمطوِّر. عمليات واجهة برمجة التطبيقات هي المجموع الإجمالي لطلبات الحصول على وعمليات التبديل. تعتمد حدود العمليات اليومية لواجهة برمجة التطبيقات على مستوى الوصول إلى الرمز المميز للمطوِّر. يوضِّح دليل مستويات الوصول والاستخدام المسموح به حدود عمليات واجهة برمجة التطبيقات المحدَّدة لكل مستوى وصول.

ويتم رفض الطلبات التي تنتهك هذه الحدود مع عرض الخطأ التالي: RESOURCE_EXHAUSTED.

قيود gRPC

تستخدم جميع مكتبات عملاء Google Ads API gRPC لإنشاء الطلبات والردود. يبلغ حجم الرسالة تلقائيًا في gRPC 4 ميغابايت، إلا أن مكتبات العملاء تضبط الحد الأقصى لحجم الرسالة على 64 ميغابايت لرفع الكفاءة.

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

ولن تؤدي الطلبات التي تنتهك هذا القيد إلى إنشاء GoogleAdsError، بل ستنتج عنها خطأ "429 Resource Exhausted" في "الملف التجاري على Google". راجِع قائمة رموز خطأ gRPC ورسائله.

تبديل الطلبات

بالإضافة إلى الاحتساب ضمن حصة التشغيل اليومية للمستخدم، لا يمكن أن يحتوي طلب التبديل على أكثر من 10,000 عملية لكل طلب.

يتم رفض الطلبات التي تخالف هذا الشرط مع عرض الخطأ التالي: TOO_MANY_MUTATE_OPERATIONS.

وقد وضّحنا أدناه حدودًا واعتبارات إضافية لخدمات وأنواع طلبات معيّنة.

طلبات البحث

يتم احتساب طلب Search أو SearchStream كعملية واحدة مقابل حصة التشغيل اليومية للمستخدم. يتم احتساب طلب SearchStream واحد كعملية واحدة لواجهة برمجة التطبيقات بغض النظر عن عدد الدفعات.

الطلبات المقسّمة على صفحات

ولا يتم احتساب الطلبات المقسّمة على صفحات (مثل الطلبات التي تحتوي على next_page_token صالح) ضمن حصة التشغيل اليومية للمستخدم. أمّا طلبات التقسيم على صفحات التي تحتوي على رمز مميّز للصفحة منتهي الصلاحية أو غير صالح، فستنشئ استثناءً وسيتم احتسابها ضمن حصة التشغيل اليومية.

تخضع الطلبات المقسّمة على صفحات، مثل طلبات البحث، إلى قيد Page size cannot exceed 10,000 rows ويتم رفضها في حال انتهاكها لهذا الحدّ، مع ظهور الخطأ التالي: INVALID_PAGE_SIZE.

لمزيد من التفاصيل عن التقسيم على صفحات، راجِع التقسيم إلى صفحات ضمن النتائج.

الأنواع الأخرى من الطلبات

الطلب الذي لا يندرج ضمن طلبات Get أو Mutate أو Search أو SearchStream يتم احتسابه كعملية واحدة مقابل حصة التشغيل اليومية للمستخدم.

في ما يلي بعض الأمثلة على هذه الطلبات:

الطلبات التي تعرض استثناءات واجهة برمجة التطبيقات

ستبقى الطلبات المرفوضة مع GoogleAdsFailure تُحتسب ضمن حصة التشغيل اليومية للمستخدم.

إنّ الطلبات التي يتعذّر إرسالها ولكنها لا تعرض GoogleAdsFailure، مثل الطلبات الواردة من خطأ على مستوى الشبكة، لن يتم احتسابها ضمن حصة التشغيل اليومية للمستخدم لأنّ الطلبات لن تصل أبدًا إلى الخدمة. أحد الأمثلة على ذلك هو فشل الاتصال بالشبكة.

خدمات التخطيط

بسبب التكلفة والتعقيد، تخضع طرق خدمة التخطيط الواردة أدناه لحدود منفصلة عن أنواع الطلبات الأخرى.

يجب مراعاة هذه الحدود عند إنشاء خطة الكلمات الرئيسية.

عنصر خطة الكلمات الرئيسية الحد الأقصى للعدد
KeywordPlan لكل حساب 10,000
KeywordPlanAdGroup لكل KeywordPlan 200
KeywordPlanAdGroupKeyword لكل KeywordPlan 10,000
KeywordPlanCampaignKeyword (الكلمات الرئيسية السلبية) 1,000
KeywordPlanCampaign لكل KeywordPlan 1

خدمة تحميل الإحالات الناجحة

خدمة تحميل تسوية الإحالات الناجحة

خدمات الفوترة وميزانية الحساب

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

    يتم رفض الطلبات التي تخالف هذا الشرط مع عرض الخطأ التالي: MUTATE_NOT_ALLOWED.

  • يُسمح بعملية 1 فقط لطلبات التبديل.

    يتم رفض الطلبات التي تخالف هذا الشرط مع عرض الخطأ التالي: TOO_MANY_MUTATE_OPERATIONS.

  • يجب الانتظار لمدة 12 ساعة على الأقل بين تغييرات أمر تحديد الميزانية في الحساب نفسه. إنّ إجراء التغييرات قبل انقضاء 12 ساعة قد يؤدي إلى حدوث أعطال لا يمكن استردادها ولا يمكن حلّها إلا من قِبل ممثّل حسابك على "إعلانات Google".

دعوات إلى حسابات العملاء

يمكن دعوة المستخدمين الجدد إلى حسابات عملاء حالية باستخدام CustomerUserAccessService. بما أنّ هذه الوظيفة ترسل دعوات بالبريد الإلكتروني إلى مستخدمين آخرين، من المحتمل إساءة استخدامها، وبالتالي هناك قيود على سلوكها:

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

  • لا يمكن أن تحتوي حسابات العملاء على أكثر من 70 دعوة في انتظار المراجعة في وقت واحد. إذا تم إرسال طلب أدّى إلى تجاوز هذه القيمة، سيتم عرض هذا الخطأ: ACCESS_INVITATION_ERROR_PENDING_INVITATIONS_LIMIT_EXCEEDED.

بيانات المستخدم

تتم إدارة بيانات المستخدمين من خلال UserDataService وOfflineUserDataJobService. في عملية إنشاء/إزالة UserData، يجب أن تكون كل مجموعة من user_identifiers خاصة بمستخدم واحد.

لفرض ذلك، يتم عرض خطأ OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS أو UserDataError.TOO_MANY_USER_IDENTIFIERS عند وجود أكثر من 20 user_identifiers في مجموعة UserData واحدة.

الأنواع الأخرى من الحدود

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

إذا واجهت هذا القيد وكنت تُجري طلبات تستخدم حقلاً متكرّرًا، جرِّب تقليل عدد العناصر في الحقل المتكرّر من خلال نشر قائمة بالعمليات في طلب تغيير.

عند إجراء طلب بحث GAQL، يكون الحد الأقصى لعدد العناصر داخل عبارة IN هو 20,000. وإذا تجاوزت هذا الحدّ، سيتم عرض خطأ FILTER_HAS_TOO_MANY_VALUES.