מכסות

במסמך הזה מפורטות המכסות שחלות על Merchant API.

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

מושגים כלליים

המכסות של Merchant API מנוהלות באמצעות קבוצות מכסות.

שיטות API ממופות לקבוצות מכסות. המבנה של המיפוי הזה יכול להיות שונה:

  • שיטה אחת לכל קבוצה: חלק מקבוצות המכסות חלות על שיטת API אחת. לדוגמה, לשיטה listing data sources‏ accounts.dataSources.list יש קבוצת מכסות ייעודית משלה.
  • כמה שיטות בכל קבוצה (חבילה): לעיתים קרובות, שיטות קשורות נכללות בחבילה אחת של קבוצת מכסות. לכל השיטות בקבוצה יש את אותן מגבלות יומיות ומגבלות לדקה. דוגמאות נפוצות:
    • קיבוץ של כל פעולות הקריאה לשיטות ולמשאבים קשורים, כמו merchant-accounts-read-methods.
    • קיבוץ כל פעולות הכתיבה לשיטות ולמשאבים קשורים, כמו merchant-accounts-write-methods.

כל הפעלת method נספרת פעם אחת, ללא קשר לסוג שלה. בקשת list של 250 פריטים נספרת רק פעם אחת, ולא כ-250 בקשות get.

HTTP batching מובנה לא משפיע על המכסה. כל בקשה בודדת באצווה של בקשות נספרת כיחידה אחת במכסה. לדוגמה, בקשת Batch שמכילה 500 בקשות לשיטת insert תחויב כ-500 בקשות נפרדות לשיטת insert.

חריג לגבי קבוצות של אזורים ייעודיים: שיטות מיוחדות של קבוצות אזורים (batchCreate, batchUpdate, batchDelete) נספרות כקריאה אחת ל-API במסגרת קבוצת המכסות merchant_regions, ללא קשר למספר הפעולות באזור שנכללות במטען הייעודי (payload).

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

עדכון מדיניות

ה-Merchant API אוכף את כללי המדיניות הבאים בנוגע לעדכונים:

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

מכסות לקצב שליחת בקשות

לכל קבוצת מכסות יש שני סוגים של מגבלות (ושימוש יומי):

  • מגבלה יומית (quotaLimit): מספר הבקשות המקסימלי שמותר לשלוח בכל יום. המכסות היומיות מתאפסות בשעה 12:00 בצהריים לפי שעון UTC.
  • מגבלה לדקה (quotaMinuteLimit): מספר הבקשות המקסימלי שמותר לשלוח בדקה, כדי לשלוט בקצב הבקשות. מגבלות המכסה לדקה מבוססות על חלון זמן מתמשך, שבו תקופת האכיפה מתחילה מהרגע שבו מתבצעת קריאת ה-API הראשונה לאותו method ולאותו משאב. לדוגמה, אם מבצעים קריאה בשעה 10:01:30, חלון המכסה לדקה של ה-method הזו יפעל עד השעה 10:02:30.
  • שימוש יומי (quotaUsage): מספר הבקשות שכבר בוצעו ונכללו במגבלה היומית של היום הנוכחי. אם השדה חסר, סימן שלא נעשה שימוש במכסה של הקבוצה הזו.

אפשר למצוא את שלושת השדות שמתוארים למעלה (quotaLimit,‏ quotaMinuteLimit ו-quotaUsage) בתגובה של השיטה quotas.list.

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

הקצאת מכסות והיררכיה

בקטע הזה מוסבר מטעם מי Merchant API עוקב אחרי השימוש במכסה ומחיל את המכסה:

באופן כללי, המכסה מחויבת על סמך המשתמש שמבצע את בקשת ה-API.

  • חשבונות עצמאיים: כשמבצעים אימות של קריאה ל-API בחשבונות עצמאיים, הבקשה הזו נספרת במסגרת המכסה של החשבון.
    • דוגמה: מוכר בשם Shoe Store A (מזהה חשבון: 12345) מבצע אימות באמצעות חשבון השירות שלו כדי להתקשר אל products.insert ולטרגט את החשבון שלו (accounts/12345). הניצול של המכסה מתבצע ממאגר המכסות של Shoe Store A.
  • חשבונות מתקדמים: כשמבצעים אימות כחשבון מתקדם, המכסה נלקחת ממאגר המכסות של החשבון המתקדם, גם כשמטרגטים חשבון משנה.
    • דוגמה: סוכנות עם חשבון לניהול קמעונאי (מזהה חשבון מתקדם: 12345) מנהלת חשבון משנה Clothing Store B (מזהה חשבון: 11111). הסוכנות מאמתת את עצמה באמצעות פרטי הכניסה שלה ומבצעת קריאות products.insert לטירגוט חנות בגדים ב' (accounts/11111). המכסה נלקחת ממאגר המכסות של החשבון הראשי של הסוכנות (מזהה החשבון המתקדם: 12345), ולא ממאגר המכסות של חשבון המשנה.
  • חשבונות משנה: כשמבצעים אימות של קריאות ל-API באמצעות פרטי הכניסה של חשבון משנה, המכסה מחויבת למאגר הנפרד של חשבון המשנה הזה. החשבון הזה פועל כמו חשבון עצמאי, למרות שהוא מנוהל על ידי חשבון מתקדם של הורה.
    • דוגמה: אם Clothing Store B (מספר חשבון: 11111) מאמת את עצמו באמצעות פרטי כניסה שהוגדרו במיוחד לחשבון המשנה שלו כדי לבצע קריאה ל-products.insert ולטרגט את החשבון שלו (accounts/11111), המכסה תנוצל ממאגר המכסות האישי של Clothing Store B, והמאגר של סוכנות האם לא יושפע.

חריגים לכללים הכלליים

יש כמה חריגים ספציפיים שחלים על הכללים הכלליים של הקצאת המכסות:

היררכיית הקצאה

  • שירותי השוואת מחירים (CSS): שירותי השוואת מחירים הם אתרים שמציגים מוצרים למכירה ומפנים את המשתמשים לאתרי קמעונאים כדי לבצע רכישות. כשמבצעים קריאות ל-API, המכסות חלות על קבוצת ה-CSS, דומיין ה-CSS, החשבון או חשבון המשנה הספציפיים שאליהם מתבצעת האימות.

    לדוגמה:

    • קבוצת CSS בשם Europe Shopping Group (מזהה חשבון: 10001) רוצה להציג את הדומיינים המשויכים של שירותי ה-CSS שלה. האימות מתבצע באמצעות פרטי הכניסה של חשבון השירות, ולכן המכסה נלקחת ישירות ממאגר המכסות של Europe Shopping Group.
    • דומיין CSS‏ TopDeals CSS (מספר חשבון: 20002) עובר אימות כדי להפעיל שיטה שמטרגטת אחד מחשבונות המוכר המשויכים שלו (accounts/30003) ולהקצות תווית. המכסה נלקחת ממאגר המכסות של שירות ה-CSS TopDeals ולא ממאגר המכסות של חשבון המוכר.

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

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

קבוצת CSS היא רמת האימות הכוללת, עם אפשרות לשירותי CSS נפרדים בתוכה, חשבונות בתוך השירותים האלה וחשבונות משנה כרמה הכי נפרדת.

התאמה אוטומטית של נפח האחסון

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

קבוצות המכסות שנכללות בהתאמות אוטומטיות של מכסות הן:

שירותי מוצרים

  • כל קבוצות המכסות של שיטות שקשורות למשאבים products ו-productInputs.
  • המכסה היומית של קריאות ה-API מוגדרת בדרך כלל ככפולה של מכסת המוצרים שיש למוכר. ההנחה היא שמוֹכרים עשויים להצטרך לעדכן כל אחד מהמוצרים שלהם עד פעמיים ביום.
  • אפשר לעדכן מוצרים ספציפיים יותר מפעמיים, אבל מספר קריאות ה-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 של API, משתמשים ב-method‏ quotas.list.

שיטות מומלצות

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

אופטימיזציה של הפצת הבקשות

  • פיזור הבקשות באופן שווה: מומלץ להימנע משליחת פרצים גדולים של בקשות. כדי לא לחרוג ממגבלות המכסה לדקה (quotaMinuteLimit), מומלץ לפזר את הקריאות היומיות ל-API באופן שווה לאורך היום.
  • הגבלת קצב בקשות יזומה: הטמעה של הגבלת קצב בקשות בצד הלקוח באפליקציה. אל תסתמכו רק על השרתים של Google כדי לדחות תנועה עודפת. שולטים בקצב הבקשות במקור.

טיפול בשגיאות בצורה חלקה

  • טיפול בשגיאת HTTP 429: האפליקציה צריכה להיות מוכנה לטפל בשגיאות מסוג 429 Too Many Requests (quota/request_rate_too_high).
  • השהיה מעריכית לפני ניסיון חוזר עם רעידות: כשמנסים שוב לשלוח בקשות שנכשלו (במיוחד אחרי קוד 429), צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (הגדלת זמני ההמתנה) ולהוסיף 'רעידות' (עיכוב אקראי). הוספת תנודות מונעת 'סופות של ניסיונות חוזרים', שבהן כמה מופעים של לקוחות מנסים שוב בדיוק באותו הזמן, ויוצרים עומס יתר על השרת שוב.
  • התייחסות להצעות לניסיון חוזר: אם התגובה של ה-API מכילה פרטים או כותרות לגבי ניסיון חוזר, צריך להשתמש בהם כדי לקבוע מתי לחדש את הקריאות.

צמצום שיחות מיותרות

  • מניעת שיחות לא עדכניות (404 NOT_FOUND): מומלץ להימנע מבקשות או ממחיקה של משאבים שכבר לא קיימים. גם קריאות שנכשלו צורכות מכסת API. כדאי לעקוב אחרי שגיאות ב'אבחון API' ב-Merchant CenterNOT_FOUND כדי לזהות מעקב לא עדכני אחרי סטטוס או סקרים מיותרים.
  • אימות לפני עדכון: לפני ששולחים בקשת עדכון, צריך לבדוק אם הנתונים באמת השתנו. אל תשלחו עדכונים שכותבים את אותם ערכים.
  • שימוש במטמון: שמירת תשובות לקריאות (למשל, פרטי מוצר, הגדרות) במטמון באופן מקומי כשמתאים, כדי להימנע מקריאות חוזרות ל-get או ל-list עבור נתונים שלא השתנו.
  • חשבונות מתקדמים וחשבונות משנה: אם יש לכם חשבון מתקדם, תצטרכו לאמת את החשבון ברמה של החשבון המתקדם אם אתם רוצים שהשיחות ייספרו במאגר המשותף של החשבונות המתקדמים.
  • שימוש ב-listSubaccounts: בחשבונות מתקדמים, משתמשים ב-accounts.listSubaccounts במקום ב-accounts.list. המיכסה accounts.list מחויבת למשתמש המתקשר (לא למזהה המרכז) והיא לא גלויה באבחון הסטנדרטי. listSubaccounts נכלל במכסת החשבונות הראשיים שלכם.
הקודם
Overview
הבא
Merchant Center limits