ภูมิภาค 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"
}
หากต้องการแก้ไขปัญหานี้ ให้ตรวจสอบว่าภูมิภาคทั้งหมดที่คุณพยายามอัปเดตมีอยู่ก่อน ส่งคำขอ