محدودیت ها و سهمیه های API

Google Ads API محدودیت‌هایی را بر روی عملیات API اعمال می‌کند، مانند تعداد عملیات‌هایی که می‌توانند در یک درخواست جهش ارسال شوند. جدول زیر برخی از محدودیت ها و سهمیه های مهمی را که باید از آنها آگاه بود خلاصه می کند.

هشدار: روش‌های دریافت دیگر پشتیبانی نمی‌شوند. به جای آن از searchStream یا search برای بازیابی اشیا استفاده کنید.

نوع درخواست، محدودیت و کد خطا
درخواست های صفحه بندی شده	10000 ردیف در هر صفحه	INVALID_PAGE_SIZE
عملیات با دسترسی پایه	15000 عملیات API در روز	RESOURCE_EXHAUSTED
تغییر درخواست ها	10000 عملیات در هر درخواست	TOO_MANY_MUTATE_OPERATIONS
درخواست های خدمات برنامه ریزی	1 QPS	RESOURCE_EXHAUSTED
درخواست های سرویس آپلود تبدیل	2000 تبدیل در هر درخواست	TOO_MANY_CONVERSIONS_IN_REQUEST
صدور صورت‌حساب و درخواست‌های خدمات بودجه حساب	1 عملیات در هر درخواست جهش	TOO_MANY_MUTATE_OPERATIONS

محدودیت های عملیاتی روزانه API

محدودیت های استفاده روزانه API بر اساس تعداد عملیات API انجام شده در هر توکن توسعه دهنده است. عملیات API مجموع کل درخواست‌های دریافت و عملیات جهش است. محدودیت‌های عملیات روزانه API به سطح دسترسی توکن توسعه‌دهنده بستگی دارد. راهنمای سطوح دسترسی و استفاده مجاز ، محدودیت‌های عملکرد API خاص برای هر سطح دسترسی را مشخص می‌کند.

درخواست‌هایی که این محدودیت‌ها را نقض می‌کنند با این خطا رد می‌شوند: RESOURCE_EXHAUSTED .

محدودیت های gRPC

همه کتابخانه‌های سرویس گیرنده Google Ads API از gRPC برای ایجاد درخواست‌ها و پاسخ‌ها استفاده می‌کنند. به طور پیش فرض، gRPC اندازه پیام 4 مگابایت دارد، اما کتابخانه های مشتری ما حداکثر اندازه پیام را به 64 مگابایت تنظیم می کنند تا کارایی را افزایش دهند.

پاسخ ها نباید از این حد تجاوز کنند. به عنوان مثال، یک درخواست جستجو که شامل فیلدهای زیادی است ممکن است پاسخی با حجم بیش از 64 مگابایت ایجاد کند. برای جلوگیری از این محدودیت، می‌توانید تعداد فیلدهای انتخابی را کاهش دهید، اندازه صفحه را کاهش دهید یا از پخش جریانی استفاده کنید. برای جهش‌ها، به ازای هر درخواست، عملیات کمتری ارسال کنید.

درخواست‌هایی که این محدودیت را نقض می‌کنند، GoogleAdsError ایجاد نمی‌کنند ، اما خطای 429 Resource Exhausted gRPC ایجاد می‌کنند. به لیست کدهای خطا و پیام های gRPC مراجعه کنید.

تغییر درخواست ها

علاوه بر شمارش در سهمیه عملیات روزانه کاربر، درخواست جهش نمی تواند بیش از 10000 عملیات در هر درخواست داشته باشد.

درخواست‌هایی که این محدودیت را نقض می‌کنند با این خطا رد می‌شوند: TOO_MANY_MUTATE_OPERATIONS .

محدودیت ها و ملاحظات اضافی برای خدمات خاص و انواع درخواست در زیر مشخص شده است.

درخواست های جستجو

درخواست Search یا SearchStream به عنوان یک عملیات در سهمیه عملیات روزانه کاربر به حساب می آید. یک درخواست SearchStream صرف نظر از تعداد دسته ها به عنوان یک عملیات API محسوب می شود.

درخواست های صفحه بندی شده

درخواست های صفحه بندی شده (به عنوان مثال، درخواست هایی که حاوی 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

درخواست هایی که استثناهای API را برمی گرداند

درخواست‌هایی که با GoogleAdsFailure رد می‌شوند همچنان جزو سهمیه عملیات روزانه کاربر محسوب می‌شوند.

درخواست‌هایی که با شکست مواجه می‌شوند اما GoogleAdsFailure را بر نمی‌گردانند، مانند یک خطا در سطح شبکه، در سهمیه عملیات روزانه کاربر حساب نمی‌شوند، زیرا درخواست‌ها هرگز به سرویس نمی‌رسند. یک مثال از این مشکل اتصال به شبکه است.

خدمات برنامه ریزی

به دلیل هزینه و پیچیدگی، روش‌های خدمات برنامه‌ریزی فهرست‌شده در زیر مشمول محدودیت‌های جداگانه‌ای از انواع دیگر درخواست‌ها هستند.

• محدود به 1 درخواست در ثانیه برای هر CID یا توکن توسعه دهنده:

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

  درخواست‌هایی که این محدودیت‌ها را نقض می‌کنند با این خطا رد می‌شوند: RESOURCE_EXHAUSTED .

• 1 QPS به صورت 60 درخواست در 60 ثانیه محاسبه می شود.

این محدودیت ها را هنگام ایجاد یک طرح کلمه کلیدی در نظر داشته باشید.

شی طرح کلمه کلیدی	حداکثر تعداد
KeywordPlan در هر حساب	10000
KeywordPlanAdGroup به ازای KeywordPlan	200
KeywordPlanAdGroupKeyword در هر KeywordPlan	10000
KeywordPlanCampaignKeyword (کلمات کلیدی منفی)	1000
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 Ads شما قابل حل است.

دعوت به حساب مشتریان

کاربران جدید را می‌توان با 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 برگردانده می شود.