Memperbarui inventaris lokal untuk Vertex AI Search untuk commerce

LocalInventory adalah informasi inventaris yang terkait dengan tempat tertentu, yang diidentifikasi berdasarkan 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 berupa output. Setelan Product.local_inventories untuk Product CRUD API atau SetInventory tidak berpengaruh.

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 diperbarui oleh AddLocalInventories dan RemoveLocalInventories mencerminkan pemetaan dari setiap ID tempat ke daftar jenis pemenuhan yang didukungnya, sementara fulfillment_info diperbarui oleh AddFulfillmentPlaces dan RemoveFulfillmentPlaces mencerminkan pemetaan dari setiap jenis pemenuhan tertentu ke daftar ID tempat yang mendukung jenis tersebut. Namun, kedua jenis API tersebut mengubah informasi pemenuhan yang mendasarinya, dan efek 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. Serangkaian metode khusus disediakan untuk menangani update dalam jumlah besar yang khusus untuk inventaris lokal. Metode ini bersifat asinkron karena pengoptimalan hilir 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 pada inventaris lokal yang sudah 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: menggantikan LocalInventory.price_info.
  • attributes: menimpa semua LocalInventory.attributes. Atribut yang ada dan tidak disebutkan dalam isi permintaan akan dihapus.
  • attributes.PLACEHOLDER_NAME: hanya mengganti atribut kustom yang ditentukan. Jika nama atribut yang ada tidak diberikan dalam permintaan, atribut akan dihapus. Beberapa attributes.PLACEHOLDER_NAME dapat ditentukan, asalkan setiap nama atribut berbeda. Namun, AddLocalInventoriesRequest.add_mask tidak boleh menyertakan nilai attributes dan nilai attributes.PLACEHOLDER_NAME dalam permintaan yang sama.
  • fulfillment_types: menimpa semua jenis pemenuhan pesanan yang didukung. Jenis pemenuhan yang ada yang 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 store1 yang ada jika ada. store2 akan memiliki nilai atribut attr1 yang ditetapkan ke nilai teks store2_value. Atribut kustom yang ada lainnya di store1 dan store2 tidak akan diubah.

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

Karena AddLocalInventoriesRequest.allow_missing ditetapkan ke benar (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 menggantikan kolom yang ditentukan dari ID tempat ini. Untuk mengetahui informasi selengkapnya tentang cara mencegah pembaruan yang tidak valid dan menyimpan informasi inventaris lokal sebelum produk dibuat, lihat Perlindungan stempel waktu untuk pembaruan inventaris lokal dan Memuat informasi inventaris.

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 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 RemoveLocalInventoriesRequest.remove_time untuk mencegah pembaruan yang sudah usang menggantikan 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 melindungi dari update yang tidak berurutan, setiap kolom inventaris lokal dikaitkan dengan waktu update 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 menentukan waktu update 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 tepat setelah waktu pembaruan terbaru.

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

Dalam perlindungan stempel waktu, RemoveLocalInventoriesRequest dapat menghapus hanya kolom tertentu dari LocalInventory, bukan semuanya. Misalkan inventaris lokal dengan ID tempat "store1" memiliki price_info dengan waktu pembaruan terakhir yang tercatat ditetapkan ke waktu T1, dan memiliki satu-satunya atribut khusus yang ada dengan nama "attr1" dengan waktu pembaruan terakhir yang tercatat pada T2. Jika RemoveLocalInventoriesRequest.place_ids berisi "store1", dan memiliki remove_time yang ditetapkan ke T3 (dengan T1 < T3 < T2), maka store_1's price_info akan dihapus, sementara atribut attr1-nya akan tetap tidak berubah.

Memuat informasi inventaris terlebih dahulu

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