מכסות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • ‫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 של מבצעים מובילים, ולא מתוך המאגר של חשבון המוכר.

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

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

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

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

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

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

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

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

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

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

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

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