Merchant API 地区表示一个地理区域，您可以将其用作与 accounts.products.regionalInventories 资源相关的目标。您可以将地区定义为邮政编码的集合，或者在某些国家/地区，使用预定义地理位置定位条件。如需了解详情，请参阅设置
地区。
Merchant API 提供用于管理地区的批量端点，让您可以在一次 API 调用中创建、更新和删除最多 100 个地区。这非常适合大规模管理地区性库存状况和价格 (RAAP) 的商家，可提高效率并简化集成。
概览
借助 Batch API，您可以使用关联的方法完成以下操作：
- 在单个请求中创建多个地区 ：
regions:batchCreate - 一次性删除多个地区 ：
regions:batchDelete - 同时更新多个地区 ：
regions:batchUpdate
前提条件
所有批量请求都需要 ADMIN 用户角色进行身份验证。
创建多个地区
此示例展示了如何在一次 BatchCreateRegions 调用中创建两个新地区，一个由邮政编码定义，另一个由地理位置定位条件定义。
请求
按如下方式构建请求网址：
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 才能更新目标区域。
请求
按如下方式构建请求网址：
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
请求正文包含 requests 列表。每个对象都必须指定要更新的 region 数据。region.name 字段必须包含要更新的区域的 ID，例如“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）使用相同的配额组。
常见错误和问题
下面列出了一些常见的陷阱及其解决方案。
“The number of requests in a batch is too large”
如果请求数组中的操作数超过 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”
如果您尝试在单个批量请求中创建或更新具有相同 ID 的多个地区，则会发生错误。
错误消息为 Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}.。
如需解决此问题，请验证所有 regionId（对于 batchCreate）或 region.name（对于 batchUpdate）值在单个批量请求中都是唯一的。
“Item not found”
使用 batchUpdate 时，如果请求中指定的任何区域不存在，则整个批次都会失败，并显示 404 NOT_FOUND 错误。这与 batchDelete 不同，后者对于不存在的地区会成功。
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
如需解决此问题，请在发送请求之前验证您尝试更新的所有地区是否存在。