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

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

نوع الطلب والقيود ورمز الخطأ
الطلبات المقسّمة على صفحات	10000 صف في الصفحة	INVALID_PAGE_SIZE
العمليات مع الدخول الأساسي	15000 عملية من عمليات واجهة برمجة التطبيقات يوميًا	RESOURCE_EXHAUSTED
طلبات التبديل	10000 عملية لكل طلب	TOO_MANY_MUTATE_OPERATIONS
طلبات خدمة التخطيط	لقطة في الثانية	RESOURCE_EXHAUSTED
طلبات خدمة تحميل الإحالات الناجحة	2000 إحالة ناجحة لكل طلب	TOO_MANY_CONVERSIONS_IN_REQUEST
الفوترة وطلبات خدمة ميزانية الحساب	عملية واحدة لكل طلب تبديل	TOO_MANY_MUTATE_OPERATIONS

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

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

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

قيود gRPC

تستخدم جميع مكتبات العملاء في "إعلانات Google API" gRPC لإنشاء الطلبات والردود. بشكل تلقائي، يبلغ حجم الرسالة في gRPC 4 ميغابايت، إلا أن مكتبات العملاء عيّنت الحد الأقصى لحجم الرسالة إلى 64 ميغابايت لزيادة الكفاءة.

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

ولن تؤدي الطلبات التي تنتهك هذا القيد إلى ظهور GoogleAdsError، ولكنها ستحدث 429 Resource Exhausted خطأ gRPC. ارجع إلى قائمة رموز خطأ gRPC ورسائله.

طلبات التبديل

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

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

خدمات تخطيط

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

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

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

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

• يتم احتساب قيمة QPS واحدة من خلال 60 طلبًا لكل 60 ثانية.

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

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

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

• يقتصر على 2000 تحويل للمكالمات أو النقرات لكل طلب:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

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

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

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

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

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

• يُسمح بإجراء 1 فقط لطلبات التبديل.

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