ניהול של קבוצות אזורים

אזור ב-Merchant API מייצג אזור גיאוגרפי שאפשר להשתמש בו כיעד שקשור למשאב accounts.products.regionalInventories. אפשר להגדיר אזורים כאוספים של מספרי מיקוד או, במדינות מסוימות, באמצעות טירגוטים גיאוגרפיים מוגדרים מראש. מידע נוסף מופיע במאמר בנושא הגדרת אזורים.

‫Merchant API מספק נקודות קצה (endpoints) של קבוצות לניהול האזורים שלכם, שמאפשרות ליצור, לעדכן ולמחוק עד 100 אזורים בקריאה אחת ל-API. התכונה הזו מתאימה במיוחד למוכרים שמנהלים זמינות ותמחור לפי אזור (RAAP) בהיקף גדול, כי היא משפרת את היעילות ומפשטת את השילוב.

סקירה כללית

‫Batch API מאפשר לכם לבצע את הפעולות הבאות באמצעות ה-methods המשויכות:

  • יצירת כמה אזורים בבקשה אחת: regions:batchCreate
  • כדי למחוק כמה אזורים בבת אחת: regions:batchDelete
  • כדי לעדכן כמה אזורים בו-זמנית: regions:batchUpdate

דרישות מוקדמות

כל הבקשות לביצוע פעולות בקבוצות מחייבות אימות של תפקיד המשתמש ADMIN.

יצירת כמה אזורים

בדוגמה הזו מוצג איך ליצור שני אזורים חדשים – אחד מוגדר לפי מיקודים ואחד לפי טירגוט גיאוגרפי – בקריאה אחת של BatchCreateRegions.

בקשה

בונים את כתובת ה-URL של הבקשה באופן הבא:

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate

גוף הבקשה מכיל רשימה של requests, כאשר כל אובייקט מציין regionId ואת נתוני region שצריך ליצור.

{
  "requests": [
    {
      "regionId": "seattle-area-98340",
      "region": {
        "displayName": "Seattle Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98340"
            }
          ]
        }
      }
    },
    {
      "regionId": "co-de-states",
      "region": {
        "displayName": "Colorado and Delaware",
        "geoTargetArea": {
          "geotargetCriteriaIds": [
            "21138",
            "21141"
          ]
        }
      }
    }
  ]
}

תשובה

בקשה שמושלמת בהצלחה מחזירה רשימה של אובייקטים חדשים של region.

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
      "displayName": "Seattle Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98340"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
      "displayName": "Colorado and Delaware",
      "geotargetArea": {
        "geotargetCriteriaIds": [
          "21138",
          "21141"
        ]
      },
      "regionalInventoryEligible": false,
      "shippingEligible": false
    }
  ]
}

עדכון של מספר אזורים

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

בקשה

בונים את כתובת ה-URL של הבקשה באופן הבא:

POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate

גוף הבקשה מכיל רשימה של requests. בכל אובייקט צריך לציין את נתוני region לעדכון. השדה region.name חייב להכיל את מזהה האזור שרוצים לעדכן, לדוגמה, 98005. מציינים את המשאב כ-name ולא כ-accounts/{ACCOUNT_ID}/regions/name. אפשר לכלול את updateMask כדי לציין את השדות שרוצים לשנות.

{
  "requests": [
    {
      "region": {
        "name": "98005",
        "displayName": "Seattle Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98330"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    },
    {
      "region": {
        "name": "07086",
        "displayName": "NewYork Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "11*"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    }
  ]
}

תשובה

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

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/98005",
      "displayName": "Seattle Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98330"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/07086",
      "displayName": "NewYork Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "11*"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    }
  ]
}

מחיקה של כמה אזורים

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

בקשה

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

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete

גוף הבקשה מכיל רשימה של requests, שבה כל אובייקט מציין את name (בלי "accounts/{ACCOUNT_ID}/regions/") של האזור שרוצים למחוק.

{
  "requests":
   [
    {
      "name": "98005"
    },
    {
      "name": "07086"
    }
   ]
}

תשובה

בקשה שמושלמת בהצלחה מחזירה גוף תגובה ריק, שמציין שהאזורים שצוינו נמחקו (או שלא היו קיימים).

{}

מגבלות

לפני שמתחילים, חשוב לזכור את הכללים הבאים:

  • פעולות אטומיות: בקשות באצווה הן אטומיות. אם פעולה אחת באצווה תיכשל (לדוגמה, אם לא תצליחו ליצור אזור אחד), האצווה כולה תיכשל ולא יבוצעו שינויים. ה-API יחזיר שגיאה עם פרטים על הסיבה לכישלון.
  • מגבלות על אצווה: כל בקשת אצווה יכולה להכיל עד 100 פעולות באזור.
  • מכסות: נקודות הקצה האלה משתמשות באותן קבוצות מכסות כמו נקודות הקצה המקבילות שלהן עם פעולה אחת (regions.create, regions.delete, regions.update).

שגיאות ובעיות נפוצות

ריכזנו כאן כמה בעיות נפוצות ואת הפתרונות שלהן.

"מספר הבקשות באצווה גדול מדי"

השגיאה הזו מתרחשת אם מספר הפעולות במערך הבקשות חורג מהמגבלה של 100.

"error":
  {
    "code": 400,
    "message": "The number of requests in a batch is too large.",
    "status": "INVALID_ARGUMENT"
  }

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

חסר שדה חובה

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

הודעות השגיאה הן:

  • בלוקאל batchCreate: ‏[regionId] Required parameter: regionId
  • בלוקאל batchUpdate: ‏[region.name] Required field not provided.
  • בלוקאל batchDelete: ‏[name] Required parameter: name

כדי לפתור את הבעיה, צריך לוודא שכל שדות החובה מופיעים בכל פעולה. לדוגמה, כל רשומה בבקשת batchUpdate חייבת לכלול את region.name. פרסום הבקשה הבאה יוביל לשגיאה:

{
  "requests":
  [
    {
      "region":
        {
          "displayName": "An update without a region name"
        },
        "updateMask": "displayName"
    }
  ]
}

‫"Region with specified ID already exists" (אזור עם המזהה שצוין כבר קיים)

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

הודעת השגיאה היא [regionId] Region with specified id already exists..

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

‫"Duplicate value found for field region.name or regionId found" (נמצא ערך כפול בשדה region.name או regionId)

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

הודעת השגיאה היא Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

כדי לפתור את הבעיה, מוודאים שכל הערכים של regionId (עבור batchCreate) או של region.name (עבור batchUpdate) ייחודיים בבקשת Batch אחת.

‫"Item not found" (הפריט לא נמצא)

כשמשתמשים ב-batchUpdate, אם אזור כלשהו שצוין בבקשה לא קיים, כל האצווה תיכשל ותוצג השגיאה 404 NOT_FOUND. ההתנהגות הזו שונה מזו של batchDelete, שפועלת גם לאזורים לא קיימים.

"error": {
    "code": 404,
    "message": "item not found",
    "status": "NOT_FOUND"
}

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

הקודם
Create and update regions
הבא
Manage Merchant Center email preferences