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

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

نوع الطلب والقيود ورمز الخطأ
العمليات التي يمكن تنفيذها باستخدام مستوى الوصول "مستكشف"	‫2,880 عملية في واجهة برمجة التطبيقات يوميًا مقابل حسابات الإنتاج ‫15,000 عملية في واجهة برمجة التطبيقات يوميًا مقابل حسابات الاختبار	RESOURCE_EXHAUSTED
العمليات التي يمكن تنفيذها باستخدام مستوى الوصول الأساسي	‫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 صالح) ضمن حصة العمليات اليومية للمستخدم. ومع ذلك، فإنّ طلبات تقسيم الصفحات التي تحتوي على رمز مميز للصفحة منتهي الصلاحية أو غير صالح ستؤدي إلى إنشاء استثناء وسيتم احتسابها ضمن حصة العمليات اليومية.

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

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

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

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

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

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

تُحتسب الطلبات التي يتم رفضها مع ظهور الخطأ GoogleAdsFailure ضمن حصة العمليات اليومية للمستخدم.

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

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

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

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

  • 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

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

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

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

  • 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.