소매업의 이름이 소매업용 Vertex AI Search로 변경됩니다. 새로운 브랜딩이 반영되도록 콘텐츠를 업데이트하는 중입니다.

Vertex AI Search for Retail을 위한 로컬 인벤토리 업데이트

LocalInventory는 place_id로 식별되는 특정 장소와 연결된 인벤토리 정보입니다. 예를 들어 특정 가격 책정을 사용할 수 있는 저장소 또는 리전에 대해 LocalInventory를 만들 수 있습니다. LocalInventory에는 다음과 같은 필드가 있습니다.

LocalInventory.price_info
LocalInventory.attributes
LocalInventory.fulfillment_types

기존 LocalInventory 항목은 Product.local_inventories을 통해 표시됩니다(이전 버전과의 호환성을 위해 Product.fulfillment_info를 통해 사용 가능한 fulfillment_types는 예외). 이 필드는 출력 전용입니다. Product CRUD API에 Product.local_inventories를 설정하거나 SetInventory를 설정하는 것은 효과가 없습니다.

각 (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) 쌍은 인벤토리 업데이트 문서에 언급된 동일한 (fulfillment_info.place_ids, fulfillment_info.type) 상을 가리킵니다. 아래에 설명된 AddLocalInventories 및 RemoveLocalInventories로 업데이트된 fulfillment_types은 각 장소 ID와 지원하는 fulfillment 유형 목록의 매핑을 반영하는 반면, AddFulfillmentPlaces 및 RemoveFulfillmentPlaces로 업데이트되는 fulfillment_info는 각 특정 fulfillment 유형과 각 유형을 지원하는 장소 ID 목록의 매핑을 반영합니다. 하지만 두 API 유형 모두 동일한 기본 fulfillment 정보를 수정하며, 두 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: 모든 지원되는 fulfillment 유형을 덮어씁니다. 요청 본문에 언급되지 않은 기존 fulfillment 유형은 삭제됩니다.

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"인 두 개의 오프라인 판매점 인벤토리를 추가하거나 업데이트합니다. store1이 존재하고 요청 전에 store2가 없는 경우 요청은 store1의 필드를 업데이트하고 지정된 필드 값으로 store2를 만듭니다.

이 AddLocalInventoriesRequest.add_mask는 이름이 "attr1"인 단일 맞춤 속성인 price_info와 fulfillment_types가 AddLocalInventoriesRequest.local_inventories에 제공된 값을 사용하여 업데이트하도록 지정합니다.

attributes는 맞춤설정 가능한 이름 및 값을 가진 장소와 연결된 속성입니다. store1의 LocalInventory는 요청에서 attr1의 값을 제공하지 않으므로 맞춤 속성 attr1는, 만일 존재하는 경우 store1의 기존 LocalInventory에서 삭제됩니다. store2에는 attr1 속성 값이 텍스트 값 store2_value로 설정됩니다. store1 및 store2의 다른 기존 맞춤 속성은 영향을 받지 않습니다.

fulfillment_types는 하나의 장소에서 Product에 대한 fulfillment 가용성 목록을 나타냅니다. 이것은 fulfillment_info.type와 동일한 값을 허용합니다. 이 AddLocalInventoriesRequest는 store1이 pickup-in-store 및 ship-to-store fulfillment 유형을 지원하고 store1이 custom-type-1을 지원하는 것으로 지정합니다. 요청에 언급되지 않은 이 업데이트 이전의 기존 fulfillment 유형은 삭제됩니다.

AddLocalInventoriesRequest.allow_missing은 true로 설정되므로 제품이 아직 존재하지 않더라도 최종적으로 제품이 생성될 때 업데이트된 오프라인 판매점 인벤토리 정보가 저장됩니다. 비활성 업데이트가 장소 ID의 지정된 필드를 재정의하지 못하도록 이 업데이트에는 AddLocalInventoriesRequest.add_time으로 타임스탬프가 지정됩니다. 제품을 만들기 전에 비활성 업데이트 방지 및 오프라인 판매점 인벤토리 정보 저장에 대한 자세한 내용은 오프라인 판매점 인벤토리 업데이트의 타임스탬프 보호 및 인벤토리 정보 사전 로드를 참조하세요.

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"인 오프라인 판매점 인벤토리를 삭제합니다. 비활성 업데이트가 장소 ID의 삭제를 재정의하지 못하도록 이 업데이트에는 RemoveLocalInventoriesRequest.remove_time으로 타임스탬프가 지정됩니다. 기존 오프라인 판매점 인벤토리가 없는 지정된 장소 ID의 경우 요청은 업데이트 시간을 remove_time에 기록합니다. 업데이트 타임스탬프에 대한 자세한 내용은 오프라인 판매점 인벤토리 업데이트를 위한 타임스탬프 보호를 참조하세요.

로컬 인벤토리 업데이트를 위한 타임스탬프 보호

잘못된 순서의 업데이트를 방지하기 위해 각 오프라인 판매점 인벤토리 필드는 최신 업데이트 시간과 연결됩니다.

각 (place_id, price_info), (place_id, attributes[...]), (place_id, fulfillment_types[...]) 쌍에 대해 최신 업데이트 시간이 기록됩니다.

AddLocalInventories, RemoveLocalInventories 메서드를 사용하면 호출자가 요청이 실행되는 시점에 대한 업데이트 시간을 지정할 수 있습니다. 이 업데이트 시간은 관련 인벤토리 필드에 기록된 최신 업데이트 시간과 비교되며, 업데이트 시간이 최신 업데이트 시간 이후인 경우에만 업데이트가 커밋됩니다.

예를 들어 장소 ID "store1"에 price_info가 있고 마지막 기록된 업데이트 시간이 T 시간으로 설정되었다고 가정해 보세요. 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가 존재하는 것처럼 처리됩니다. 오프라인 판매점 인벤토리 정보는 이 기간 내에 CreateProduct를 통해 해당 Product가 생성되지 않을 경우 최대 2일 동안 보관됩니다.