Merchant API 지역은 accounts.products.regionalInventories 리소스와 관련된 타겟으로 사용할 수 있는 지리적 지역을 나타냅니다. 우편번호 또는 일부 국가의 경우 사전 정의된 지역 타겟을 사용하여 지역을 정의할 수 있습니다. 자세한 내용은 리전 설정을 참고하세요.
Merchant API는 리전을 관리하기 위한 일괄 엔드포인트를 제공하므로 단일 API 호출로 최대 100개의 리전을 만들고, 업데이트하고, 삭제할 수 있습니다. 이는 지역별 재고 및 가격 (RAAP)을 대규모로 관리하는 판매자에게 적합하며, 효율성을 개선하고 통합을 간소화합니다.
개요
Batch API를 사용하면 연결된 메서드로 다음 작업을 할 수 있습니다.
- 단일 요청으로 여러 리전 만들기:
regions:batchCreate - 한 번에 여러 지역 삭제:
regions:batchDelete - 여러 지역을 동시에 업데이트:
regions:batchUpdate
기본 요건
모든 일괄 요청에는 인증을 위해 관리자 사용자 역할이 필요합니다.
여러 리전 만들기
이 예에서는 BatchCreateRegions를 한 번 호출하여 우편번호로 정의된 지역과 지리적 타겟팅으로 정의된 지역 등 두 개의 새 지역을 만드는 방법을 보여줍니다.
요청
다음과 같이 요청 URL을 구성합니다.
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를 제공해야 합니다.
요청
다음과 같이 요청 URL을 구성합니다.
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
요청 본문에는 requests 목록이 포함됩니다. 각 객체는 업데이트할 region 데이터를 지정해야 합니다. region.name 필드에는 업데이트할 지역의 ID가 포함되어야 합니다(예: '98005'). 리소스를 accounts/{ACCOUNT_ID}/regions/name이 아닌 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: regionIdbatchUpdate의 경우[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 값이 배치 내에서 고유하고 기존 리전과 충돌하지 않는지 확인하세요.
'지역.이름 또는 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"
}
이 문제를 해결하려면 요청을 보내기 전에 업데이트하려는 모든 지역이 있는지 확인하세요.