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

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

نوع الطلب والقيود ورمز الخطأ
العمليات التي تتطلب إذن الوصول الأساسي	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 واحد على أنّه عملية واحدة لواجهة برمجة التطبيقات بغض النظر عن عدد الدفعات.

الطلبات التي تتضمّن صفحات

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

لمزيد من التفاصيل حول تقسيم الصفحات، يُرجى الاطّلاع على مقالة التنقّل بين النتائج باستخدام ميزة تقسيم الصفحات.

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

إنّ الطلب الذي لا يخصّ Get أو Mutate أو Search أو SearchStream يُحتسَب كعملية واحدة ضمن حصة المستخدم اليومية من العمليات.

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

• BatchJobService.ListMutateJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

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

إنّ الطلبات المرفوضة باستخدام الرمز GoogleAdsFailure تظلّ مُحتسَبة ضمن حصة العمليات اليومية للمستخدم.

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

خدمة تخطيط الكلمات الرئيسية

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

• يقتصر على طلب واحد في الثانية لكل معرّف مستخدم:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

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

• يتم احتساب طلب بحث واحد في الثانية على أنّه 60 طلبًا في 60 ثانية.

• تقتصر على طلبَين في الثانية لكل رقم تعريفي للعميل:

  • KeywordPlanIdeaService.GenerateAdGroupTheme

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

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

خدمة "إحصاءات الجمهور"

تخضع الطرق التالية ضمن methods AudienceInsightsService methods لحدود حصص محدّدة.

• تقتصر على 200 طلب تقريبًا في اليوم لكل معرّف حملة:

  • AudienceInsightsService.generateAudienceCompositionInsights
  • AudienceInsightsService.generateSuggestedTargetingInsights

• محدودة بـ طلبَين في الثانية لكل رمز مميّز للمطوّر:

  • AudienceInsightsService.generateTargetingSuggestionMetrics

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

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

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

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

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

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

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

  ويتم رفض الطلبات التي تنتهك هذا الحدّ مع ظهور رسالة الخطأ: MUTATE_NOT_ALLOWED.

• يُسمح بإجراء عملية واحدة فقط لطلبات التعديل.

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

يُسمح لك باستخدام ما يصل إلى 100,000 معرّف مستخدم بغض النظر عن عدد العمليات.

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

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

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

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