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

تفرض 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.

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

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

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

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

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

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

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

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

• يقتصر على حوالي 200 طلب في اليوم لكل معرّف CID:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• يقتصر على طلبَين في الثانية لكل مشروع على السحابة الإلكترونية على 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.

• يُسمح بإجراء عملية 1 فقط لطلبات التعديل.

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