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

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

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

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

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

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

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

خدمات التخطيط

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

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

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

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

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

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

  • لا يمكن إجراء عمليات التحويل إلا للحسابات التي تم إعدادها للفواتير الشهرية.

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

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

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

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

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

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