リージョン バッチ処理を管理する

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: 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 値がバッチ内で一意であり、既存のリージョンと競合しないことを確認します。

「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"
}

この問題を解決するには、リクエストを送信する前に、更新しようとしているすべてのリージョンが存在することを確認します。

前へ
Create and update regions