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

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

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

סקירה כללית

באמצעות Batch API, אתם יכולים לבצע את הפעולות הבאות בעזרת השיטות המשויכות:

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

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

כדי לאמת את כל בקשות ה-Batch, נדרש תפקיד המשתמש ADMIN.

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

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

בקשה

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

POST
https://merchantapi.googleapis.com/accounts/v1/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
    }
  ]
}

בדוגמה הבאה אפשר לראות איך יוצרים כמה אזורים בבקשת אצווה:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.CreateRegionRequest;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea.PostalCodeRange;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to create multiple regions for a Merchant Center account. */
public class BatchCreateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  public static void batchCreateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the regions.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<CreateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            CreateRegionRequest.newBuilder()
                .setParent(parent)
                .setRegionId(regionId)
                .setRegion(
                    Region.newBuilder()
                        .setDisplayName("Region " + regionId)
                        .setPostalCodeArea(
                            PostalCodeArea.newBuilder()
                                .setRegionCode("US")
                                .addPostalCodes(
                                    PostalCodeRange.newBuilder()
                                        .setBegin("10001")
                                        .setEnd("10282")
                                        .build())
                                .build())
                        .build())
                .build());
      }

      BatchCreateRegionsRequest request =
          BatchCreateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Create Regions request");
      BatchCreateRegionsResponse response = regionsServiceClient.batchCreateRegions(request);
      System.out.println("Inserted Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to create.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchCreateRegions(config, regionIds);
  }
}

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

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

בקשה

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

POST https://merchantapi.googleapis.com/accounts/v1/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
    }
  ]
}

בדוגמה הבאה אפשר לראות איך לעדכן כמה אזורים בבקשת אצווה:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import com.google.shopping.merchant.accounts.v1.UpdateRegionRequest;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to update multiple regions for a Merchant Center account. */
public class BatchUpdateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchUpdateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to update the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<UpdateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            UpdateRegionRequest.newBuilder()
                .setRegion(
                    Region.newBuilder()
                        .setName(getRegionName(accountId, regionId))
                        .setDisplayName("Updated Region " + regionId)
                        .build())
                .setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build())
                .build());
      }

      BatchUpdateRegionsRequest request =
          BatchUpdateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Update Regions request");
      BatchUpdateRegionsResponse response = regionsServiceClient.batchUpdateRegions(request);
      System.out.println("Updated Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to update.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchUpdateRegions(config, regionIds);
  }
}

מחיקת כמה אזורים

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

בקשה

בדוגמה הזו מוסבר איך משתמשים ב-BatchDeleteRegions כדי למחוק שני אזורים בקריאה אחת.

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

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

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

תשובה

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

{}

בדוגמה הבאה אפשר לראות איך למחוק כמה אזורים בבקשת אצווה:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchDeleteRegionsRequest;
import com.google.shopping.merchant.accounts.v1.DeleteRegionRequest;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to delete multiple regions for a Merchant Center account. */
public class BatchDeleteRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchDeleteRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to delete the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<DeleteRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            DeleteRegionRequest.newBuilder().setName(getRegionName(accountId, regionId)).build());
      }

      BatchDeleteRegionsRequest request =
          BatchDeleteRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Delete Regions request");
      regionsServiceClient.batchDeleteRegions(request);
      System.out.println("Regions deleted successfully");

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to delete.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchDeleteRegions(config, regionIds);
  }
}

מגבלות

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

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

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

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

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

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

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

כדי לפתור את הבעיה, צריך לפצל את הפעולות לכמה בקשות Batch של 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"
    }
  ]
}

"כבר קיים אזור עם המזהה שצוין"

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

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

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

"נמצא ערך כפול בשדה region.name או regionId"

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

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

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

"הפריט לא נמצא"

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

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

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