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) 相同的配额组。
常见错误和问题
下面列出了一些常见误区及其解决方案。
“批次中的请求数量过大”
如果请求数组中的操作数超过 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"
}
]
}
“具有指定 ID 的地区已存在”
如果您尝试创建具有已存在的 regionId 的区域，则会发生错误。
错误消息为 [regionId] Region with specified id already exists.。
如需解决此问题，请验证批次中的所有 regionId 值是否都是唯一的，并且不与现有区域冲突。
“发现字段 region.name 或 regionId 存在重复值”
如果您尝试在单个批量请求中创建或更新具有相同 ID 的多个区域，则会发生错误。
错误消息为 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"
}
如需解决此问题，请在发送请求之前验证您尝试更新的所有区域是否存在。