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

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

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

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

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

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

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

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

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

درخواست‌های تغییر شکل

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خدمات برنامه‌ریزی کلمات کلیدی

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

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

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

سرویس بینش مخاطبان

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

• محدود به تقریباً ۲۰۰ درخواست در روز برای هر CID:
  • 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 رد می‌شوند.

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

  درخواست‌هایی که این محدودیت را نقض کنند با خطای 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 حداکثر به 20 شناسه محدود می‌شود. تجاوز از این محدودیت در یک شیء UserData منجر به خطای OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS یا UserDataError.TOO_MANY_USER_IDENTIFIERS خواهد شد.

مدیریت کاربران با بیش از 20 شناسه

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

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

برای مثال، اگر کاربری 30 آدرس ایمیل داشته باشد، می‌توانید دو شیء UserData که یک third_party_user_id مشترک دارند را ارسال کنید (برای اینکه در محدوده 20 شناسه باقی بماند، thirdPartyUserId به همراه ایمیل‌های 1 تا 19 را در شیء اول قرار دهید و thirdPartyUserId به همراه ایمیل‌های 20 تا 30 را در شیء دوم قرار دهید):

{
  "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 شود. همین پیام خطا می‌تواند به دلیل مشکلات دیگری نیز باشد.

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

هنگام ایجاد یک پرس‌وجوی GAQL ، حداکثر تعداد آیتم‌ها در یک عبارت IN 20،000 است. اگر از این حد تجاوز کنید، خطای FILTER_HAS_TOO_MANY_VALUES بازگردانده می‌شود.