Merchant API 區域代表地理區域，可用於與 accounts.products.regionalInventories 資源相關的目標。您可以將區域定義為郵遞區號的集合，或在部分國家/地區使用預先定義的地理區域目標。詳情請參閱「設定區域」一文。
Merchant API 提供批次端點來管理區域，讓您在單一 API 呼叫中建立、更新及刪除最多 100 個區域。這項功能非常適合大規模管理區域供應情形和價格的商家，可提高效率並簡化整合程序。
總覽
您可以使用 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」(已存在指定 ID 的區域)
如果您嘗試建立的區域已存在，就會發生錯誤。regionId
錯誤訊息為 [regionId] Region with specified id already exists.。
如要修正這個問題，請確認批次中的所有 regionId 值都是不重複，且不會與現有區域衝突。
「Duplicate value found for field region.name or regionId found」(找到區域名稱或區域 ID 的重複值)
如果嘗試在單一批次要求中，建立或更新多個具有相同 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"
}
如要修正這個問題，請先確認要更新的所有區域都存在，再傳送要求。