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

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

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

מגבלות השימוש היומיות ב-API מבוססות על מספר הפעולות ב-API שבוצעו בפרויקט בענן שלכם ב-Google Cloud. פעולות API הן הסכום הכולל של בקשות Search ו-SearchStream, פעולות שינוי נפרדות ובקשות שירות אחרות. המגבלות על פעולות יומיות ב-API תלויות ברמת הגישה ל-API של הפרויקט בענן ב-Google Cloud. במדריך לרמות גישה ולשימוש מותר מפורטות מגבלות הפעולה הספציפיות של ה-API לכל רמת גישה.

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

מגבלות של gRPC

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

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

בקשות שמפרות את המגבלה הזו לא יגרמו לשגיאה מסוג GoogleAdsError, אלא לשגיאה מסוג RESOURCE_EXHAUSTED (קוד gRPC‏ 8 / HTTP‏ 429). רשימת קודי השגיאה וההודעות של gRPC

בקשות לשינוי נתונים

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

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

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

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

הכלי לתכנון מילות מפתח

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

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

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

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

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

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

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

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

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

• מוגבל לכ-200 בקשות ביום לכל CID:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• מוגבל ל-2 בקשות לשנייה לכל פרויקט ב-Google Cloud:
  • 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.

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

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

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

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

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

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

• צריך להמתין לפחות 12 שעות בין שינויים בתקציב החשבון (AccountBudget או AccountBudgetProposal) באותו חשבון. אם תבצעו שינויים לפני שיעברו 12 שעות, עלולות להתרחש תקלות שלא ניתן לשחזר, ורק איש הקשר האחראי לחשבון Google Ads יוכל לפתור אותן.

הזמנות לחשבונות של לקוחות

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

• משתמשים לא יכולים לקבל יותר מהזמנה אחת בהמתנה לאותו חשבון לקוח. אם נשלחת בקשה נוספת לשלוח הזמנה למשתמש שכבר יש לו הזמנה בהמתנה, תוחזר השגיאה הבאה: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• בחשבונות לקוח יכולות להיות עד 70 הזמנות בהמתנה בו-זמנית. אם נשלחת בקשה שחורגת מהערך הזה, מוחזרת השגיאה הבאה: 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 שחולקים third_party_user_id משותף (כך ש-thirdPartyUserId וכתובות האימייל 1 עד 19 יהיו באובייקט הראשון כדי לא לחרוג מהמגבלה של 20 מזהים, ו-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 יחיד היא 100,000 (OfflineUserDataJob יכול לקבל כמה קריאות ל-AddOfflineUserDataJobOperationsRequest, עד למקסימום המומלץ של 1,000,000 פעולות לכל משימה). בהעלאות סינכרוניות באמצעות UploadUserDataRequest (UserDataService.UploadUserData), כל בקשה מוגבלת ל-10 פעולות לכל היותר ול-100 user_identifiers בכל הבקשה.

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

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

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

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