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

تفرض 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 واحد كعملية واحدة لواجهة برمجة التطبيقات بغض النظر عن عدد الدفعات.

الطلبات التي تتضمّن صفحات

لا يتم احتساب الطلبات التي يتم تقسيمها إلى صفحات (مثل الطلبات التي تحتوي على قيمة صالحة لملف شخصي على Google) ضمن حصة العمليات اليومية للمستخدم.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 رسالة خطأ.

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