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

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

نوع الطلب والقيود ورمز الخطأ
العمليات التي تتضمّن مستوى الوصول "اختبار" ‫15,000 عملية في واجهة برمجة التطبيقات يوميًا للحسابات الاختبارية RESOURCE_EXHAUSTED
العمليات التي يمكن إجراؤها باستخدام مستوى الوصول "مستكشف" ‫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

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

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

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

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

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

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

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

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

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

عنصر خطة الكلمات الرئيسية الحد الأقصى للعدد
‫KeywordPlan لكل حساب 10,000
‫KeywordPlanAdGroup لكل KeywordPlan 200
‫KeywordPlanAdGroupKeyword لكل KeywordPlan 10,000
KeywordPlanCampaignKeyword (كلمات رئيسية سلبية) لكل KeywordPlan 1,000
‫KeywordPlanCampaign لكل KeywordPlan 1

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

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

خدمة تحميل الإحالات الناجحة

خدمة تحميل تعديلات الإحالات الناجحة

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

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

السابق
نظرة عامة
التالي
حدود النظام