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

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

حدود عملیات میانای برنامه‌سازی کاربردی روزانه

حدود استفاده روزانه از API براساس تعداد عملیات API انجام‌شده توسط پروژه Google Cloud شما است. عملیات میانای برنامه‌سازی کاربردی مجموع کل درخواست‌های Search و SearchStream، عملیات‌های تغییردهنده جداگانه، و دیگر درخواست‌های سرویس است. محدودیت‌های عملیات روزانه API به سطح دسترسی API پروژه Google Cloud شما بستگی دارد. راهنمای سطوح دسترسی و استفاده مجاز حدود عملیات خاص میانای برنامه‌سازی کاربردی را برای هر سطح دسترسی مشخص می‌کند.

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

محدودیت‌های gRPC

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

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

درخواست‌هایی که این محدودیت را نقض کنند، GoogleAdsError تولید نمی‌کنند، اما خطای RESOURCE_EXHAUSTED (کد gRPC 8 / HTTP 429) تولید می‌کنند. به فهرست کدها و پیام‌های خطای gRPC مراجعه کنید.

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

علاوه‌بر اینکه درخواست تغییر در سهمیه عملیات روزانه کاربر لحاظ می‌شود، نمی‌تواند حاوی بیش‌از ۱۰٬۰۰۰ عملیات تغییر در هر درخواست باشد. درخواست‌هایی که این محدودیت را نقض کنند با خطای: TOO_MANY_MUTATE_OPERATIONS رد می‌شوند.

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

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

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

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

درخواست‌های صفحه‌بندی‌شده (برای مثال، درخواست‌هایی که حاوی next_page_token معتبر هستند) در سهمیه عملیات روزانه کاربر محاسبه نمی‌شوند. بااین‌حال، درخواست‌های صفحه‌بندی که حاوی کد صفحه منقضی‌شده یا نامعتبر باشند، استثنا ایجاد می‌کنند و در سهمیه عملیات روزانه لحاظ می‌شوند.

برای جزئیات بیشتر درباره صفحه‌بندی، به صفحه‌بندی نتایج مراجعه کنید.

انواع دیگر درخواست‌ها

درخواستی که درخواست Mutate، Search، یا SearchStream نباشد به‌عنوان یک عملیات دربرابر سهمیه عملیات روزانه کاربر محاسبه می‌شود.

چند نمونه از این درخواست‌ها عبارت‌اند از:

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

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

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

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

سرویس برنامه‌ریزی کلیدواژه

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

• محدود به ۱ درخواست در ثانیه برای هر شناسه مشتری:

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

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

• ‫۱ QPS به‌عنوان ۶۰ درخواست در ۶۰ ثانیه محاسبه می‌شود.

• محدود به ۲ درخواست در ثانیه برای هر شناسه مشتری:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

سرویس اطلاعات آماری مخاطب

روش‌های زیر در AudienceInsightsService مشمول محدودیت‌های سهمیه خاصی هستند.

• محدود به تقریباً ۲۰۰ درخواست در روز برای هر شناسه مشتری:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• محدود به ۲ درخواست در ثانیه برای هر پروژه Google Cloud:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

سرویس بارگذاری تبدیل

• محدود به ۲٬۰۰۰ تبدیل ازطریق تماس یا کلیک در هر درخواست:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

سرویس بارگذاری تعدیل تبدیل

• محدود به ۲٬۰۰۰ اصلاح تبدیل در هر درخواست:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

قوانین مقدار تبدیل‌به‌مشتری

• محدود به ۱۰۰٬۰۰۰ قانون مقدار تبدیل‌به‌مشتری برای هر حساب.

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

اگر ConversionValueRuleSet با attachment_type CUSTOMER ازقبل برای حساب وجود داشته باشد، باید هرگونه قانون مقدار تبدیل جدید را به آن مجموعه اضافه کنید تا فعال شوند. اگر چنین مجموعه قانون مقدار تبدیلی وجود ندارد، باید یکی ایجاد کنید و قوانین مقدار تبدیل خود را به آن اضافه کنید، همان‌طور که در ایجاد مجموعه‌های قانون توضیح داده شده است.

خدمات بودجه حساب و صدور صورت‌حساب

• تغییرات فقط برای حساب‌هایی که برای صورت‌حساب ماهانه پیکربندی شده‌اند قابل انجام است.

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

• فقط ۱ عملیات برای درخواست‌های تغییر مجاز است.

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

• بین تغییرات بودجه حساب (AccountBudget یا AccountBudgetProposal) در یک حساب باید حداقل ۱۲ ساعت صبر کنید. ایجاد تغییرات قبل‌از گذشت ۱۲ ساعت ممکن است منجر به خطاهای غیرقابل‌بازیابی شود که فقط نماینده حساب Google Ads شما می‌تواند آن‌ها را برطرف کند.

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

کاربران جدید را می‌توان با CustomerUserAccessInvitationService به حساب‌های مشتری موجود دعوت کرد. ازآنجایی‌که این ویژگی ایمیل‌های دعوت را به کاربران دیگر ارسال می‌کند، احتمال سوءاستفاده از آن وجود دارد، و بنابراین محدودیت‌هایی برای عملکرد آن وجود دارد:

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

• حساب‌های مشتری نمی‌توانند بیش‌از ۷۰ دعوت معلقه به‌طور هم‌زمان داشته باشند. اگر درخواستی ارسال شود که باعث فراتر رفتن از این مقدار شود، این خطا برگردانده می‌شود: PENDING_INVITATIONS_LIMIT_EXCEEDED.

داده‌های کاربر

داده‌های کاربر با UserDataService و OfflineUserDataJobService مدیریت می‌شود.

هر شیء UserData در عملیات create یا remove به یک کاربر نهایی مربوط می‌شود. فیلد user_identifiers در یک شیء UserData واحد به حداکثر ۲۰ شناسه محدود می‌شود. فراتر رفتن از این حد در یک شیء UserData منجر به خطای OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS یا UserDataError.TOO_MANY_USER_IDENTIFIERS خواهد شد.

کاربران دارای بیش‌از ۲۰ شناسه را مدیریت کنید

اگر یک کاربر نهایی بیش‌از ۲۰ شناسه دارد که باید بارگذاری کنید، باید این شناسه‌ها را در چندین UserData شیء توزیع کنید. برای اینکه مطمئن شوید Google می‌تواند همه این شناسه‌ها را به یک کاربر نهایی نسبت دهد، هر UserData شیء برای آن کاربر باید حداقل یک user_identifier مشترک داشته باشد، مثلاً hashed_email، hashed_phone_number، یا third_party_user_id یکسان. ‫Google از این شناسه‌های هم‌رسانی‌شده برای پیوند دادن و ادغام کردن اطلاعات از UserData عملیات جداگانه در نمایه کاربر نهایی صحیح استفاده می‌کند.

اگر به اطلاعات شناساننده شخصی مانند ایمیل‌ها یا شماره تلفن‌های درهم‌سازی‌شده متکی هستید، مطمئن شوید که آن‌ها طبق الزامات Google Ads API (SHA-256، حروف کوچک، بدون فاصله) نرمال‌سازی و درهم‌سازی شده‌اند تا از شکست پیوند جلوگیری شود.

برای مثال، اگر کاربری ۳۰ نشانی ایمیل داشته باشد، می‌توانید دو UserData شیء ارسال کنید که third_party_user_id مشترک دارند (با قرار دادن thirdPartyUserId به‌علاوه ایمیل‌های ۱ تا ۱۹ در شیء اول برای ماندن در محدوده ۲۰ شناسه، و thirdPartyUserId به‌علاوه ایمیل‌های ۲۰ تا ۳۰ در شیء دوم):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

محدودیت کلی برای user_identifiers در همه عملیات‌ها در یک AddOfflineUserDataJobOperationsRequest ۱۰۰٬۰۰۰ است (یک OfflineUserDataJob می‌تواند چندین AddOfflineUserDataJobOperationsRequest تماس را بپذیرد، تا حداکثر توصیه شده ۱٬۰۰۰٬۰۰۰ عملیات در هر کار). برای بارگذاری‌های هم‌زمان بااستفاده از UploadUserDataRequest (UserDataService.UploadUserData)، هر درخواست به حداکثر ۱۰ عملیات و ۱۰۰ user_identifiers در کل درخواست محدود می‌شود.

انواع دیگر محدودیت‌ها

فیلد تکراری، مثل فهرست عملیات، که موارد زیادی در درخواست دارد می‌تواند باعث بروز این خطا شود: REQUEST_SIZE_LIMIT_EXCEEDED. این پیام خطا ممکن است به‌دلیل مشکلات دیگری نیز باشد.

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

هنگام ایجاد پُرسمان GAQL، حداکثر تعداد موارد در بند IN،‏ ۲۰٬۰۰۰ است. اگر از این حد فراتر بروید، خطای FILTER_HAS_TOO_MANY_VALUES برگردانده می‌شود.