Merchant API のリージョンは、accounts.products.regionalInventories
リソースに関連するターゲットとして使用できる地理的リージョンを表します。リージョンは、郵便番号のコレクションとして定義することも、一部の国では事前定義された地域ターゲティングを使用して定義することもできます。詳細については、リージョン
を設定するをご覧ください。
Merchant API には、リージョンを管理するためのバッチ エンドポイントが用意されています。これにより、1 回の API 呼び出しで最大 100 個のリージョンを作成、更新、削除できます。これは、地域別の在庫状況と価格（RAAP）を大規模に管理する販売者にとって理想的であり、効率の向上と統合の簡素化につながります。
概要
Batch API を使用すると、関連するメソッドで次の操作を行うことができます。
- 1 回のリクエストで複数のリージョンを作成 する:
regions:batchCreate - 複数のリージョンを一度に削除 する:
regions:batchDelete - 複数のリージョンを同時に更新 する:
regions:batchUpdate
前提条件
すべてのバッチ リクエストで認証に ADMIN ユーザー ロールが必要です。
複数のリージョンを作成する
この例では、BatchCreateRegions の 1 回の呼び出しで、郵便番号で定義されたリージョンと地域ターゲティングで定義されたリージョンの 2 つの新しいリージョンを作成する方法を示します。
リクエスト
リクエスト 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 を使用して、既存の 2 つのリージョンの 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
}
]
}
複数のリージョンを削除する
1 回の呼び出しで複数のリージョンを削除できます。
リクエスト
この例では、BatchDeleteRegions を使用して、1 回の呼び出しで 2 つのリージョンを削除する方法を示します。
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
リクエストの本文には requests のリストが含まれます。各オブジェクトは、削除するリージョンの
name（"accounts/{ACCOUNT_ID}/regions/" なし）を指定します。
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
レスポンス
リクエストが成功すると、空のレスポンス本文が返されます。これは、指定されたリージョンが削除された（または存在しなかった）ことを示します。
{}
制限事項
始める前に、次のルールに注意してください。
- アトミック オペレーション: バッチ リクエストはアトミックです。バッチ内のいずれか 1 つのオペレーションが失敗した場合（たとえば、1 つのリージョンが作成できなかった場合）、バッチ全体が失敗し、変更は行われません。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: 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"
}
]
}
「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」（フィールド region.name または regionId に重複した値が見つかりました）
1 つのバッチ リクエスト内で同じ ID を持つ複数のリージョンを作成または更新しようとすると、エラーが発生します。
エラー メッセージは Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}. です。
この問題を解決するには、1 つのバッチ リクエスト内のすべての regionId（batchCreate の場合）または region.name（batchUpdate の場合）の値が一意であることを確認します。
「Item not found」（アイテムが見つかりません）
batchUpdate を使用する場合、リクエストで指定されたリージョンが存在しないと、バッチ全体が失敗し、404 NOT_FOUND エラーが発生します。これは、存在しないリージョンに対して成功する batchDelete とは異なります。
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
この問題を解決するには、リクエストを送信する前に、更新しようとしているすべてのリージョンが存在することを確認します。