تفرض Google Ads API قيودًا على عمليات واجهة برمجة التطبيقات، مثل عدد العمليات التي يمكن إرسالها في طلب تبديل واحد. يلخص الجدول أدناه بعض الحدود والحصص المهمة التي يجب أن تكون على دراية بها.
نوع الطلب وتحديده ورمز الخطأ | |||
---|---|---|---|
الطلبات المقسّمة على صفحات | 10,000 صف في كل صفحة |
INVALID_PAGE_SIZE
|
|
العمليات ذات الوصول الأساسي | 15,000 عملية على واجهة برمجة التطبيقات في اليوم |
RESOURCE_EXHAUSTED
|
|
تبديل الطلبات | 10,000 عملية لكل طلب |
TOO_MANY_MUTATE_OPERATIONS
|
|
التخطيط لطلبات الخدمة | طلب واحد في الثانية |
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
gRPC. ارجع إلى قائمة رسائل ورموز خطأ 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
.