رابط برنامه‌نویسی کاربردی گوگل ادز محدودیت‌هایی را بر عملیات API اعمال می‌کند، مانند تعداد عملیاتی که می‌توانند در یک درخواست جهش واحد ارسال شوند. جدول زیر برخی از محدودیت‌ها و سهمیه‌های مهم را که باید از آنها آگاه باشید، خلاصه می‌کند.
| نوع درخواست، محدودیت و کد خطا | ||
|---|---|---|
| عملیات با سطح دسترسی Explorer | ۲۸۸۰ عملیات API در روز علیه حساب‌های کاربری تولیدی ۱۵۰۰۰ عملیات API در روز روی حساب‌های آزمایشی | RESOURCE_EXHAUSTED |
| عملیات با سطح دسترسی پایه | ۱۵۰۰۰ عملیات API در روز بر روی حساب‌های آزمایشی و عملیاتی | RESOURCE_EXHAUSTED |
| درخواست‌های تغییر شکل | ۱۰،۰۰۰ عملیات در هر درخواست | TOO_MANY_MUTATE_OPERATIONS |
| درخواست‌های خدمات برنامه‌ریزی | ۱ کوارتر در ثانیه | RESOURCE_EXHAUSTED |
| درخواست‌های سرویس آپلود تبدیل | ۲۰۰۰ تبدیل به ازای هر درخواست | TOO_MANY_CONVERSIONS_IN_REQUEST |
| درخواست‌های خدمات بودجه‌بندی صورتحساب و حساب | ۱ عملیات به ازای هر درخواست جهش | TOO_MANY_MUTATE_OPERATIONS |
محدودیت‌های روزانه عملیات API
محدودیت‌های استفاده روزانه از API بر اساس تعداد عملیات API انجام شده به ازای هر توکن توسعه‌دهنده تعیین می‌شود. عملیات API مجموع کل درخواست‌های دریافت و عملیات تغییر است. محدودیت‌های عملیات روزانه API به سطح دسترسی توکن توسعه‌دهنده بستگی دارد. راهنمای سطوح دسترسی و استفاده مجاز، محدودیت‌های خاص عملیات API را برای هر سطح دسترسی مشخص می‌کند.
درخواست‌هایی که این محدودیت‌ها را نقض کنند با خطای RESOURCE_EXHAUSTED رد می‌شوند.
محدودیت‌های gRPC
تمام کتابخانه‌های کلاینت API گوگل ادز از gRPC برای تولید درخواست‌ها و پاسخ‌ها استفاده می‌کنند. به طور پیش‌فرض، gRPC اندازه پیام ۴ مگابایت دارد، اما کتابخانه‌های کلاینت ما برای افزایش کارایی، حداکثر اندازه پیام را روی ۶۴ مگابایت تنظیم کرده‌اند.
پاسخ‌ها نباید از این حد تجاوز کنند. برای مثال، یک درخواست جستجو که شامل فیلدهای زیادی است، ممکن است پاسخی با حجم بیش از ۶۴ مگابایت ایجاد کند. برای جلوگیری از این محدودیت، می‌توانید تعداد فیلدهای انتخاب شده را کاهش دهید یا از جریان‌سازی استفاده کنید. برای جهش‌ها، عملیات کمتری را در هر درخواست ارسال کنید.
درخواست‌هایی که این محدودیت را نقض کنند، خطای GoogleAdsError ایجاد نمی‌کنند ، اما خطای 429 Resource Exhausted gRPC را ایجاد می‌کنند. به لیست کدهای خطا و پیام‌های gRPC مراجعه کنید.
درخواست‌های تغییر شکل
علاوه بر محاسبه در سهمیه عملیات روزانه کاربر، یک درخواست جهش نمی‌تواند شامل بیش از ۱۰،۰۰۰ عملیات در هر درخواست باشد.
درخواست‌هایی که این محدودیت را نقض کنند با خطای TOO_MANY_MUTATE_OPERATIONS رد می‌شوند.
محدودیت‌ها و ملاحظات اضافی برای خدمات خاص و انواع درخواست‌ها در ادامه شرح داده شده است.
درخواست‌های جستجو
یک درخواست Search یا SearchStream به عنوان یک عملیات در سهمیه عملیات روزانه کاربر محاسبه می‌شود. یک درخواست SearchStream صرف نظر از تعداد دسته‌ها، به عنوان یک عملیات API محاسبه می‌شود.
درخواست‌های صفحه‌بندی‌شده
درخواست‌های صفحه‌بندی‌شده (برای مثال، درخواست‌هایی که حاوی یک next_page_token معتبر هستند) جزو سهمیه عملیات روزانه کاربر محسوب نمی‌شوند. با این حال، درخواست‌های صفحه‌بندی که حاوی یک page token منقضی شده یا نامعتبر هستند، یک استثنا ایجاد می‌کنند و جزو سهمیه عملیات روزانه محسوب می‌شوند.
برای جزئیات بیشتر در مورد صفحه‌بندی، به «صفحه‌بندی از طریق نتایج» مراجعه کنید.
انواع دیگر درخواست‌ها
درخواستی که از نوع Get ، Mutate ، Search یا SearchStream نباشد، به عنوان یک عملیات در سهمیه عملیات روزانه کاربر محاسبه می‌شود.
چند نمونه از این درخواست‌ها عبارتند از:
-
BatchJobService.ListMutateJobResults -
ConversionUploadService.UploadCallConversions -
ConversionUploadService.UploadClickConversions -
OfflineUserDataJobService.AddOfflineUserDataJobOperations -
OfflineUserDataJobService.CreateOfflineUserDataJob -
UserDataService.UploadUserData
درخواست‌هایی که استثنائات API را برمی‌گردانند
درخواست‌هایی که با خطای GoogleAdsFailure رد می‌شوند، همچنان جزو سهمیه کارکرد روزانه کاربر محسوب می‌شوند.
درخواست‌هایی که با شکست مواجه می‌شوند اما GoogleAdsFailure برنمی‌گردانند، مانند درخواست‌های ناشی از خطا در سطح شبکه، جزو سهمیه عملیات روزانه کاربر محسوب نمی‌شوند، زیرا درخواست‌ها هرگز به سرویس نمی‌رسند. نمونه‌ای از این مورد، خرابی اتصال شبکه است.
خدمات برنامه‌ریزی کلمات کلیدی
با توجه به هزینه و پیچیدگی، روش‌های خدمات برنامه‌ریزی کلمات کلیدی زیر مشمول محدودیت‌های جداگانه‌ای نسبت به سایر انواع درخواست‌ها هستند.
محدود به ۱ درخواست در ثانیه برای هر CID:
-
KeywordPlanIdeaService.GenerateKeywordIdeas -
KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics -
KeywordPlanIdeaService.GenerateKeywordForecastMetrics
درخواست‌هایی که این محدودیت‌ها را نقض کنند با خطای
RESOURCE_EXHAUSTEDرد می‌شوند.-
۱ QPS به صورت ۶۰ درخواست در هر ۶۰ ثانیه محاسبه می‌شود.
محدود به ۲ درخواست در ثانیه برای هر CID:
هنگام ایجاد یک برنامه کلمات کلیدی، این محدودیت‌ها را در نظر داشته باشید.
| شیء طرح کلمه کلیدی | حداکثر تعداد |
|---|---|
KeywordPlan برای هر حساب کاربری | ۱۰۰۰۰ |
KeywordPlanAdGroup به ازای KeywordPlan | ۲۰۰ |
KeywordPlanAdGroupKeyword به ازای هر KeywordPlan | ۱۰۰۰۰ |
KeywordPlanCampaignKeyword (کلمات کلیدی منفی) | ۱۰۰۰ |
KeywordPlanCampaign برای KeywordPlan | ۱ |
سرویس بینش مخاطبان
متدهای زیر در متدهای AudienceInsightsService مشمول محدودیت‌های سهمیه‌بندی خاصی هستند.
محدود به تقریباً ۲۰۰ درخواست در روز برای هر CID:
محدود به ۲ درخواست در ثانیه برای هر توکن توسعه‌دهنده:
سرویس آپلود تبدیل
محدود به ۲۰۰۰ تبدیل تماس یا کلیک به ازای هر درخواست:
درخواست‌هایی که این محدودیت‌ها را نقض کنند با خطای
TOO_MANY_CONVERSIONS_IN_REQUESTرد می‌شوند.
سرویس آپلود تنظیم تبدیل
محدود به ۲۰۰۰ تنظیم تبدیل در هر درخواست:
درخواست‌هایی که این محدودیت‌ها را نقض کنند با خطای
TOO_MANY_ADJUSTMENTS_IN_REQUESTرد می‌شوند.
خدمات صورتحساب و بودجه‌بندی حساب
تغییرات فقط می‌توانند روی حساب‌هایی که برای صدور صورتحساب ماهانه پیکربندی شده‌اند، اعمال شوند.
درخواست‌هایی که این محدودیت را نقض کنند با خطای
MUTATE_NOT_ALLOWEDرد می‌شوند.فقط 1 عملیات برای درخواست‌های جهش مجاز است.
درخواست‌هایی که این محدودیت را نقض کنند با خطای
TOO_MANY_MUTATE_OPERATIONSرد می‌شوند.شما باید حداقل ۱۲ ساعت بین تغییرات سفارش بودجه در همان حساب کاربری صبر کنید. ایجاد تغییرات قبل از گذشت ۱۲ ساعت ممکن است منجر به خرابی‌های غیرقابل جبرانی شود که فقط توسط نماینده حساب Google Ads شما قابل حل است.
دعوتنامه برای حساب‌های کاربری مشتریان
کاربران جدید را می‌توان با استفاده از CustomerUserAccessService به حساب‌های کاربری موجود دعوت کرد. از آنجا که این ویژگی ایمیل‌های دعوت را برای سایر کاربران ارسال می‌کند، احتمال سوءاستفاده از آن وجود دارد و بنابراین محدودیت‌هایی در رفتار آن وجود دارد:
کاربران نمی‌توانند بیش از یک دعوتنامه در حال انتظار برای یک حساب کاربری دریافت کنند. اگر درخواست بعدی برای ارسال دعوتنامه به کاربری که از قبل دعوتنامه در حال انتظار دارد، ارسال شود، این خطا بازگردانده می‌شود:
ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.حساب‌های کاربری نمی‌توانند بیش از ۷۰ دعوت‌نامه‌ی در انتظار دریافت داشته باشند. اگر درخواستی ارسال شود که باعث شود تعداد دعوت‌نامه‌ها از این مقدار بیشتر شود، این خطا برگردانده می‌شود:
ACCESS_INVITATION_ERROR_PENDING_INVITATIONS_LIMIT_EXCEEDED.
داده‌های کاربر
داده‌های کاربر با UserDataService و OfflineUserDataJobService مدیریت می‌شوند. در یک عملیات ایجاد یا حذف UserData ، هر مجموعه از user_identifiers باید مختص یک کاربر واحد باشد.
برای اجرای این امر، هنگامی که بیش از 20 user_identifiers در یک مجموعه UserData وجود داشته باشد، خطای OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS یا UserDataError.TOO_MANY_USER_IDENTIFIERS بازگردانده می‌شود.
صرف نظر از تعداد عملیات، شما مجاز به استفاده از حداکثر ۱۰۰۰۰۰ شناسه کاربری هستید.
انواع دیگر محدودیت‌ها
یک فیلد تکراری، مانند لیستی از عملیات، که موارد زیادی در یک درخواست دارد، می‌تواند منجر به خطای REQUEST_SIZE_LIMIT_EXCEEDED شود. همین پیام خطا می‌تواند به دلیل مشکلات دیگری نیز باشد.
اگر با این محدودیت مواجه شدید و درخواست‌هایی ارسال می‌کنید که از یک فیلد تکراری استفاده می‌کنند، سعی کنید با استفاده از فهرستی از عملیات در یک درخواست جهشی، تعداد موارد موجود در فیلد تکراری را کاهش دهید.
هنگام ایجاد یک پرس‌وجوی GAQL ، حداکثر تعداد آیتم‌ها در یک عبارت IN 20،000 است. اگر از این حد تجاوز کنید، خطای FILTER_HAS_TOO_MANY_VALUES بازگردانده می‌شود.