จัดการการจัดกลุ่มตามภูมิภาค

ภูมิภาค Merchant API แสดงถึงภูมิภาคทางภูมิศาสตร์ที่คุณใช้เป็น เป้าหมายที่เกี่ยวข้องกับaccounts.products.regionalInventoriesได้ คุณสามารถ กำหนดภูมิภาคเป็นคอลเล็กชันของรหัสไปรษณีย์ หรือในบางประเทศ ใช้การกำหนดเป้าหมายตามภูมิศาสตร์ที่กำหนดไว้ล่วงหน้า ดูข้อมูลเพิ่มเติมได้ที่ตั้งค่า ภูมิภาค

Merchant API มีปลายทางแบบกลุ่มสำหรับการจัดการภูมิภาค ซึ่งช่วยให้คุณ สร้าง อัปเดต และลบภูมิภาคได้สูงสุด 100 ภูมิภาคในการเรียก API ครั้งเดียว ซึ่งเหมาะสำหรับผู้ขายที่จัดการความพร้อมจำหน่ายสินค้าและการกำหนดราคาระดับภูมิภาค (RAAP) ในวงกว้าง ช่วยปรับปรุงประสิทธิภาพและลดความซับซ้อนในการผสานรวม

ภาพรวม

Batch API ช่วยให้คุณทำสิ่งต่อไปนี้ได้ด้วยเมธอดที่เกี่ยวข้อง

  • สร้างหลายภูมิภาคในคำขอเดียว regions:batchCreate
  • ลบหลายภูมิภาคพร้อมกัน: regions:batchDelete
  • อัปเดตหลายภูมิภาคพร้อมกัน: regions:batchUpdate

ข้อกำหนดเบื้องต้น

คำขอแบบกลุ่มทั้งหมดต้องมีบทบาทผู้ใช้ ADMIN สำหรับการตรวจสอบสิทธิ์

สร้างหลายภูมิภาค

ตัวอย่างนี้แสดงวิธีสร้างภูมิภาคใหม่ 2 แห่ง โดยกำหนดภูมิภาคหนึ่งตามรหัสไปรษณีย์ และอีกภูมิภาคหนึ่งตามการกำหนดเป้าหมายตามภูมิศาสตร์ในการเรียกใช้ 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 สำหรับ 2 ภูมิภาคที่มีอยู่ คุณต้องระบุ 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 เพื่อลบ 2 ภูมิภาคในการเรียกใช้ครั้งเดียว

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

ข้อจำกัด

โปรดคำนึงถึงกฎต่อไปนี้ก่อนที่จะเริ่มต้น

  • การดำเนินการแบบอะตอมมิก: คำขอแบบกลุ่มเป็นแบบอะตอมมิก หากการดำเนินการใดก็ตาม ภายในกลุ่มไม่สำเร็จ (เช่น สร้างภูมิภาคไม่สำเร็จ) กลุ่มทั้งหมดจะไม่สำเร็จ และจะไม่มีการเปลี่ยนแปลงใดๆ 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"
    }
  ]
}

"มีภูมิภาคที่มีรหัสที่ระบุอยู่แล้ว"

ระบบจะแสดงข้อผิดพลาดหากคุณพยายามสร้างภูมิภาคที่มีregionIdที่ มีอยู่แล้ว

ข้อความแสดงข้อผิดพลาดคือ [regionId] Region with specified id already exists.

หากต้องการแก้ไขปัญหานี้ ให้ตรวจสอบว่าค่า regionId ทั้งหมดไม่ซ้ำกันภายในกลุ่ม และ ไม่ขัดแย้งกับภูมิภาคที่มีอยู่

"พบค่าที่ซ้ำกันสำหรับฟิลด์ region.name หรือพบ regionId"

ระบบจะแสดงข้อผิดพลาดหากคุณพยายามสร้างหรืออัปเดตหลายภูมิภาคที่มีรหัสเดียวกัน ภายในคำขอแบบกลุ่มเดียว

ข้อความแสดงข้อผิดพลาดคือ Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}.

หากต้องการแก้ไขปัญหานี้ ให้ตรวจสอบว่าค่า regionId ทั้งหมด (สำหรับ batchCreate) หรือ region.name (สำหรับ batchUpdate) ไม่ซ้ำกันภายในคำขอแบบกลุ่มเดียว

"ไม่พบรายการ"

เมื่อใช้ batchUpdate หากไม่มีภูมิภาคใดที่ระบุไว้ในคำขอ ชุดทั้งหมดจะล้มเหลวพร้อมข้อผิดพลาด 404 NOT_FOUND ซึ่งแตกต่างจาก batchDeleteที่สำเร็จสำหรับภูมิภาคที่ไม่มีอยู่

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

หากต้องการแก้ไขปัญหานี้ ให้ตรวจสอบว่าภูมิภาคทั้งหมดที่คุณพยายามอัปเดตมีอยู่ก่อน ส่งคำขอ

ก่อนหน้า
Create and update regions
ถัดไป
Manage Merchant Center email preferences