Quản lý việc phân lô theo khu vực

Khu vực Merchant API đại diện cho một khu vực địa lý mà bạn có thể sử dụng làm mục tiêu liên quan đến tài nguyên accounts.products.regionalInventories. Bạn có thể xác định khu vực là tập hợp các mã bưu chính hoặc sử dụng các mục tiêu địa lý được xác định trước ở một số quốc gia. Để biết thêm thông tin, hãy xem bài viết Thiết lập khu vực.

Merchant API cung cấp các điểm cuối theo lô để quản lý khu vực, cho phép bạn tạo, cập nhật và xoá tối đa 100 khu vực trong một lệnh gọi API. Đây là lựa chọn lý tưởng cho những người bán quản lý tình trạng còn hàng và giá theo khu vực (RAAP) trên quy mô lớn, giúp nâng cao hiệu quả và đơn giản hoá việc tích hợp.

Tổng quan

Batch API cho phép bạn thực hiện những việc sau bằng các phương thức liên quan:

  • Tạo nhiều khu vực trong một yêu cầu: regions:batchCreate
  • Xoá nhiều khu vực cùng lúc: regions:batchDelete
  • Cập nhật nhiều khu vực cùng lúc: regions:batchUpdate

Điều kiện tiên quyết

Tất cả yêu cầu theo lô đều cần có vai trò người dùng ADMIN để xác thực.

Tạo nhiều khu vực

Ví dụ này cho thấy cách tạo hai khu vực mới (một khu vực được xác định bằng mã bưu chính và một khu vực được xác định bằng tiêu chí nhắm mục tiêu theo vị trí địa lý) trong một lệnh gọi BatchCreateRegions.

Yêu cầu

Tạo URL yêu cầu như sau:

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

Nội dung yêu cầu chứa danh sách requests, trong đó mỗi đối tượng chỉ định một regionId và dữ liệu region cần tạo.

{
  "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"
          ]
        }
      }
    }
  ]
}

Phản hồi

Yêu cầu thành công sẽ trả về danh sách các đối tượng region mới.

{
  "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
    }
  ]
}

Mẫu sau đây minh hoạ cách tạo nhiều khu vực trong một yêu cầu theo lô:

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);
  }
}

Cập nhật nhiều khu vực

Ví dụ này cho thấy cách sử dụng BatchUpdateRegions để cập nhật displayName và postalCodeArea cho hai khu vực hiện có. Bạn phải cung cấp region.name để cập nhật khu vực mục tiêu.

Yêu cầu

Tạo URL yêu cầu như sau:

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

Nội dung yêu cầu chứa danh sách requests. Mỗi đối tượng phải chỉ định dữ liệu region cần cập nhật. Trường region.name phải chứa mã của khu vực cần cập nhật, ví dụ: "98005". Chỉ định tài nguyên là name thay vì accounts/{ACCOUNT_ID}/regions/name. Bạn không bắt buộc phải thêm updateMask để cho biết các trường cần thay đổi.

{
  "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"
    }
  ]
}

Phản hồi

Yêu cầu thành công sẽ trả về danh sách các đối tượng region đã cập nhật.

{
  "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
    }
  ]
}

Mẫu sau đây minh hoạ cách cập nhật nhiều khu vực trong một yêu cầu theo lô:

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);
  }
}

Xoá nhiều khu vực

Bạn có thể xoá nhiều vùng trong một lệnh gọi.

Yêu cầu

Ví dụ này cho thấy cách sử dụng BatchDeleteRegions để xoá hai vùng trong một lệnh gọi.

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

Nội dung yêu cầu chứa danh sách requests, trong đó mỗi đối tượng chỉ định name (không có "accounts/{ACCOUNT_ID}/regions/") của khu vực cần xoá.

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

Phản hồi

Yêu cầu thành công sẽ trả về nội dung phản hồi trống, cho biết rằng các khu vực được chỉ định đã bị xoá (hoặc không tồn tại).

{}

Mẫu sau đây minh hoạ cách xoá nhiều khu vực trong một yêu cầu theo lô:

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);
  }
}

Các điểm hạn chế

Trước khi bắt đầu, hãy lưu ý những quy tắc sau:

  • Thao tác nguyên tử: Yêu cầu theo lô là thao tác nguyên tử. Nếu có bất kỳ thao tác nào trong lô không thành công (ví dụ: không tạo được một khu vực), thì toàn bộ lô sẽ không thành công và không có thay đổi nào được thực hiện. API sẽ trả về một lỗi nêu chi tiết nguyên nhân gây ra lỗi.
  • Giới hạn theo lô: Mỗi yêu cầu theo lô có thể chứa tối đa 100 thao tác theo khu vực.
  • Hạn mức: Các điểm cuối này sử dụng cùng một nhóm hạn mức với các điểm cuối thao tác đơn lẻ (regions.create, regions.delete, regions.update).

Các lỗi và vấn đề thường gặp

Dưới đây là một số lỗi thường gặp và giải pháp.

"Số lượng yêu cầu trong một lô quá lớn"

Lỗi này xảy ra nếu số lượng thao tác trong mảng yêu cầu của bạn vượt quá giới hạn là 100.

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

Để khắc phục vấn đề này, hãy chia các thao tác thành nhiều yêu cầu theo lô, mỗi yêu cầu có tối đa 100 thao tác.

Thiếu trường bắt buộc

Lỗi này xảy ra khi thiếu một trường bắt buộc. Thông báo lỗi chỉ định tham số bị thiếu.

Thông báo lỗi như sau:

  • Đối với batchCreate: [regionId] Required parameter: regionId
  • Đối với batchUpdate: [region.name] Required field not provided.
  • Đối với batchDelete: [name] Required parameter: name

Để khắc phục vấn đề này, hãy xác minh rằng tất cả các trường bắt buộc đều có trong mỗi thao tác. Ví dụ: mọi mục nhập trong yêu cầu batchUpdate đều phải bao gồm region.name. Việc đăng yêu cầu sau đây sẽ dẫn đến lỗi:

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

"Khu vực có mã nhận dạng được chỉ định đã tồn tại"

Lỗi sẽ xảy ra nếu bạn cố gắng tạo một vùng có regionId đã tồn tại.

Thông báo lỗi là [regionId] Region with specified id already exists..

Để khắc phục vấn đề này, hãy xác minh rằng tất cả giá trị regionId đều là duy nhất trong lô và không xung đột với các khu vực hiện có.

"Đã tìm thấy giá trị trùng lặp cho trường region.name hoặc regionId"

Lỗi sẽ xảy ra nếu bạn cố gắng tạo hoặc cập nhật nhiều khu vực có cùng một mã nhận dạng trong một yêu cầu theo lô.

Thông báo lỗi là Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

Để khắc phục vấn đề này, hãy xác minh rằng tất cả giá trị regionId (cho batchCreate) hoặc region.name (cho batchUpdate) đều là duy nhất trong một yêu cầu theo lô.

"Không tìm thấy mục"

Khi sử dụng batchUpdate, nếu bất kỳ khu vực nào được chỉ định trong yêu cầu không tồn tại, thì toàn bộ lô sẽ không thành công và có lỗi 404 NOT_FOUND. Điều này khác với batchDelete, vốn thành công đối với các vùng không tồn tại.

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

Để khắc phục vấn đề này, hãy xác minh rằng tất cả khu vực bạn đang cố gắng cập nhật đều tồn tại trước khi gửi yêu cầu.

Trước
Create and update regions