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

تفرض 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 واحد كعملية واحدة على واجهة برمجة التطبيقات بغض النظر عن عدد الدفعات.

الطلبات المقسّمة إلى صفحات

لا يتم احتساب الطلبات المقسّمة إلى صفحات (مثل الطلبات التي تحتوي على 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

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

تخضع الطرق التالية ضمن طرق 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.