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

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

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

تستند حدود الاستخدام اليومي لواجهة برمجة التطبيقات إلى عدد عمليات واجهة برمجة التطبيقات التي يجريها مشروعك على Google Cloud. عمليات واجهة برمجة التطبيقات هي المجموع الكلي لطلبات Search وSearchStream، وعمليات التعديل الفردية، وطلبات الخدمة الأخرى. تعتمد حدود العمليات اليومية في واجهة برمجة التطبيقات على مستوى الوصول إلى واجهة برمجة التطبيقات في مشروعك على Google Cloud. يحدّد دليل مستويات الوصول والاستخدام المسموح به حدود عمليات واجهة برمجة التطبيقات لكل مستوى وصول.

يتم رفض الطلبات التي تخالف هذه الحدود القصوى مع ظهور رسالة الخطأ: RESOURCE_EXHAUSTED.

قيود gRPC

تستخدم جميع مكتبات برامج Google Ads API بروتوكول gRPC لإنشاء الطلبات والردود. يبلغ حجم الرسالة في gRPC تلقائيًا 4 ميغابايت، ولكن تضبط مكتبات العملاء الحد الأقصى لحجم الرسالة على 64 ميغابايت لزيادة الكفاءة.

يجب ألا تتجاوز الردود هذا الحدّ. على سبيل المثال، قد يؤدي طلب البحث الذي يتضمّن الكثير من الحقول إلى إنشاء ردّ يتجاوز حجمه 64 ميغابايت. لتجنُّب هذا الحدّ، يمكنك تقليل عدد الحقول المحدّدة أو استخدام البث. بالنسبة إلى عمليات التغيير، أرسِل عددًا أقل من العمليات لكل طلب.

الطلبات التي تخالف هذا الحدّ لن تؤدي إلى إنشاء GoogleAdsError، بل ستؤدي إلى إنشاء خطأ RESOURCE_EXHAUSTED (رمز gRPC‏ 8 / HTTP‏ 429). يُرجى الرجوع إلى قائمة رموز ورسائل أخطاء gRPC.

طلبات التغيير

بالإضافة إلى احتساب طلب التغيير ضمن حصة العمليات اليومية للمستخدم، لا يمكن أن يحتوي طلب التغيير على أكثر من 10,000 عملية تغيير لكل طلب. يتم رفض الطلبات التي تخالف هذا الحدّ الأقصى مع ظهور رسالة الخطأ: TOO_MANY_MUTATE_OPERATIONS.

في ما يلي، نوضّح الحدود والاعتبارات الإضافية لخدمات وأنواع طلبات معيّنة.

طلبات البحث

يتم احتساب طلب Search أو SearchStream كعملية واحدة من حصة العمليات اليومية للمستخدم. يتم احتساب طلب واحد من SearchStream كعملية واحدة في واجهة برمجة التطبيقات بغض النظر عن عدد الدفعات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

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

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

• يقتصر على 200 طلب تقريبًا في اليوم لكل رقم تعريف عميل:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• يقتصر على طلبَين (2) في الثانية لكل مشروع على السحابة الإلكترونية على Google Cloud:
  • 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 ساعة على الأقل بين تغييرات ميزانية الحساب (AccountBudget أو AccountBudgetProposal) في الحساب نفسه. قد يؤدي إجراء تغييرات قبل مرور 12 ساعة إلى حدوث أخطاء غير قابلة للاسترداد لا يمكن حلّها إلا من خلال ممثل حسابك على "إعلانات Google".

الدعوات إلى حسابات العملاء

يمكن دعوة مستخدمين جُدد إلى حسابات عملاء حالية باستخدام CustomerUserAccessInvitationService. بما أنّ هذه الميزة ترسل دعوات بالبريد الإلكتروني إلى مستخدمين آخرين، من المحتمل أن تتم إساءة استخدامها، وبالتالي هناك قيود على سلوكها:

• لا يمكن للمستخدمين تلقّي أكثر من دعوة واحدة في انتظار المراجعة لحساب العميل نفسه. إذا تم تقديم طلب لاحق لإرسال دعوة إلى مستخدم لديه دعوة معلّقة، سيظهر هذا الخطأ: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• لا يمكن أن تتلقّى حسابات العملاء أكثر من 70 دعوة في انتظار المراجعة في الوقت نفسه. في حال إرسال طلب يؤدي إلى تجاوز هذه القيمة، سيظهر الخطأ التالي: 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 يتشاركان قيمة third_party_user_id (من خلال وضع thirdPartyUserId بالإضافة إلى عناوين البريد الإلكتروني من 1 إلى 19 في العنصر الأول للبقاء ضمن الحدّ الأقصى المسموح به وهو 20 معرّفًا، وthirdPartyUserId بالإضافة إلى عناوين البريد الإلكتروني من 20 إلى 30 في العنصر الثاني):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

الحدّ الأقصى الإجمالي لـ user_identifiers في جميع العمليات في AddOfflineUserDataJobOperationsRequest واحد هو 100,000 (يمكن أن يقبل OfflineUserDataJob طلبات AddOfflineUserDataJobOperationsRequest متعددة، بحدّ أقصى مقترَح يبلغ 1,000,000 عملية لكل مهمة). بالنسبة إلى عمليات التحميل المتزامنة باستخدام UploadUserDataRequest (UserDataService.UploadUserData)، يقتصر كل طلب على 10 عمليات كحدّ أقصى و100 user_identifiers في الطلب بأكمله.

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

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

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

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