במאמר הזה מפורטות המכסות שחלות על Merchant API.
ב-Merchant API יש מכסות כדי להבטיח סביבה יציבה והוגנת לכל המשתמשים. המכסות מונעות ממשתמש יחיד ב-API להעמיס יותר מדי על המערכת, וכך מבטיחות ביצועים גבוהים. כדי לנהל את נתוני המוצרים ולהרחיב את הפעילות של העסק שלכם ב-Google, חשוב שתבינו את המכסות האלה.
מושגים כלליים
המכסות של Merchant API מנוהלות באמצעות קבוצות של מכסות.
השיטות של ה-API ממופות לקבוצות של מכסות. המבנה של המיפוי הזה יכול להשתנות:
- שיטה אחת לכל קבוצה: חלק מקבוצות המכסות חלות על שיטת API אחת.
לדוגמה, לשיטה של הצגת מקורות נתונים
accounts.dataSources.listיש קבוצת מכסות ייעודית משלה. - כמה שיטות בכל קבוצה (חבילה): לעיתים קרובות, שיטות קשורות מקובצות יחד לקבוצת מכסות אחת. כל השיטות בקבוצה הזו חולקות את אותן מגבלות יומיות ומגבלות לדקה. דוגמאות נפוצות:
- קיבוץ של כל פעולות הקריאה של שיטות ומשאבים קשורים, כמו
merchant-accounts-read-methods. - קיבוץ כל פעולות הכתיבה של שיטות ומשאבים קשורים, כמו
merchant-accounts-write-methods.
- קיבוץ של כל פעולות הקריאה של שיטות ומשאבים קשורים, כמו
כל הפעלת method נספרת פעם אחת, בלי קשר לסוג שלה. בקשת list אחת של 250 פריטים נספרת רק פעם אחת, ולא כ-250 בקשות get.
אצווה מובנית של HTTP לא משפיעה על המכסה. כל בקשה בודדת באצווה של בקשות נספרת כבקשה אחת במכסה. לדוגמה, בקשת Batch שמכילה 500 בקשות insert מחויבת כ-500 בקשות נפרדות של השיטה insert.
חריגה לאיסוף באצווה של אזורים ייעודיים: שיטות לאיסוף באצווה של אזורים ייעודיים (batchCreate, batchUpdate, batchDelete) נספרות כקריאה אחת ל-API במסגרת קבוצת המכסות merchant_regions, בלי קשר למספר הפעולות באזור שכלולות במטען הייעודי (payload).
כדי לנהל את השילוב בצורה יעילה, כדאי לבדוק את קבוצת המכסות הספציפית שמשויכת לכל שיטת API שבה אתם מתכוונים להשתמש. אפשר למצוא את הפרטים האלה ב-quotas list method. למידע נוסף על מעקב וניראות
עדכון של המדיניות
ה-Merchant API אוכף את כללי המדיניות הבאים בנוגע לעדכונים:
- כברירת מחדל, אפשר לעדכן את המוצרים עד פעמיים ביום. כדי לעמוד במכסה לדקה, צריך לפזר את הקריאות באופן שווה לאורך היום.
- כברירת מחדל, אפשר לעדכן את חשבונות המשנה רק עד פעמיים ביום. המכסה היומית לעדכון חשבונות משנה היא מגבלה מצטברת שמבוססת על המספר הכולל של חשבונות המשנה שמותר לכם ליצור.
- כברירת מחדל, אתם יכולים להפעיל שיטות של מקורות נתונים בחשבונות המשנה שלכם, כמו
listאוcreate, עד פעמיים ביום לכל חשבון משנה.
מכסות לקצב שליחת בקשות
לכל קבוצת מכסות יש שני סוגים של מגבלות (ושימוש יומי):
- Daily Limit (
quotaLimit): מגבלה יומית: המספר המקסימלי של בקשות שמותר לשלוח ביום. המכסות היומיות מתאפסות ב-12:00 בצהריים לפי שעון UTC. - מגבלה לדקה (
quotaMinuteLimit): המספר המקסימלי של בקשות שמותר לשלוח בדקה, ששולט בקצב הבקשות. מגבלות המכסה לדקה משתמשות בחלון זמן דינמי, שבו תקופת האכיפה מתחילה ברגע שמתבצעת הקריאה הראשונה ל-API עבור ה-method והמשאב האלה. לדוגמה, אם שולחים קריאה בשעה 10:01:30, חלון המכסה לדקה של ה-method הזו נמשך עד השעה 10:02:30. - Daily Usage (
quotaUsage): מספר הבקשות שכבר נשלחו ונכללו במגבלה היומית של היום הנוכחי. אם השדה חסר, עדיין לא נוצלה מכסה לקבוצה הזו.
שלושת השדות שתיארנו קודם (quotaLimit, quotaMinuteLimit ו-quotaUsage) נמצאים בתגובה של ה-method quotas.list.
המגבלות הספציפיות ליום ולדקה משתנות באופן משמעותי בין קבוצות המכסות השונות. לפעולות עם נפח צפוי גבוה יותר או עלות מערכת נמוכה יותר, כמו קריאת נתוני מוצרים, בדרך כלל יש מגבלות גבוהות יותר. לעומת זאת, לפעולות אינטנסיביות או רגישות יותר, כמו שינויים בחשבון, יכולות להיות מגבלות נמוכות יותר.
הקצאת מכסות והיררכיה
בקטע הזה מוסבר בשם מי Merchant API עוקב אחרי ניצול המכסות ומחיל אותו:
באופן כללי, המכסה מחויבת על סמך המשתמש ששולח את בקשת ה-API.
- חשבונות נפרדים: בחשבונות נפרדים שמאמתים קריאה ל-API, הבקשה נספרת במכסה של אותו חשבון.
- דוגמה: מוכר Shoe Store A (מזהה חשבון: 12345) מבצע אימות באמצעות חשבון השירות שלו כדי לשלוח קריאה אל
products.insertשמטרגטת את החשבון שלו (accounts/12345). המכסה נצרכת ממאגר המכסות של Shoe Store A.
- דוגמה: מוכר Shoe Store A (מזהה חשבון: 12345) מבצע אימות באמצעות חשבון השירות שלו כדי לשלוח קריאה אל
- חשבונות מתקדמים: אימות כחשבון מתקדם צורך מכסה ממאגר המכסות של החשבון המתקדם, גם כשמטרגטים חשבון משנה.
- דוגמה: סוכנות עם חשבון ניהול קמעונאי (מספר חשבון מתקדם: 12345) מנהלת חשבון משני בשם חנות בגדים ב' (מספר חשבון: 11111).
הסוכנות מאמתת את עצמה באמצעות פרטי הכניסה שלה וקוראת ל-
products.insertשמטרגט את Clothing Store B (accounts/11111). המכסה נצרכת מהמאגר של סוכנות ההורה (מזהה חשבון מתקדם: 12345), ולא מהמאגר של חשבון המשנה.
- דוגמה: סוכנות עם חשבון ניהול קמעונאי (מספר חשבון מתקדם: 12345) מנהלת חשבון משני בשם חנות בגדים ב' (מספר חשבון: 11111).
הסוכנות מאמתת את עצמה באמצעות פרטי הכניסה שלה וקוראת ל-
- חשבונות משנה: כשקריאות ל-API מאומתות באמצעות פרטי הכניסה של חשבון משנה, המכסה מחויבת במאגר הנפרד של אותו חשבון משנה. החשבון הזה פועל כמו חשבון עצמאי, למרות שהוא מנוהל על ידי חשבון מתקדם ראשי.
- דוגמה: נשתמש באותה הגדרה כמו בדוגמה הקודמת. אם חנות הבגדים ב' (מזהה חשבון: 11111) מבצעת אימות באמצעות פרטי כניסה שהוגדרו במיוחד לחשבון המשנה שלה כדי לשלוח קריאה ל-
products.insertשמטרגטת את החשבון שלה (accounts/11111), המכסה נצרכת ממאגר המכסות הנפרד של חנות הבגדים ב', ומאגר המכסות של סוכנות האם נשאר ללא שינוי.
- דוגמה: נשתמש באותה הגדרה כמו בדוגמה הקודמת. אם חנות הבגדים ב' (מזהה חשבון: 11111) מבצעת אימות באמצעות פרטי כניסה שהוגדרו במיוחד לחשבון המשנה שלה כדי לשלוח קריאה ל-
חריגים לכללים הכלליים
יש כמה חריגים ספציפיים לכללים הכלליים של הקצאת המכסות:
- Accounts.list: המכסה של השיטה הזו מחויבת בחשבון המשתמש המאומת או בחשבון השירות שמבצע את הקריאה, ולא במזהה החשבון ב-Merchant Center.
השימוש במכסה לא יופיע בדף האבחון הרגיל של Merchant Center API.
אם יש לכם חשבון מתקדם, מומלץ להשתמש בשיטה
accounts.listSubaccounts, שנספרת במכסת החשבונות המתקדמים. - שיטות לפתרון בעיות: השיטות האלה תמיד נספרות במכסה של החשבון שבו מבקשים לפתור את הבעיות, גם אם הבקשה מאומתת בחשבון אחר.
היררכיית ההקצאה
שירותי השוואת מחירים (CSS): שירותי השוואת מחירים הם אתרים שמרכזים מוצרים למכירה ומפנים את המשתמשים לאתרים של קמעונאים כדי לבצע רכישות. כשמבצעים קריאות ל-API, המכסות חלות על קבוצת ה-CSS, דומיין ה-CSS, החשבון או חשבון המשנה הספציפיים שאתם מאמתים.
לדוגמה:
- קבוצת CSS בשם Europe Shopping Group (מספר חשבון: 10001) רוצה להציג את דומייני ה-CSS שמשויכים אליה. האימות מתבצע באמצעות פרטי הכניסה של החשבון עצמו כדי לבצע את הקריאה ל-API, והמכסה נצרכת ישירות ממאגר המכסות של Europe Shopping Group.
- דומיין CSS בשם TopDeals CSS (מספר חשבון: 20002) מבצע אימות כדי לקרוא לשיטה שמטרגטת את אחד מחשבונות המוכרים שמשויכים אליו (
accounts/30003) כדי להקצות תווית. המכסה מנוצלת ממאגר המכסות של שירות ה-CSS TopDeals, ולא ממאגר המכסות של חשבון המוכר.
זירות מסחר: זירות מסחר הן פלטפורמות אונליין שמארחות כמה מוכרים עצמאיים. הם פועלים כחשבונות מתקדמים מיוחדים שמאפשרים לכם ליצור חשבונות משנה נפרדים לכל אחד מהמוכרים שלכם.
בתרשים הבא מוצגת ההיררכיה של קבוצות CSS, שירותי CSS, זירות מסחר, חשבונות מתקדמים, חשבונות עצמאיים וחשבונות משנה.

התאמה אוטומטית של המכסות
ל-Merchant API יש מערכת אוטומטית לניהול מכסות בשירותים ספציפיים. המערכת מתאימה את מגבלות המכסות למוכרים שמתרחבים, על סמך השימוש, המוצרים וגודל החשבון. Merchant API מחשב מחדש את המכסות האלה מדי יום.
קבוצות המכסות שנכללות בהתאמות האוטומטיות של המכסות הן:
שירותי מוצרים
- כל קבוצות המכסות של השיטות שקשורות למשאבים
productsו-productInputs. - המכסה היומית של הקריאות מוגדרת בדרך כלל לפי מספר המוצרים המשווקים שהמוכר יכול לשווק כפול 2. ההנחה היא שמוכר עשוי לעדכן כל אחד מהמוצרים שלו עד פעמיים ביום.
- אפשר לעדכן מוצרים ספציפיים יותר מפעמיים, אבל מספר הקריאות היומי הכולל ל-API לא יכול לחרוג ממכסת הקריאות היומית המצטברת.
שירותי חשבונות
- כל קבוצות המכסות של השיטות שקשורות למשאבים השונים שקשורים לחשבון ב-Merchant API.
- מכסת הקריאות היומית מוגדרת למספר המקסימלי של חשבונות משנה שמותרים לאותו חשבון. כך אפשר לבצע עד שתי קריאות ביום לכל חשבון משנה.
שירותי מקורות נתונים
- כל קבוצות המכסות של השיטות שקשורות למשאבים שקשורים למקור הנתונים ב-Merchant API, כמו
listאוcreate, שחשבון מתקדם מבצע בחשבונות המשנה שלו. - מכסת הקריאות היומית מוגדרת בדרך כלל לפי מספר חשבונות המשנה בחשבון המתקדם כפול 2. ההנחה היא שמוכר יכול לעדכן את מקורות הנתונים של כל אחד מחשבונות המשנה שלו עד פעמיים ביום.
רק בשירותים שתוארו קודם יש התאמות אוטומטיות של המכסות. בשירותים אחרים יש מכסה שמוגדרת כברירת מחדל, וצריך לבקש ידנית להגדיל אותה. איך מגדילים את המכסות?
מה קורה כשחורגים מהמכסות
אם חורגים מהמכסה, מופיעות שגיאות בתגובות מה-API ובדף האבחון בחשבון Merchant Center:
- לדקה:
quota/request_rate_too_high
{
"error": {
"code": 429,
"message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
}
}
]
}
}
- ליום:
quota/daily_limit_exceeded
{
"error": {
"code": 429,
"message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_TOO_MANY_REQUESTS"
}
}
]
}
}
השגיאות הבאות קשורות למגבלות של Merchant Center, ולא למכסות של Merchant API. אתם יכולים לנסות לבקש הגדלה של מכסת הפריטים, הפידים או חשבונות המשנה:
-
too_many_items: חריגה ממכסת המוֹכרים -
too_many_subaccounts: הגעת למספר המקסימלי של חשבונות משנה
מעקב וניראות
כדי לבדוק את מכסות הקריאות הנוכחיות ואת השימוש בחשבון, קוראים ל-quotas.list עם שם החשבון.
POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}
מחליפים את מה שכתוב בשדות הבאים:
-
ACCOUNT_ID: מספר חשבון Merchant Center -
ACCESS_TOKEN: אסימון ההרשאה לביצוע הקריאה ל-API
אם הבקשה תצליח, ה-API יחזיר רשימה של משאבי quotaGroups שמכילים את המשאב name של קבוצת המכסות, את המכסות השונות ואת השיטות שעליהן חלה המכסה של הקבוצה.
{
"quotaGroups": [
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
"quotaUsage": "2",
"quotaLimit": "1000",
"methodDetails": [
{
"method": "quotaservice.listquotagroups",
"version": "v1",
"subapi": "quota",
"path": "quota/v1/quotaservice.listquotagroups"
}
],
"quotaMinuteLimit": "10"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
"quotaLimit": "10000",
"methodDetails": [
{
"method": "commissiongroupservice.listcommissiongroups",
"version": "v1",
"subapi": "youtube",
"path": "youtube/v1/commissiongroupservice.listcommissiongroups"
}
],
"quotaMinuteLimit": "60"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
"quotaLimit": "20000000",
"methodDetails": [
{
"method": "merchantreviewsservice.listmerchantreviews",
"version": "v1",
"subapi": "reviews",
"path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
}
],
"quotaMinuteLimit": "60000"
}
]
}
תהליך הגדלת המכסה
כדי לבקש מכסה נוספת, פותחים את טופס הפנייה לתמיכה, בוחרים באפשרות "בקשה להגדלת מכסה" בשדה החובה "מה הבעיה/השאלה" וממלאים את כל שדות החובה, כולל מספר חשבון Merchant Center, שיטות היעד וההצדקה העסקית.
- למשאבים עם מכסות אוטומטיות (
products,accountsו-datasourcesלחשבונות מתקדמים): אפשר לבקש רק הגדלה זמנית בתרחישים מיוחדים, כמו השקה בשוק חדש או במהלך עונות קניות עם נפח תנועה גבוה. אנחנו לא מאשרים הגדלות קבועות של מכסות לסוגי המשאבים האלה. - לכל המשאבים האחרים שאין להם מכסות אוטומטיות: צריך לבקש הגדלה של המכסות לפי הצורך.
מומלץ לבדוק את המכסות מדי פעם כדי לוודא שיש לכם מספיק מכסות להטמעה, ולראות איך המכסה מותאמת באופן אוטומטי.
אפשר להשתמש ב-method quotas.list כדי לראות את מגבלת המכסה היומית הנוכחית, את המגבלה לדקה ואת השימוש היומי הנוכחי בכל קבוצת methods של ה-API.
שיטות מומלצות
השיטות המומלצות האלה יעזרו לכם לוודא שהשילוב פועל בצורה חלקה, להימנע משגיאות מכסה בלתי צפויות ולהשתמש במשאבים של Merchant Center ביעילות.
אופטימיזציה של חלוקת הבקשות
- פיזור הבקשות באופן שווה: הימנעו משליחת כמות גדולה של בקשות בבת אחת. כדי לא לחרוג ממגבלות המכסה לדקה (
quotaMinuteLimit), פזרו את הקריאות היומיות ל-API באופן שווה לאורך היום. - הגבלת קצב יזומה: הטמיעו באפליקציה הגבלת קצב של יצירת בקשות בצד הלקוח. אל תסתמכו רק על השרתים של Google כדי לדחות תנועה עודפת. שליטה בקצב הבקשות במקור.
טיפול בשגיאות בצורה חלקה
- טיפול בשגיאת HTTP 429: האפליקציה צריכה להיות מוכנה לטפל בשגיאות 429 Too Many Requests (
quota/request_rate_too_high). - השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם תנודות: כשמנסים שוב לשלוח בקשות שנכשלו (במיוחד אחרי שגיאה 429), כדאי להשתמש בהשהיה מעריכית לפני ניסיון חוזר (זמני המתנה הולכים וגדלים) ולהוסיף "תנודות" (עיכוב אקראי). התנודות מונעות "סערות של ניסיונות חוזרים", שבהן כמה מכונות של לקוחות מנסות שוב בדיוק באותו זמן, מה שגורם לעומס יתר על השרת.
- לפעול לפי ההנחיות לניסיון חוזר: אם התגובה מה-API כוללת פרטים או כותרות לגבי ניסיון חוזר, צריך להשתמש בהם כדי לקבוע מתי לחדש את הקריאות.
צמצום שיחות מיותרות
- מניעת קריאות לא עדכניות (שגיאת 404 NOT_FOUND): אל תבקשו או תמחקו משאבים שכבר לא קיימים. גם קריאות שנכשלו נספרות במכסת ה-API. כדי לזהות מעקב אחר מצב לא עדכני או דגימה מיותרת, עוקבים אחרי שגיאות
NOT_FOUNDבכלי לאבחון API ב-Merchant Center. - אימות לפני עדכון: לפני ששולחים בקשת עדכון, בודקים אם הנתונים באמת השתנו. אל תשלחו עדכונים שכותבים את אותם ערכים.
- שימוש במטמון: כדאי לשמור במטמון המקומי תגובות קריאה (למשל, פרטי מוצרים, הגדרות) כשזה מתאים, כדי להימנע מקריאות חוזרות ל-
getאו ל-listלנתונים שלא השתנו.
הסבר על היררכיית המכסות והחריגות
- חשבונות מתקדמים וחשבונות משנה: אם יש לכם חשבון מתקדם, אתם צריכים לבצע אימות ברמת החשבון המתקדם כדי שהקריאות ייספרו במאגר המשותף של החשבונות המתקדמים.
- שימוש ב-
listSubaccounts: בחשבונות מתקדמים, צריך להשתמש ב-accounts.listSubaccountsבמקום ב-accounts.list. המכסה שלaccounts.listמחויבת למשתמש המתקשר (לא למזהה ה-MC) ולא גלויה באבחון הרגיל.listSubaccountsנכלל במכסה של חשבון ה-MCA.