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

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

סוג הבקשה, המגבלה וקוד השגיאה
פעולות עם גישה בסיסית	15,000 פעולות API ביום	RESOURCE_EXHAUSTED
בקשות לשינוי	10,000 פעולות לבקשה	TOO_MANY_MUTATE_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. כדי למנוע את המגבלה הזו, אפשר לצמצם את מספר השדות שנבחרו או להשתמש בסטרימינג. לגבי פעולות שינוי (mutate), כדאי לשלוח פחות פעולות לכל בקשה.

בקשות שמפירות את המגבלה הזו לא ייצרו 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, למשל בגלל שגיאה ברמת הרשת, לא נספרות במכסת הפעולות היומית של המשתמש כי הן אף פעם לא מגיעות לשירות. דוגמה לכך היא כשל בחיבור לרשת.

שירותי תכנון

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

• מוגבלת לבקשה אחת לשנייה לכל מזהה לקוח:

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupTheme

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

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

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

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

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

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

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

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

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

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

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

• מותר להגדיר רק פעולה 1 לבקשות שינוי.

  בקשות שמפירות את המגבלה הזו יידחו עם השגיאה: 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, כל קבוצה של user_identifiers צריכה להיות ספציפית למשתמש יחיד.

כדי לאכוף את הכלל הזה, המערכת מחזירה את השגיאה OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS או UserDataError.TOO_MANY_USER_IDENTIFIERS אם יש יותר מ-20 user_identifiers בקבוצת UserData.

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

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

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

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