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

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

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

تستند حدود الاستخدام اليومي لواجهة برمجة التطبيقات إلى عدد واجهة برمجة التطبيقات العمليات التي تمت لكل رمز مميز للمطوِّر. API والعمليات هي المجموع الإجمالي لطلبات الحصول وعمليات التغيير. الحدود لعمليات واجهة برمجة التطبيقات اليومية على مستوى الوصول إلى الرمز المميز للمطوِّر. تشير رسالة الأشكال البيانية يلخّص دليل مستويات الوصول والاستخدام المسموح به محددة لعملية واجهة برمجة التطبيقات لكل مستوى وصول.

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

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupTheme

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

عنصر خطة الكلمة الرئيسية	الحد الأقصى للعدد
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 هو 20000. في حال تجاوز هذا الحدّ، FILTER_HAS_TOO_MANY_VALUES .