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

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

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

تستند حدود الاستخدام اليومي لواجهة برمجة التطبيقات إلى عدد عمليات واجهة برمجة التطبيقات التي يتم إجراؤها لكل رمز مميّز للمطوّر. عمليات واجهة برمجة التطبيقات هي المجموع الكلي لطلبات الحصول على البيانات وعمليات التعديل. تعتمد حدود العمليات اليومية لواجهة برمجة التطبيقات على مستوى الوصول الخاص بالرمز المميز للمطوِّر. يحدّد دليل مستويات الوصول والاستخدام المسموح به حدود عمليات واجهة برمجة التطبيقات المحدّدة لكل مستوى وصول.

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

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

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

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

• يقتصر على حوالي 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.

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

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

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

إذا كانت هناك 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 في عملية create أو remove بمستخدم نهائي واحد. يقتصر الحقل user_identifiers ضمن عنصر UserData واحد على 20 معرّفًا كحدّ أقصى. سيؤدي تجاوز هذا الحد في عنصر UserData واحد إلى حدوث خطأ OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS أو UserDataError.TOO_MANY_USER_IDENTIFIERS.

التعامل مع المستخدمين الذين لديهم أكثر من 20 معرّفًا

إذا كان لدى مستخدم نهائي واحد أكثر من 20 معرّفًا عليك تحميلها، عليك توزيع هذه المعرّفات على عدة عناصر UserData. للتأكّد من أنّ Google يمكنه ربط كل هذه المعرّفات بالمستخدم النهائي نفسه، يجب أن يتضمّن كل عنصر UserData لهذا المستخدم معرّفًا واحدًا على الأقل مشتركًا user_identifier، مثل hashed_email أو hashed_phone_number أو third_party_user_id نفسه. تستخدِم Google هذه المعرّفات المشترَكة لربط المعلومات ودمجها من عمليات UserData المنفصلة بملف المستخدم النهائي الصحيح.

إذا كنت تعتمد على معلومات تكشف الهوية الشخصية، مثل عناوين البريد الإلكتروني أو أرقام الهواتف المجزّأة، تأكَّد من تسويتها وتجزئتها وفقًا لمتطلبات Google Ads API (SHA-256، أحرف لاتينية صغيرة، بدون مسافة بيضاء) لتجنُّب حدوث أخطاء في الربط.

على سبيل المثال، إذا كان لدى المستخدم 30 عنوان بريد إلكتروني، يمكنك إرسال كائنَين من النوع UserData

• UserData 1: {third_party_user_id: "user123", hashed_email: "email1@...", ... hashed_email: "email19@..."}
• UserData 2: {third_party_user_id: "user123", hashed_email: "email20@...", ... hashed_email: "email30@..."}

يظل الحدّ الأقصى لإجمالي عدد user_identifiers في جميع العمليات ضمن OfflineUserDataJob واحدة هو 100,000.

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

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

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

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