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

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

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

حد استفاده روزانه از API براساس تعداد عملیات API انجام‌شده توسط پروژه Google Cloud شما است. عملیات میانای برنامه‌سازی کاربردی مجموع کل درخواست‌های Search و SearchStream، عملیات‌های جهش فردی، و دیگر درخواست‌های خدمات است. حدود عملیات روزانه میانای برنامه‌سازی کاربردی به سطح دسترسی میانای برنامه‌سازی کاربردی پروژه 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.

• ۱ پُرسمان در ثانیه به‌صورت ۶۰ درخواست در ۶۰ ثانیه محاسبه می‌شود.

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

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