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

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

نوع الطلب والحدّ ورمز الخطأ
العمليات التي تستخدم مستوى الوصول "مستكشف"	‫2,880 عملية في واجهة برمجة التطبيقات يوميًا على الحسابات الفعلية ‫15,000 عملية في واجهة برمجة التطبيقات يوميًا على الحسابات التجريبية	RESOURCE_EXHAUSTED
العمليات التي تستخدم مستوى الوصول "أساسي"	‫15,000 عملية في واجهة برمجة التطبيقات يوميًا على كلّ من الحسابات التجريبية والفعلية	RESOURCE_EXHAUSTED
طلبات التبديل	‫10,000 عملية تبديل لكل طلب ‫100 عملية إجراء لكل طلب	TOO_MANY_MUTATE_OPERATIONS TOO_MANY_ACTION_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 كعملية واحدة ضمن الحصة اليومية للعمليات المسموح بها للمستخدم.

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

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

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

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

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

خدمة تخطيط الكلمات الرئيسية

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

• يُسمح بطلب واحد في الثانية لكل رقم تعريف عميل:

  • 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

خدمة إحصاءات الجمهور

تخضع الطرق التالية ضمن AudienceInsightsService لحدود حصص محدّدة.

• يُسمح بحوالى 200 طلب في اليوم لكل رقم تعريف عميل:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• يُسمح بطلبَين في الثانية لكل رمز مميّز للمطوّر:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

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

• يُسمح بـ 2,000 إحالة ناجحة للمكالمات أو النقرات لكل طلب:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

• يُسمح بـ 2,000 تعديل للإحالات الناجحة لكل طلب:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

قواعد قيمة الإحالة الناجحة

• يُسمح بـ 100,000 قاعدة لقيمة الإحالة الناجحة لكل حساب.

  يتم رفض الطلبات التي تنتهك هذا الحدّ مع عرض الخطأ ResourceCountLimitExceededError.ACCOUNT_LIMIT.

إذا كان هناك ConversionValueRuleSet يتضمّن attachment_type بقيمة CUSTOMER للحساب، عليك إضافة أي قواعد جديدة لقيمة الإحالة الناجحة إلى هذه المجموعة لتفعيلها. إذا لم تكن هناك مجموعة قواعد قيمة الإحالة الناجحة، عليك إنشاء مجموعة وإضافة قواعد قيمة الإحالة الناجحة إليها كما هو موضّح في مقالة إنشاء مجموعات القواعد.

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

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

  يتم رفض الطلبات التي تنتهك هذا الحدّ مع عرض الخطأ: 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 في عملية create أو remove إلى مستخدم نهائي واحد. يقتصر الحقل user_identifiers ضمن كائن واحد UserData على 20 معرّفًا كحدّ أقصى. سيؤدي تجاوز هذا الحدّ في كائن UserData واحد إلى ظهور الخطأ OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS أو UserDataError.TOO_MANY_USER_IDENTIFIERS.

التعامل مع المستخدمين الذين لديهم أكثر من 20 معرّفًا

إذا كان لدى مستخدم نهائي واحد أكثر من 20 معرّفًا عليك تحميلها، عليك توزيع هذه المعرّفات على عدّة كائنات UserData. للتأكّد من أنّ بإمكان Google ربط كل هذه المعرّفات بالمستخدم النهائي نفسه، يجب أن يتضمّن كل كائن UserData لهذا المستخدم معرّف user_identifier واحدًا على الأقل، مثل hashed_email أو hashed_phone_number أو third_party_user_id نفسها. تستخدِم Google هذه المعرّفات المشترَكة لربط ودمج المعلومات من عمليات UserData المنفصلة بملف المستخدم النهائي الصحيح.

إذا كنت تعتمد على معلومات تكشف الهوية الشخصية، مثل عناوين البريد الإلكتروني أو أرقام الهواتف المجزّأة، تأكَّد من أنّها موحّدة ومجزّأة وفقًا لمتطلبات Google Ads API (SHA-256، أحرف صغيرة، بدون مسافات بيضاء) لمنع حالات تعذُّر الربط.

على سبيل المثال، إذا كان لدى المستخدم 30 عنوان بريد إلكتروني، يمكنك إرسال كائنَين من UserData.

• UserData 1: {third_party_user_id: "user123"، hashed_email: "email1@..."، ... hashed_email: "email19@..."}
• UserData 2: {third_party_user_id: "user123", hashed_email: "email20@...", ... hashed_email: "email30@..."}

يظلّ الحدّ الأقصى الإجمالي لـ user_identifiers في جميع العمليات ضمن OfflineUserDataJob واحد هو 100,000.

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

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

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

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