「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

小売業向け Vertex AI Search のローカル在庫を更新する

LocalInventory は、place_id で識別される特定の場所に関連付けられた在庫情報です。たとえば、特定の価格が設定されている店舗や地域に LocalInventory を作成できます。LocalInventory には次のフィールドがあります。

LocalInventory.price_info
LocalInventory.attributes
LocalInventory.fulfillment_types

既存の LocalInventory エントリは Product.local_inventories に表示されます（ただし、下位互換性の fulfillment_types は Product.fulfillment_info を介して使用可能です）。このフィールドは出力専用です。Product CRUD API または SetInventory に Product.local_inventories を設定しても効果はありません。

各 (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) ペアは、インベントリの更新に関するドキュメントで説明されているのと同じ (fulfillment_info.place_ids, fulfillment_info.type) ペアを指します。以下に説明する AddLocalInventories と RemoveLocalInventories によって更新される fulfillment_types には、各場所 ID からサポートするフルフィルメントタイプのリストへのマッピングが反映され、AddFulfillmentPlaces と RemoveFulfillmentPlaces によって更新される fulfillment_info には、それぞれの特定のフルフィルメントタイプから各タイプをサポートする場所 ID のリストへのマッピングが反映されます。ただし、どちらのタイプの API でも同じ基盤となるフルフィルメント情報が変更され、両方のタイプの API の効果は Product.fulfillment_info に反映されます。

ローカル在庫の更新メソッド

商品のローカル在庫情報の変更は、カタログ情報の変更よりも頻繁に発生する可能性があります。ローカル在庫固有の更新を大量に処理するための特別な一連のメソッドが提供されます。これらのメソッドは、パフォーマンスを犠牲にすることなく、商品ごとに数百の同時更新をサポートするダウンストリームの最適化のために、非同期になっています。

`AddLocalInventories`

AddLocalInventories を使用すると、新しい場所でローカル在庫を作成したり（新しい place_id で表現）、既存のローカル在庫の既存のフィールドを更新したりできます。リクエスト本文の LocalInventory エントリのリストに追加または更新されるフィールドは、AddLocalInventoriesRequest.add_mask で指定できます。指定できる add_mask 値は次のとおりです。

price_info: LocalInventory.price_info を上書きします。
attributes: すべての LocalInventory.attributes を上書きします。リクエスト本文に記載されていない既存の属性は削除されます。
attributes.PLACEHOLDER_NAME: 指定されたカスタム属性のみを上書きします。リクエストで既存の属性名が指定されていない場合、その属性は削除されます。属性名がそれぞれ異なる限り、複数の attributes.PLACEHOLDER_NAME を指定できます。ただし、AddLocalInventoriesRequest.add_mask では、同じリクエストに attributes 値と attributes.PLACEHOLDER_NAME 値の両方を含めることはできません。
fulfillment_types: サポートされているすべてのフルフィルメントタイプを上書きします。リクエスト本文に記載されていない既存のフルフィルメントタイプは削除されます。

.proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store1"
    price_info: {
      currency_code: "USD"
      price: 100
      original_price: 110
      cost: 95
    }
    fulfillment_types: "pickup-in-store"
    fulfillment_types: "ship-to-store"
  }
  local_inventories: {
    place_id: "store2"
    price_info: {
      currency_code: "USD"
      price: 200
      original_price: 210
      cost: 195
    }
    attributes: {
      key: "attr1",
      value: {
        text: "store2_value"
      }
    }
    fulfillment_types: "custom-type-1"
  }
  add_mask: {
    paths: "price_info"
    paths: "attributes.attr1"
    paths: "fulfillment_types"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}

このサンプル AddLocalInventoriesRequest では、指定した商品の場所 ID "store1" と "store2" で 2 つのローカル在庫を追加または更新します。リクエストの前に store1 が存在し、store2 が存在しない場合、リクエストは store1 のフィールドを更新し、指定されたフィールド値を持つ store2 を作成します。

この AddLocalInventoriesRequest.add_mask は、その price_info、名前が "attr1" の単一のカスタム属性を指定し、fulfillment_types は AddLocalInventoriesRequest.local_inventories で指定された値を使用して更新する必要があります。

attributes は、カスタマイズ可能な名前と値で場所に関連付けられる属性です。store1 の LocalInventory ではリクエストで attr1 の値が提供されないため、カスタム属性 attr1 は既存の store1 の LocalInventory から削除されます（存在する場合）。store2 の属性 attr1 の値は、テキスト値 store2_value に設定されます。store1 と store2 の他の既存のカスタム属性は変更されません。

fulfillment_types は、ある場所での Product のフルフィルメントの在庫状況のリストを表します。これは fulfillment_info.type と同じで、同じ値を受け入れます。AddLocalInventoriesRequest は、store1 が pickup-in-store と ship-to-store のフルフィルメントタイプをサポートし、store1 が custom-type-1 をサポートすることを指定します。更新の前に存在し、リクエストに記載されていないフルフィルメントタイプは削除されます。

AddLocalInventoriesRequest.allow_missing は true に設定されているため、商品がまだ存在しない場合でも、最終的に商品が作成されたときに更新されたローカル在庫情報が保存されます。更新には、AddLocalInventoriesRequest.add_time というタイムスタンプが付けられており、これらの場所 ID の指定されたフィールドが古い更新によってオーバーライドされないようにしています。商品の作成前に、古い更新を防ぎ、ローカル在庫情報を保存する方法の詳細については、ローカル在庫の更新のタイムスタンプの保護および在庫情報のプリロードをご覧ください。

.proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store3"
    attributes: {
      key: "attr1",
      value: {
        text: "attr1_value"
      }
    }
    attributes: {
      key: "attr2",
      value: {
        numbers: 123
      }
    }
  }
  add_mask: {
    paths: "attributes"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
}

このサンプル AddLocalInventoriesRequest では、指定した商品の場所 ID "store3" を持つ単一のローカル在庫を追加または更新します。この add_mask には "attributes" が含まれているため、store3 の既存のカスタム属性がすべて削除され、リクエストで指定されている attr1 と attr2 に置き換えられます。 allow_missing が設定されていないため、指定した商品が存在している必要があります。存在していない場合は、NOT_FOUND エラーがスローされます。

`RemoveLocalInventories`

RemoveLocalInventories を使用すると、特定の場所 ID を持つ場所から既存のローカル在庫を削除できます。

.proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  place_ids: "store1"
  place_ids: "store2"
  remove_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}

このサンプル RemoveLocalInventoriesRequest は、指定された商品の場所 ID "store1" と "store2" の場所のローカル在庫を削除します。更新には、RemoveLocalInventoriesRequest.remove_time というタイムスタンプが付けられており、これらの場所 ID の削除が古い更新によってオーバーライドされないようにしています。既存のローカル在庫がない指定した場所 ID の場合、リクエストで更新時間も remove_time に記録されます。更新タイムスタンプの詳細については、ローカル在庫の更新のタイムスタンプの保護をご覧ください。

ローカル在庫の更新のタイムスタンプの保護

順不同な更新から保護するために、各ローカル在庫フィールドが最新の更新時間が関連付けられます。

最新の更新時間は、(place_id, price_info)、(place_id, attributes[...])、(place_id, fulfillment_types[...]) の各ペアに対して記録されます。

AddLocalInventories メソッド、RemoveLocalInventories メソッドを使用すると、リクエストの発行時に、呼び出し元が更新時刻を指定できます。この更新時刻が、関連する広告枠フィールドに対して記録された最新の更新時刻と比較され、更新時刻が直近の更新時刻より後の場合に限り、更新がコミットされます。

たとえば、場所 ID "store1" に、最後に記録された更新時刻が T に設定された price_info があるとします。RemoveLocalInventoriesRequest.place_ids に "store1" が含まれている場合、RemoveLocalInventoriesRequest.remove_time が T より後の場合にのみ、リクエストで "store1" から price_info が削除されます。RemoveLocalInventoriesRequest についても同様です。

タイムスタンプの保護下では、RemoveLocalInventoriesRequest が LocalInventory のすべてではなく、特定のフィールドのみを削除する可能性があります。場所 ID が "store1" のローカル在庫で、最後に記録された更新時刻が T1 に設定された price_info があり、最後に記録された更新時刻が T2 の "attr1" という名前の既存のカスタム属性のみがあるとします。RemoveLocalInventoriesRequest.place_ids に "store1" が含まれ、remove_time が T3（T1 < T3 < T2）に設定されている場合、store_1 の price_info は削除されますが、その属性 attr1 は変更されません。

広告枠情報のプリロード

各ローカル在庫更新メソッドでは、呼び出し元がリクエストで allow_missing を設定できます。allow_missing が true に設定されている場合、存在しない Product へのローカル在庫更新は、メソッドの仕様に従って Product が存在しているかのように処理されます。この期間内に対応する Product が CreateProduct を介して作成しない場合、ローカル在庫情報は最大 2 日間保持されます。