מגבלות ומכסות ל-API

ב-Google Ads API יש מגבלות על פעולות API, כמו מספר הפעולות שאפשר לשלוח בבקשת שינוי אחת. בטבלה הבאה מפורטות חלק מהמגבלות והמכסות החשובות שכדאי להכיר.

סוג הבקשה, המגבלה וקוד השגיאה
פעולות עם רמת הגישה 'חוקר'	‫2,880 פעולות API ביום בחשבונות פעילים ‫15,000 פעולות API ביום בחשבונות בדיקה	RESOURCE_EXHAUSTED
פעולות ברמת גישה בסיסית	‫15,000 פעולות API ביום בחשבונות בדיקה ובחשבונות פעילים	RESOURCE_EXHAUSTED
בקשות לשינוי	‫10,000 פעולות שינוי לכל בקשה 100 פעולות מסוג action לכל בקשה	TOO_MANY_MUTATE_OPERATIONS TOO_MANY_ACTION_OPERATIONS
בקשות לשירותי תכנון	‫1 QPS	RESOURCE_EXHAUSTED
בקשות שירות בנושא העלאת המרות	‫2,000 המרות לכל בקשה	TOO_MANY_CONVERSIONS_IN_REQUEST
בקשות שירות בנושא חיוב ותקציב חשבון	פעולה אחת לכל בקשת שינוי	TOO_MANY_MUTATE_OPERATIONS

מגבלות יומיות על פעולות API

המגבלות על השימוש ב-API מדי יום מבוססות על מספר הפעולות ב-API שבוצעו לכל קוד מפתח. פעולות API הן הסכום הכולל של בקשות get ופעולות mutate. המגבלות על פעולות API יומיות תלויות ברמת הגישה של קוד המפתח. במדריך בנושא רמות גישה ושימוש מותר מפורטות המגבלות הספציפיות על פעולות API לכל רמת גישה.

בקשות שמפרות את המגבלות האלה נדחות עם השגיאה: RESOURCE_EXHAUSTED.

מגבלות של gRPC

כל ספריות הלקוח של Google Ads API משתמשות ב-gRPC כדי ליצור בקשות ותגובות. כברירת מחדל, גודל ההודעה ב-gRPC הוא 4MB, אבל בספריות הלקוח שלנו הגדרנו את הגודל המקסימלי של ההודעה ל-64MB כדי לשפר את היעילות.

התשובות לא יכולות לחרוג מהמגבלה הזו. לדוגמה, בקשת חיפוש שכוללת הרבה שדות עשויה ליצור תגובה שגודלה גדול מ-64MB. כדי לא לחרוג מהמגבלה הזו, אפשר לצמצם את מספר השדות שנבחרו או להשתמש בסטרימינג. במקרה של שינויים, כדאי לשלוח פחות פעולות בכל בקשה.

בקשות שמפירות את המגבלה הזו לא ייצרו GoogleAdsError, אלא ייצרו שגיאת gRPC‏ 429 Resource Exhausted. אפשר לעיין ברשימת קודי השגיאה וההודעות של gRPC.

בקשות לשינוי

בנוסף למכסת הפעולות היומית של המשתמש, בקשת מוטציה לא יכולה להכיל יותר מ-10,000 פעולות לכל בקשה.

בקשות שמפירות את ההגבלה הזו נדחות עם השגיאה: TOO_MANY_MUTATE_OPERATIONS.

בהמשך מפורטות מגבלות נוספות ושיקולים נוספים לגבי שירותים ספציפיים וסוגים ספציפיים של בקשות.

בקשות חיפוש

בקשת Search או SearchStream נספרת כפעולה אחת במכסת הפעולות היומית של המשתמש. בקשה אחת של SearchStream נספרת כפעולת API אחת, ללא קשר למספר האצוות.

בקשות עם מספור עמודים

בקשות עם חלוקה לדפים (לדוגמה, בקשות שמכילות next_page_token תקין) לא נספרות במכסת הפעולות היומית של המשתמש. עם זאת, בקשות חלוקה לדפים שמכילות טוקן דף לא חוקי או שפג תוקפו יגרמו לחריג וייכללו במכסת הפעולות היומית.

פרטים נוספים על חלוקה לדפים זמינים במאמר בנושא חלוקת תוצאות לדפים.

סוגים אחרים של בקשות

בקשה שלא משויכת ל-Get, ל-Mutate, ל-Search או ל-SearchStream נספרת כפעולה אחת במסגרת מכסת הפעולות היומית של המשתמש.

דוגמאות לבקשות כאלה:

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

בקשות שמחזירות חריגות ב-API

בקשות שנדחות עם GoogleAdsFailure עדיין נספרות במכסת הפעולות היומית של המשתמש.

בקשות שנכשלות אבל לא מחזירות GoogleAdsFailure, כמו בקשות שנובעות משגיאה ברמת הרשת, לא ייספרו במסגרת מכסת הפעולות היומית של המשתמש, כי הבקשות לא יגיעו לשירות. דוגמה לכך היא כשל בקישוריות לרשת.

שירות לתכנון מילות מפתח

בגלל העלות והמורכבות, המגבלות על השיטות הבאות של שירות תכנון מילות מפתח שונות מהמגבלות על סוגים אחרים של בקשות.

• מוגבל ל-1 בקשות לשנייה לכל מספר לקוח:

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

  בקשות שמפירות את המגבלות האלה נדחות עם השגיאה: RESOURCE_EXHAUSTED.

• שאילתה אחת לשנייה (QPS) מחושבת כ-60 בקשות ל-60 שניות.

• מוגבל ל-2 בקשות לשנייה לכל CID:

  • KeywordPlanIdeaService.GenerateAdGroupTheme

חשוב לזכור את המגבלות האלה כשיוצרים תוכנית למילות מפתח.

אובייקט של תוכנית למילות מפתח	מספר מקסימלי
‫KeywordPlan לכל חשבון	10,000
‫KeywordPlanAdGroup לכל KeywordPlan	200
‫KeywordPlanAdGroupKeyword לכל KeywordPlan	10,000
‫KeywordPlanCampaignKeyword (מילות מפתח שליליות)	1,000
‫KeywordPlanCampaign לכל KeywordPlan	1

שירות מדדי הקהלים

השיטות הבאות ב-AudienceInsightsService כפופות למגבלות מכסה ספציפיות.

• מוגבל לכ-200 בקשות ביום לכל מספר לקוח:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• מוגבל ל-2 בקשות לשנייה לכל קוד מפתח:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

שירות העלאת המרות

• מוגבל ל-2,000 המרות מסוג שיחה או קליק לכל בקשה:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  בקשות שמפרות את המגבלות האלה נדחות עם השגיאה: TOO_MANY_CONVERSIONS_IN_REQUEST.

שירות להעלאת שינויי ערך המרה

• מוגבל ל-2,000 שינויים של ערכי המרות לכל בקשה:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  בקשות שמפרות את המגבלות האלה נדחות עם השגיאה: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

כללים לקביעת ערכי המרות

• מוגבל ל-100,000 כללים לקביעת ערכי המרות לכל חשבון.

  בקשות שחורגות מהמגבלה הזו נדחות עם השגיאה ResourceCountLimitExceededError.ACCOUNT_LIMIT.

הערה: כללים לקביעת ערך המרה שנוצרו באמצעות Google Ads API פעילים רק אם הם חלק מקבוצת כללים לקביעת ערך המרה שכוללת את שמות המשאבים ConversionValueRule בשדה conversion_value_rules, והסטטוס ConversionValueRuleSet שלהם מוגדר לערך ENABLED. כללים לקביעת ערכי המרות שלא נכללים בקבוצה של כללים לקביעת ערכי המרות לא מוצגים בממשק המשתמש של Google Ads, ואפשר לנהל אותם רק באמצעות ה-API.

אם כבר קיים בחשבון ConversionValueRuleSet עם attachment_type של CUSTOMER, כדי שכללים חדשים לקביעת ערך המרה יופעלו, צריך להוסיף אותם לקבוצה הזו. אם לא קיים כלל כזה לקביעת ערך המרה, צריך ליצור אותו ולהוסיף אליו את הכללים לקביעת ערך המרה, כמו שמתואר במאמר בנושא יצירת קבוצות של כללים.

שירותים שקשורים לחיוב ולתקציב החשבון

• אפשר לבצע שינויים רק בחשבונות שמוגדר בהם חיוב חודשי.

  בקשות שמפירות את ההגבלה הזו נדחות עם השגיאה: MUTATE_NOT_ALLOWED.

• מותר לבצע רק פעולה אחת בבקשות שינוי.

  בקשות שמפירות את ההגבלה הזו נדחות עם השגיאה: 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 בפעולת create או remove מתייחס למשתמש קצה יחיד. השדה user_identifiers באובייקט UserData יחיד מוגבל ל-20 מזהים לכל היותר. חריגה מהמגבלה הזו באובייקט UserData יחיד תגרום לשגיאה OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS או UserDataError.TOO_MANY_USER_IDENTIFIERS.

טיפול במשתמשים עם יותר מ-20 מזהים

אם למשתמש קצה יחיד יש יותר מ-20 מזהים שצריך להעלות, צריך לפצל את המזהים האלה בין כמה אובייקטים של UserData. כדי לוודא ש-Google תוכל לשייך את כל המזהים האלה לאותו משתמש קצה, כל אובייקט UserData של המשתמש צריך לכלול לפחות user_identifier משותף, כמו אותו hashed_email, hashed_phone_number או third_party_user_id. ‫Google משתמשת במזהים המשותפים האלה כדי לקשר ולמזג את המידע מפעולות UserData נפרדות עם הפרופיל הנכון של משתמש הקצה.

אם אתם מסתמכים על PII כמו כתובות אימייל או מספרי טלפון מגובבים, חשוב לוודא שהם מנורמלים ומגובבים בהתאם לדרישות של Google Ads API (SHA-256, אותיות קטנות, ללא רווחים לבנים) כדי למנוע כשלים בקישור.

לדוגמה, אם למשתמש יש 30 כתובות אימייל, אפשר לשלוח שני אובייקטים של UserData.

• UserData 1: {third_party_user_id: "user123", hashed_email: "email1@...", ... hashed_email: "email19@..."}
• UserData 2: {third_party_user_id: "user123", hashed_email: "email20@...", ‪... hashed_email: "email30@..."}

המגבלה הכוללת של user_identifiers בכל הפעולות ב-OfflineUserDataJob נשארת 100,000.

סוגים אחרים של מגבלות

שדה חוזר, כמו רשימת פעולות, שמכיל יותר מדי פריטים בבקשה, עלול לגרום לשגיאה: REQUEST_SIZE_LIMIT_EXCEEDED. יכול להיות שיופיעו הודעות שגיאה אחרות.

אם נתקלתם במגבלה הזו ואתם שולחים בקשות שמשתמשות בשדה חוזר, נסו לצמצם את מספר הפריטים בשדה החוזר על ידי פריסת רשימה של פעולות בבקשת שינוי.

כשמבצעים שאילתת GAQL, המספר המקסימלי של פריטים בתוך פסקה IN הוא 20,000. אם חורגים מהמגבלה הזו, מוחזרת שגיאה FILTER_HAS_TOO_MANY_VALUES.