Memperbarui inventaris lokal untuk Vertex AI Search untuk retail

LocalInventory adalah informasi inventaris yang terkait dengan tempat tertentu, yang diidentifikasi oleh place_id-nya. Misalnya, LocalInventory dapat dibuat untuk toko atau wilayah tempat harga tertentu tersedia. LocalInventory memiliki kolom berikut:

  • LocalInventory.price_info
  • LocalInventory.attributes
  • LocalInventory.fulfillment_types

Entri LocalInventory yang ada dapat dilihat melalui Product.local_inventories (kecuali fulfillment_types yang, untuk kompatibilitas mundur, tersedia melalui Product.fulfillment_info). Kolom ini hanya output. Menetapkan Product.local_inventories untuk Product CRUD API atau SetInventory tidak mempunyai efek.

Setiap pasangan (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) mengarah ke pasangan (fulfillment_info.place_ids, fulfillment_info.type) yang sama yang disebutkan dalam Dokumentasi pembaruan inventaris. fulfillment_types yang diperbarui oleh AddLocalInventories dan RemoveLocalInventories yang dijelaskan di bawah ini mencerminkan pemetaan dari setiap ID tempat ke daftar jenis fulfillment yang didukung, sedangkan fulfillment_info yang diperbarui oleh AddFulfillmentPlaces dan RemoveFulfillmentPlaces mencerminkan pemetaan dari setiap jenis fulfillment tertentu ke daftar ID tempat yang mendukung jenis tersebut. Namun, kedua jenis API tersebut mengubah informasi fulfillment yang mendasarinya, dan efek dari kedua jenis API tersebut akan tercermin pada Product.fulfillment_info.

Metode pembaruan inventaris lokal

Perubahan pada informasi inventaris lokal produk dapat terjadi jauh lebih sering daripada perubahan pada informasi katalognya. Kumpulan metode khusus disediakan untuk menangani update khusus inventaris lokal dalam jumlah besar. Metode ini bersifat asinkron karena pengoptimalan downstream yang mendukung ratusan update serentak per produk, tanpa mengorbankan performa.

AddLocalInventories

AddLocalInventories dapat digunakan untuk membuat inventaris lokal di tempat baru (diwakili dengan place_id baru), atau memperbarui kolom yang ada di inventaris lokal yang ada. Kolom yang ditambahkan atau diperbarui pada daftar entri LocalInventory dalam isi permintaan dapat ditentukan melalui AddLocalInventoriesRequest.add_mask. Nilai add_mask yang valid adalah:

  • price_info: menimpa LocalInventory.price_info.
  • attributes: menimpa semua LocalInventory.attributes. Atribut yang ada dan tidak disebutkan dalam isi permintaan akan dihapus.
  • attributes.PLACEHOLDER_NAME: hanya menimpa atribut kustom yang ditentukan. Jika nama atribut yang ada tidak diberikan dalam permintaan, atribut akan dihapus. Beberapa attributes.PLACEHOLDER_NAME dapat ditentukan, selama setiap nama atribut berbeda. Namun, AddLocalInventoriesRequest.add_mask tidak dapat menyertakan nilai attributes dan nilai attributes.PLACEHOLDER_NAME dalam permintaan yang sama.
  • fulfillment_types: menimpa semua jenis fulfillment yang didukung. Jenis fulfillment yang ada dan tidak disebutkan dalam isi permintaan akan dihapus.

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
}
  

Contoh AddLocalInventoriesRequest ini menambahkan atau memperbarui dua inventaris lokal dengan ID tempat "store1" dan "store2" untuk produk yang ditentukan. Jika store1 ada, dan store2 tidak ada sebelum permintaan, permintaan akan memperbarui kolom store1, dan membuat store2 dengan nilai kolom yang diberikan.

AddLocalInventoriesRequest.add_mask ini menentukan bahwa price_info, satu atribut kustom dengan nama "attr1", dan fulfillment_types harus diperbarui menggunakan nilai yang diberikan di AddLocalInventoriesRequest.local_inventories.

attributes adalah atribut yang terkait dengan tempat dengan nama dan nilai yang dapat disesuaikan. Karena LocalInventory dari store1 tidak memberikan nilai attr1 dalam permintaan, atribut kustom attr1 akan dihapus dari LocalInventory dari store1 yang ada jika ada. store2 akan memiliki nilai atribut attr1 yang ditetapkan ke nilai teks store2_value. Atribut kustom lainnya yang ada di store1 dan store2 tidak akan diubah.

fulfillment_types mewakili daftar ketersediaan fulfillment untuk Product di satu tempat. Nilai ini sama dan menerima nilai yang sama dengan fulfillment_info.type. AddLocalInventoriesRequest ini menentukan bahwa store1 mendukung jenis fulfillment pickup-in-store dan ship-to-store, sedangkan store1 mendukung custom-type-1. Jenis fulfillment yang ada sebelum update ini yang tidak disebutkan dalam permintaan akan dihapus.

Karena AddLocalInventoriesRequest.allow_missing ditetapkan ke true, meskipun produk belum ada, informasi inventaris lokal yang diperbarui akan disimpan untuk saat produk akhirnya dibuat. Pembaruan diberi stempel waktu dengan AddLocalInventoriesRequest.add_time untuk mencegah pembaruan yang sudah tidak berlaku mengganti kolom yang ditentukan dari ID tempat ini. Untuk mengetahui informasi selengkapnya tentang cara mencegah pembaruan yang sudah tidak berlaku dan menyimpan informasi inventaris lokal sebelum produk dibuat, lihat Perlindungan stempel waktu untuk pembaruan inventaris lokal dan Memuat informasi inventaris secara otomatis.

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

Contoh AddLocalInventoriesRequest ini menambahkan atau memperbarui satu inventaris lokal dengan ID tempat "store3" untuk produk yang ditentukan. Karena add_mask-nya berisi "attributes", semua atribut kustom store3 yang ada akan dihapus, dan diganti dengan attr1 dan attr2 seperti yang ditentukan dalam permintaan. Perhatikan bahwa karena allow_missing tidak ditetapkan, produk yang ditentukan harus ada. Jika tidak, error NOT_FOUND akan ditampilkan.

RemoveLocalInventories

RemoveLocalInventories dapat digunakan untuk menghapus inventaris lokal yang ada di tempat dengan ID tempat tertentu.

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
}
  

Contoh RemoveLocalInventoriesRequest ini menghapus inventaris lokal untuk tempat dengan ID tempat "store1" dan "store2" untuk produk yang ditentukan. Pembaruan diberi stempel waktu dengan RemoveLocalInventoriesRequest.remove_time untuk mencegah update yang sudah tidak berlaku mengganti penghapusan ID tempat ini. Untuk ID tempat yang ditentukan tanpa inventaris lokal yang ada, permintaan juga mencatat waktu pembaruannya ke remove_time. Untuk mengetahui informasi selengkapnya tentang stempel waktu update, lihat Perlindungan stempel waktu untuk update inventaris lokal

Perlindungan stempel waktu untuk pembaruan inventaris lokal

Untuk mencegah pembaruan yang tidak berurutan, setiap kolom inventaris lokal dikaitkan dengan waktu pembaruan terbaru.

Waktu update terbaru dicatat untuk setiap pasangan (place_id, price_info), (place_id, attributes[...]), dan (place_id, fulfillment_types[...]).

Metode AddLocalInventories dan RemoveLocalInventories memungkinkan pemanggil untuk menentukan waktu pembaruan saat permintaan dikeluarkan. Waktu pembaruan ini dibandingkan dengan waktu pembaruan terbaru yang dicatat untuk kolom inventaris yang relevan, dan pembaruan dilakukan jika dan hanya jika waktu pembaruan benar-benar setelah waktu pembaruan terbaru.

Misalnya, ID tempat "store1" memiliki price_info dengan waktu pembaruan terakhir yang dicatat disetel ke waktu T. Jika RemoveLocalInventoriesRequest.place_ids berisi "store1", permintaan akan menghapus price_info dari "store1" hanya jika RemoveLocalInventoriesRequest.remove_time lebih lambat dari waktu T. Hal yang sama berlaku untuk RemoveLocalInventoriesRequest.

Berdasarkan perlindungan stempel waktu, mungkin saja RemoveLocalInventoriesRequest hanya menghapus kolom tertentu dari LocalInventory, bukan semuanya. Misalkan inventaris lokal dengan ID tempat "store1" memiliki price_info dengan waktu pembaruan terakhir yang dicatat ditetapkan ke waktu T1, dan memiliki satu-satunya atribut kustom yang ada dengan nama "attr1" dengan waktu pembaruan terakhir yang dicatat di T2. Jika RemoveLocalInventoriesRequest.place_ids berisi "store1", dan remove_time ditetapkan ke T3 (dengan T1 < T3 < T2), price_info store_1 akan dihapus, sedangkan atributnya attr1 akan tidak tersentuh.

Melakukan pramuat informasi inventaris

Setiap metode pembaruan inventaris lokal memungkinkan pemanggil menetapkan allow_missing dalam permintaan. Jika allow_missing ditetapkan ke benar, update inventaris lokal ke Product yang tidak ada akan diproses seolah-olah Product ada sesuai dengan spesifikasi metode. Informasi inventaris lokal akan disimpan maksimal selama dua hari jika Product yang sesuai tidak dibuat melalui CreateProduct dalam jangka waktu ini.