Memperbarui inventaris Vertex AI Search untuk retail

Meskipun metode buat, baca, perbarui, dan hapus (CRUD) Product digunakan untuk mengubah atribut Product secara luas, ada kumpulan metode Product yang dapat digunakan untuk memperbarui kolom khusus inventaris dengan berbagai tingkat perincian. Kolom Product berikut dianggap sebagai kolom inventaris:

  • Product.price_info
  • Product.availability
  • Product.available_quantity
  • Product.fulfillment_info

Tutorial menyetel inventaris

Tutorial ini menunjukkan cara mendorong pembaruan inventaris menggunakan metode SetInventory, bukan memperbarui seluruh produk.

Untuk mengikuti panduan langkah demi langkah tugas ini langsung di Cloud Shell Editor, klik Pandu saya:

Pandu saya

Menambahkan tutorial fulfillment

Sebaiknya gunakan metode AddLocalInventories, bukan AddFulfillmentPlaces. AddLocalInventories memberikan hasil yang sama, tetapi memberikan kontrol yang lebih terperinci atas penyerapan data inventaris lokal. Untuk informasi selengkapnya, lihat dokumentasi AddLocalInventories.

Tutorial ini menunjukkan cara memperbarui informasi fulfillment produk menggunakan metode AddFulfillmentPlaces. Dengan cara ini, penelusuran dapat menampilkan pembaruan di mana produk tersedia dan pesanan dapat dipenuhi. Misalnya, seorang pembeli mencari jeans biru di toko tetapi stoknya habis. Saat jeans tersedia lagi di toko ini atau toko lain, pembeli akan melihat pembaruan dan dapat melanjutkan pesanannya.

Untuk mengikuti panduan langkah demi langkah tugas ini langsung di Cloud Shell Editor, klik Pandu saya:

Pandu saya

Menghapus tutorial fulfillment

Sebaiknya gunakan metode RemoveLocalInventories, bukan RemoveFulfillmentPlaces. RmoveLocalInventories memberikan hasil yang sama, tetapi memberikan kontrol yang lebih terperinci atas penyerapan data inventaris lokal. Untuk informasi selengkapnya, lihat dokumentasi RemoveLocalInventories.

Tutorial ini menunjukkan cara memperbarui informasi fulfillment produk menggunakan metode RemoveFulfillmentPlaces. Dengan cara ini, Vertex AI Search untuk retail dapat menampilkan pembaruan saat produk tidak tersedia dan pesanan tidak dapat dipenuhi. Dengan cara ini, penelusuran dapat menampilkan pembaruan saat produk tidak tersedia dan pesanan tidak dapat dipenuhi. Misalnya, seorang pembeli sedang mencari jeans biru di toko. Jika stok jeans habis di toko ini, pembeli akan melihat hal ini dan tidak dapat melanjutkan pesanan.

Untuk mengikuti panduan langkah demi langkah tugas ini langsung di Cloud Shell Editor, klik Pandu saya:

Pandu saya

Metode pembaruan inventaris

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

Update inkremental

Perhatikan bahwa sebaiknya ikuti panduan pembaruan inventaris lokal untuk menerbitkan pembaruan inventaris tambahan. Metode API yang lebih baru memberikan kontrol yang lebih mendetail untuk atribut inventaris per tempat.

fulfillment_info sering digunakan untuk mengenkode ketersediaan fulfillment tingkat tempat untuk Product. Dalam beberapa kasus, ketersediaan fulfillment untuk beberapa tempat tertentu dapat berubah, dan Anda dapat memutuskan untuk melakukan pembaruan yang menjelaskan perubahan ini, bukan menggunakan metode UpdateProduct untuk menentukan ulang informasi fulfillment seluruh produk.

Dalam kasus seperti itu, metode AddFulfillmentPlaces dan RemoveFulfillmentPlaces dapat digunakan untuk secara bertahap memperbarui perubahan fulfillment produk berdasarkan ID tempat yang ditambahkan atau dihapus untuk jenis fulfillment tertentu.

Java

Guna mempelajari cara menginstal dan menggunakan library klien bagi Vertex AI Search untuk retail, lihat Vertex AI Search untuk library klien retail. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Vertex AI Search untuk Java API retail.

Untuk melakukan autentikasi ke Vertex AI Search untuk retail, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }

Contoh AddFulfillmentPlacesRequest ini menambahkan jenis fulfillment "pickup-in-store" untuk ID tempat "store0" dan "store1" untuk produk yang ditentukan. Karena AddFulfillmentPlacesRequest.allow_missing ditetapkan ke true, meskipun produk belum ada, informasi inventaris yang diperbarui akan disimpan saat produk akhirnya dibuat. Update diberi stempel waktu dengan AddFulfillmentPlacesRequest.add_time untuk mencegah update yang tidak berlaku agar tidak mengganti status fulfillment ID tempat ini. Fitur-fitur ini dibahas secara lebih mendetail di bagian berikut.

Perilaku untuk RemoveFulfillmentPlacesRequest identik dan skemanya sangat mirip.

Saat fulfillment_types diperbarui oleh AddLocalInventories dan RemoveLocalInventories, pembaruan ini mencerminkan pemetaan dari setiap ID tempat ke daftar jenis fulfillment yang didukungnya. Saat fulfillment_info diperbarui oleh AddFulfillmentPlaces dan RemoveFulfillmentPlaces, pembaruan ini mencerminkan pemetaan dari setiap jenis fulfillment tertentu ke daftar ID tempat yang mendukung setiap jenis. Kedua jenis API ini mengubah informasi fulfillment dasar yang sama, dan efek kedua jenis API dicerminkan oleh Product.fulfillment_info.

Update non-inkremental

price_info, availability, dan available_quantity tidak dapat diperbarui secara bertahap karena mewakili inventaris tingkat produk, bukan informasi tingkat tempat. Selain itu, sebaiknya lakukan update non-inkremental pada fulfillment_info, bukan hanya perubahan inkremental. Dalam kasus tersebut, metode SetInventory direkomendasikan.

Java

Guna mempelajari cara menginstal dan menggunakan library klien bagi Vertex AI Search untuk retail, lihat Vertex AI Search untuk library klien retail. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Vertex AI Search untuk Java API retail.

Untuk melakukan autentikasi ke Vertex AI Search untuk retail, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {
      paths: "availability"
      paths: "fulfillment_info"
    }
    allow_missing: true
  }

Dalam permintaan khusus ini, kolom SetInventoryRequest.product.fulfillment_info adalah deskripsi lengkap dari setiap ID tempat yang memenuhi syarat dari setiap jenis pemenuhan pesanan, bukan spesifikasi tambahan. Perubahan pada "same-day-delivery" menunjukkan bahwa tidak ada ID tempat yang memenuhi syarat untuk jenis fulfillment ini untuk produk ini. Semua jenis fulfillment lainnya tidak diperbarui dalam permintaan ini. Dengan demikian, metode ini dapat digunakan untuk mengganti ID tempat hanya untuk subset jenis fulfillment tanpa mengubah jenis lainnya.

Secara default,SetInventory akan memperbarui semua kolom inventaris jika SetInventory.set_mask tidak disetel atau kosong. Jika mask tidak kosong atau jika kolom inventaris tidak tercantum secara eksplisit dalam SetInventoryRequest.set_mask, nilai apa pun yang ditentukan untuk kolom inventaris tersebut akan diabaikan dalam permintaan update.

Seperti halnya update inkremental, kolom SetInventoryRequest.set_time dapat digunakan untuk menetapkan waktu update yang akan berbeda dengan waktu update terakhir yang dicatat dari semua kolom inventaris yang diperbarui.

Perlindungan stempel waktu untuk pembaruan inventaris

Ada beberapa jalur yang berbeda untuk memperbarui kolom inventaris produk, dan untuk melindungi dari update yang tidak berurutan, setiap kolom inventaris dikaitkan dengan waktu pembaruan terbaru.

Waktu update terbaru dicatat untuk price_info, availability, available_quantity, dan setiap pasangan (fulfillment_info.place_ids, fulfillment_info.type).

Metode AddFulfillmentPlaces, RemoveFulfillmentPlaces, dan SetInventory memungkinkan pemanggil menentukan waktu update saat permintaan dikeluarkan. Waktu update ini dibandingkan dengan waktu update terbaru yang dicatat untuk kolom inventaris yang relevan, dan update akan dilakukan jika dan hanya jika waktu update benar-benar setelah waktu update terbaru.

Misalnya, ID tempat "store1" memiliki jenis fulfillment "pickup-in- store" aktif, dengan waktu pembaruan yang terakhir dicatat disetel ke waktu T. Jika RemoveFulfillmentPlacesRequest.type = "pickup-in-store" dan RemoveFulfillmentPlacesRequest.place_ids berisi "store1", permintaan akan menghapus "pickup-in-store" dari "store1" jika dan hanya jika RemoveFulfillmentPlacesRequest.remove_time lebih dari waktu T. Hal yang sama berlaku untuk AddFulfillmentPlacesRequests.

SetInventory beroperasi dengan cara yang sama untuk mengupdate price_info, availability, dan available_quantity. Saat memperbarui fulfillment_info, SetInventoryRequest secara implisit meminta untuk menambahkan semua ID tempat yang ditentukan untuk jenis fulfillment tertentu dan menghapus semua ID tempat yang ada yang tidak ditentukan.

Dengan demikian, saat SetInventoryRequest diproses, update fulfillment_info secara implisit akan dikonversi menjadi AddFulfillmentPlacesRequest dan RemoveFulfillmentPlacesRequest untuk setiap jenis fulfillment yang ditentukan. Hal ini berarti bahwa jika setiap tempat yang ada "store1" dengan fulfillment "pickup-in-store" memiliki waktu update terakhir T yang lebih baru dari SetInventoryRequest.set_time, maka penambahan/penghapusan implisit pada "store1" dan "pickup-in-store" tidak akan diterapkan.

Pramuat informasi inventaris

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

Java

public static SetInventoryResponse setInventory(Product productToUpdate)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Kapan menggunakan metode Product

Meskipun Anda dapat memperbarui kolom inventaris dengan metode CRUD Produk, pemanggil harus secara eksplisit mengetahui efeknya terhadap informasi inventaris yang ada atau yang sudah ada sebelumnya.

Ini adalah metode sinkron, yang berarti pengoptimalan downstream yang digunakan untuk metode inventaris tidak berlaku, dan mungkin akan mahal jika mengandalkan metode ini untuk pembaruan inventaris yang sering dilakukan. Jika memungkinkan, pilih untuk menggunakan metode pembaruan inventaris yang disebutkan di atas.

CreateProduct

Saat CreateProduct dipanggil dengan kolom inventaris apa pun yang ditetapkan, nilai yang diberikan dalam CreateProductRequest.product akan menggantikan nilai yang telah dimuat sebelumnya untuk masing-masing kolom tersebut. Jika tidak ada kolom inventaris yang ditetapkan, informasi inventaris yang sudah ada sebelumnya akan digunakan secara otomatis.

Selain itu, waktu update terakhir untuk kolom inventaris yang diganti akan direset ke waktu panggilan metode.

CreateProduct dengan inventaris bawaan

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
  }
}

Dalam contoh ini, produk yang dibuat tidak memiliki kolom inventaris yang ditetapkan, yang berarti setiap informasi inventaris bawaan akan otomatis digunakan jika diperbarui menggunakan metode pembaruan inventaris. Hal ini dapat membantu saat pembaruan inventaris dipisahkan dari pembaruan katalog dan Anda ingin menyinkronkan Product yang baru dibuat dengan informasi inventaris yang sudah ada sebelumnya.

CreateProduct dengan inventaris eksplisit

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
    availability: OUT_OF_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
}

Dalam contoh ini, Product dibuat dengan kolom inventaris yang ditetapkan secara eksplisit. Kolom ini akan mengganti nilai yang sudah ada, dan mengabaikan waktu update terbaru untuk kolom yang sesuai. Dengan demikian, Product yang baru dibuat dijamin memiliki ketersediaan yang ditetapkan ke OUT_OF_STOCK, dan tidak ada ID tempat yang akan mendukung jenis fulfillment "pickup-in-store" dan "same-day-delivery".

CreateProduct dengan informasi inventaris dapat membantu jika Anda tidak yakin apakah semua informasi inventaris yang dimuat sebelumnya akurat, dan memilih untuk menetapkan inventaris secara eksplisit pada waktu pembuatan Product untuk sepenuhnya menyinkronkan katalog dan inventaris.

UpdateProduct

Saat UpdateProduct dipanggil dan mask kolom UpdateProductRequest.update_mask berisi kolom inventaris apa pun, nilai yang diberikan di UpdateProductRequest.product akan menggantikan nilai bawaan untuk kolom masing-masing.

Selain itu, waktu update terakhir untuk kolom inventaris yang diganti akan direset ke waktu panggilan metode.

PROTO

{
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    availability: IN_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
      place_ids: "store0"
      place_ids: "store1"
      place_ids: "store2"
      place_ids: "store3"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
  update_mask: {
    paths: "availability"
    paths: "fulfillment_info"
  }
}

Contoh ini sangat mirip dengan contoh SetInventory, tetapi update dijamin akan diterapkan terlepas dari waktu update terbaru untuk setiap kolom inventaris.

UpdateProduct untuk inventaris dapat berguna saat sinkronisasi penuh pada informasi inventaris diperlukan sambil mengabaikan perlindungan stempel waktu.

Meskipun informasi inventaris dapat dipramuat menggunakan UpdateProduct dengan menetapkan UpdateProductRequest.allow_missing ke true untuk melakukan pembaruan dan penyisipan Product, metode ini memerlukan penetapan kolom katalog khusus seperti UpdateProductRequest.product.title. Dengan demikian, sebaiknya gunakan metode update inventaris untuk melakukan pramuat kasus penggunaan.

DeleteProduct

Saat DeleteProduct dipanggil, semua informasi inventaris yang ada untuk produk yang ditentukan dalam DeleteProductRequest.name akan dihapus, termasuk semua catatan waktu pembaruan terakhir untuk setiap kolom inventaris.