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

تفرض 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 إحالة ناجحة للمكالمات أو النقرات لكل طلب:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

• يقتصر على 2,000 تعديل للإحالة الناجحة لكل طلب:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  يتم رفض الطلبات التي تنتهك هذه الحدود مع عرض الخطأ: 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.