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

تفرض 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، مثل الطلبات التي تعذّر تنفيذها بسبب حدوث خطأ على مستوى الشبكة، ضمن الحصة اليومية المخصّصة للمستخدم لأنّ الطلبات لن تصل إلى الخدمة أبدًا. ومن الأمثلة على ذلك حدوث عطل في الاتصال بالشبكة.

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

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

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

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

قواعد قيمة الإحالة الناجحة

• يقتصر على 100,000 قاعدة لقيمة الإحالة الناجحة لكل حساب.

  ويتم رفض الطلبات التي تنتهك هذا الحدّ مع ظهور الخطأ ResourceCountLimitExceededError.ACCOUNT_LIMIT.

ملاحظة: لا تكون قواعد قيم الإحالات الناجحة التي يتم إنشاؤها باستخدام واجهة برمجة التطبيقات الخاصة بـ "إعلانات Google" نشطة إلا إذا كانت جزءًا من مجموعة قواعد قيم الإحالات الناجحة التي تتضمّن أسماء موارد ConversionValueRule في حقل conversion_value_rules، والتي تم ضبط الحالة ConversionValueRuleSet فيها على ENABLED. لا تظهر قواعد قيم الإحالات الناجحة التي لا تشكّل جزءًا من أي مجموعة قواعد قيم إحالات ناجحة في واجهة مستخدم "إعلانات Google"، ولا يمكن إدارتها إلا باستخدام واجهة برمجة التطبيقات.

إذا كانت هناك ConversionValueRuleSet تتضمّن attachment_type بقيمة CUSTOMER في الحساب، عليك إضافة أي قواعد جديدة لقيمة الإحالة الناجحة إلى هذه المجموعة لتصبح نشطة. إذا لم تكن هناك مجموعة قواعد لقيم الإحالات الناجحة، عليك إنشاء مجموعة وإضافة قواعد قيم الإحالات الناجحة إليها كما هو موضّح في مقالة إنشاء مجموعات قواعد.

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

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

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