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"
}
]
}
レスポンス
リクエストが成功すると、空のレスポンス本文が返されます。これは、指定されたリージョンが削除された（または存在しなかった）ことを示します。
{}
制限事項
始める前に、次のルールに注意してください。
- アトミック オペレーション: バッチ リクエストはアトミックです。バッチ内の単一のオペレーションが失敗した場合（たとえば、リージョンの作成に失敗した場合）、バッチ全体が失敗し、変更は行われません。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"
}
]
}
「指定された ID のリージョンはすでに存在します」
すでに存在する regionId を使用してリージョンを作成しようとすると、エラーが発生します。
エラー メッセージは [regionId] Region with specified id already exists. です。
この問題を解決するには、すべての regionId 値がバッチ内で一意であり、既存のリージョンと競合しないことを確認します。
「Duplicate value found for field region.name or regionId found」
1 つのバッチ リクエスト内で同じ ID を持つ複数のリージョンを作成または更新しようとすると、エラーが発生します。
エラー メッセージは Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}. です。
この問題を解決するには、1 つのバッチ リクエスト内で、すべての regionId（batchCreate の場合）または region.name（batchUpdate の場合）の値が一意であることを確認します。
「アイテムが見つかりません」
batchUpdate を使用する場合、リクエストで指定されたリージョンが存在しないと、バッチ全体が 404 NOT_FOUND エラーで失敗します。これは、存在しないリージョンで成功する batchDelete とは異なります。
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
この問題を解決するには、リクエストを送信する前に、更新しようとしているすべてのリージョンが存在することを確認します。