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

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

نوع الطلب والقيد ورمز الخطأ
الطلبات المقسّمة على صفحات	10000 صف في كل صفحة	INVALID_PAGE_SIZE
العمليات ذات الوصول الأساسي	15,000 عملية لواجهة برمجة التطبيقات يوميًا	RESOURCE_EXHAUSTED
طلبات التبديل	10000 عملية لكل طلب	TOO_MANY_MUTATE_OPERATIONS
التخطيط لطلبات الخدمة	1 طلب في الثانية	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 صالحة) ضمن حصة العمليات اليومية للمستخدم. ومع ذلك، ستُنشِئ طلبات التقسيم على صفحات التي تحتوي على رمز مميّز للصفحة منتهي الصلاحية أو غير صالح استثناءً وسيتم احتسابها ضمن حصة العمليات اليومية.

تخضع أيضًا الطلبات المقسّمة إلى صفحات، مثل طلبات البحث، لقيد Page size cannot exceed 10,000 rows ويتم رفضها إذا تجاوزت هذا الحدّ، مع ظهور الخطأ: INVALID_PAGE_SIZE.

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

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

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

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

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

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

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

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

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

نظرًا للتكلفة والتعقيدات، تخضع طرق خدمة "التخطيط" المُدرجة أدناه لحدود منفصلة عن أنواع الطلبات الأخرى.

• يقتصر على طلب واحد (1) في الثانية لكل رقم تعريفي للعميل أو رمز مميز للمطوِّر:

  • KeywordPlanService.GetKeywordPlan
  • KeywordPlanService.GenerateHistoricalMetrics
  • KeywordPlanService.GenerateForecastMetrics

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

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

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

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

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

• تقتصر على 2,000 إحالة ناجحة من خلال الاتصال أو النقر لكل طلب:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

• يقتصر ذلك على 2,000 تعديل للإحالة الناجحة لكل طلب:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

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

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

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