تفرض 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
يتم احتسابه كعملية واحدة مقابل حصة التشغيل اليومية للمستخدم.
في ما يلي بعض الأمثلة على هذه الطلبات:
BatchJobService.ListMutateJobResults
ConversionUploadService.UploadCallConversions
ConversionUploadService.UploadClickConversions
OfflineUserDataJobService.AddOfflineUserDataJobOperations
OfflineUserDataJobService.CreateOfflineUserDataJob
UserDataService.UploadUserData
الطلبات التي تعرض استثناءات واجهة برمجة التطبيقات
ستبقى الطلبات المرفوضة مع GoogleAdsFailure
تُحتسب ضمن
حصة التشغيل اليومية للمستخدم.
إنّ الطلبات التي يتعذّر إرسالها ولكنها لا تعرض GoogleAdsFailure
، مثل الطلبات الواردة من خطأ على مستوى الشبكة، لن يتم احتسابها ضمن حصة التشغيل اليومية للمستخدم لأنّ الطلبات لن تصل أبدًا إلى الخدمة. أحد الأمثلة على ذلك هو
فشل الاتصال بالشبكة.
خدمات التخطيط
بسبب التكلفة والتعقيد، تخضع طرق خدمة التخطيط الواردة أدناه لحدود منفصلة عن أنواع الطلبات الأخرى.
يقتصر على طلب واحد في الثانية لكل رقم تعريفي أو رمز مميز للمطوِّر:
KeywordPlanService.GetKeywordPlan
KeywordPlanService.GenerateHistoricalMetrics
KeywordPlanService.GenerateForecastMetrics
يتم رفض الطلبات التي تنتهك هذه القيود مع عرض الخطأ التالي:
RESOURCE_EXHAUSTED
.ويتم احتساب طلب واحد في الثانية من خلال 60 طلبًا لكل 60 ثانية.
يجب مراعاة هذه الحدود عند إنشاء خطة الكلمات الرئيسية.
عنصر خطة الكلمات الرئيسية | الحد الأقصى للعدد |
---|---|
KeywordPlan لكل حساب |
10,000 |
KeywordPlanAdGroup لكل KeywordPlan |
200 |
KeywordPlanAdGroupKeyword لكل KeywordPlan |
10,000 |
KeywordPlanCampaignKeyword (الكلمات الرئيسية السلبية) |
1,000 |
KeywordPlanCampaign لكل KeywordPlan |
1 |
خدمة تحميل الإحالات الناجحة
يقتصر على 2,000 إحالة ناجحة للمكالمات أو النقرات لكل طلب:
ويتم رفض الطلبات التي تنتهك هذه الحدود مع عرض الخطأ التالي:
TOO_MANY_CONVERSIONS_IN_REQUEST
.
خدمة تحميل تسوية الإحالات الناجحة
يقتصر على 2,000 تعديل للإحالة الناجحة لكل طلب:
ويتم رفض الطلبات التي تنتهك هذه الحدود مع عرض الخطأ التالي:
TOO_MANY_ADJUSTMENTS_IN_REQUEST
.
خدمات الفوترة وميزانية الحساب
لا يمكن إجراء عمليات التبديل إلا على الحسابات التي تم إعدادها لنظام الفواتير الشهرية.
يتم رفض الطلبات التي تخالف هذا الشرط مع عرض الخطأ التالي:
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
.