Memperbarui inventaris untuk Vertex AI Search untuk retail

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

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

Tutorial menetapkan 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 mencapai 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 info terbaru tentang tempat produk tersedia dan pesanan dapat dipenuhi. Misalnya, 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

Tutorial penghapusan fulfillment

Sebaiknya gunakan metode RemoveLocalInventories, bukan RemoveFulfillmentPlaces. RmoveLocalInventories mencapai 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 jika produk tidak tersedia dan pesanan tidak dapat dipenuhi. Dengan cara ini, penelusuran dapat menampilkan info terbaru jika produk tidak tersedia dan pesanan tidak dapat dipenuhi. Misalnya, pembeli mencari jeans biru di toko. Jika stok jeans di toko ini habis, pembeli akan melihatnya 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 mungkin terjadi jauh lebih sering daripada perubahan pada informasi katalognya. Dengan demikian, serangkaian metode khusus disediakan untuk menangani pembaruan khusus inventaris dalam jumlah besar. Metode ini adalah 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 inkremental. Metode API yang lebih baru memberikan kontrol yang lebih terperinci 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 mengeluarkan pembaruan yang menjelaskan perubahan ini, bukan menggunakan metode UpdateProduct untuk menentukan ulang informasi fulfillment seluruh produk.

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

Java

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

Untuk melakukan autentikasi ke Vertex AI Search untuk retail, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 menempatkan ID "store0" dan "store1" untuk produk yang ditentukan. Karena AddFulfillmentPlacesRequest.allow_missing ditetapkan ke true, meskipun produk belum ada, informasi inventaris yang diperbarui akan disimpan untuk saat produk akhirnya dibuat. Pembaruan diberi stempel waktu dengan AddFulfillmentPlacesRequest.add_time untuk mencegah pembaruan yang tidak berlaku mengganti status fulfillment ID tempat ini. Fitur-fitur ini dibahas secara lebih mendetail di bagian berikut.

Perilakunya identik untuk RemoveFulfillmentPlacesRequest dan skemanya sangat mirip.

Saat diperbarui oleh AddLocalInventories dan RemoveLocalInventories, fulfillment_types akan mencerminkan pemetaan dari setiap ID tempat ke daftar jenis fulfillment yang didukungnya. Saat fulfillment_info diperbarui oleh AddFulfillmentPlaces dan RemoveFulfillmentPlaces, hal ini mencerminkan pemetaan dari setiap jenis fulfillment tertentu ke daftar ID tempat yang mendukung setiap jenis. Kedua jenis API mengubah informasi fulfillment yang mendasarinya, dan efek dari kedua jenis API tersebut tercermin oleh Product.fulfillment_info.

Update non-inkremental

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

Java

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

Untuk melakukan autentikasi ke Vertex AI Search untuk retail, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 untuk setiap jenis fulfillment, bukan spesifikasi inkremental. Pembaruan 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 sebagian jenis fulfillment tanpa mengubah jenis lainnya.

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

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

Perlindungan stempel waktu untuk pembaruan inventaris

Ada beberapa jalur berbeda untuk memperbarui kolom inventaris produk, dan untuk melindungi dari pembaruan 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 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" mengaktifkan jenis fulfillment "pickup-in- store", dengan waktu pembaruan terakhir yang dicatat ditetapkan 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 lambat dari waktu T. Hal yang sama berlaku untuk AddFulfillmentPlacesRequests.

SetInventory beroperasi dengan cara yang serupa 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 akan dikonversi secara implisit menjadi AddFulfillmentPlacesRequest dan RemoveFulfillmentPlacesRequest untuk setiap jenis fulfillment yang ditentukan. Artinya, jika tempat yang ada "store1" dengan fulfillment "pickup-in-store" memiliki waktu pembaruan terakhir T yang lebih baru dari SetInventoryRequest.set_time, penambahan/penghapusan implisit pada "store1" dan "pickup-in-store" tidak akan diterapkan.

Memuat informasi inventaris secara otomatis

Setiap metode pembaruan inventaris memungkinkan pemanggil menetapkan allow_missing dalam permintaan. Jika allow_missing ditetapkan ke true, pembaruan inventaris ke Product yang tidak ada akan diproses seolah-olah Product ada sesuai dengan spesifikasi metode. Informasi inventaris akan disimpan selama maksimal 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 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. Jika memungkinkan, sebaiknya gunakan metode pembaruan inventaris yang disebutkan di atas.

CreateProduct

Saat CreateProduct dipanggil dengan menetapkan kolom inventaris, nilai yang diberikan di CreateProductRequest.product akan menggantikan nilai yang dimuat sebelumnya untuk kolom tersebut. Jika tidak ada kolom inventaris yang ditetapkan, informasi inventaris yang sudah ada akan otomatis digunakan.

Selain itu, waktu pembaruan terbaru untuk kolom inventaris yang diganti akan direset ke waktu panggilan metode.

CreateProduct dengan inventaris yang dipramuat

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 informasi inventaris yang dimuat sebelumnya akan otomatis digunakan jika diperbarui menggunakan metode pembaruan inventaris. Hal ini dapat berguna saat pembaruan inventaris dipisahkan dari pembaruan katalog dan Anda ingin Product yang baru dibuat disinkronkan dengan informasi inventaris yang sudah ada.

CreateProduct dengan inventaris vulgar

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 menggantikan nilai yang sudah ada, 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 lebih memilih untuk menetapkan inventaris secara eksplisit pada waktu pembuatan Product untuk menyinkronkan sepenuhnya katalog dan inventaris.

UpdateProduct

Saat UpdateProduct dipanggil dan mask kolom UpdateProductRequest.update_mask berisi kolom inventaris, nilai yang diberikan di UpdateProductRequest.product akan menggantikan nilai yang dimuat sebelumnya untuk kolom tersebut.

Selain itu, waktu pembaruan terbaru 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, kecuali pembaruan dijamin akan diterapkan terlepas dari waktu pembaruan terbaru setiap kolom inventaris.

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

Meskipun Anda dapat memuat ulang informasi inventaris menggunakan UpdateProduct dengan menetapkan UpdateProductRequest.allow_missing ke true untuk melakukan pembaruan dan penyisipan Product, metode ini memerlukan penetapan kolom katalog tertentu seperti UpdateProductRequest.product.title. Oleh karena itu, sebaiknya gunakan metode pembaruan inventaris untuk memuat kasus penggunaan secara otomatis.

DeleteProduct

Saat DeleteProduct dipanggil, semua informasi inventaris yang ada untuk produk yang ditentukan di DeleteProductRequest.name akan dihapus, termasuk semua data waktu pembaruan terbaru untuk setiap kolom inventaris.