Memperbarui inventaris untuk Vertex AI Search untuk commerce

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

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

Tutorial setel inventaris

Tutorial ini menunjukkan cara mengirimkan 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 pemenuhan

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 pemenuhan produk menggunakan metode AddFulfillmentPlaces. Dengan cara ini, penelusuran dapat menampilkan pembaruan tempat produk tersedia dan pesanan dapat dipenuhi. Misalnya, seorang pembeli mencari celana jeans biru di toko, tetapi stoknya habis. Saat celana jeans tersedia lagi di toko ini atau toko lain, pembeli akan melihat pembaruan dan dapat melanjutkan pesanan.

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

Pandu saya

Menghapus tutorial pemenuhan pesanan

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 pemenuhan produk menggunakan metode RemoveFulfillmentPlaces. Dengan cara ini, Vertex AI Search untuk commerce dapat menampilkan pembaruan jika produk tidak tersedia dan pesanan tidak dapat dipenuhi. Dengan cara ini, penelusuran dapat menampilkan pembaruan jika produk tidak tersedia dan pesanan tidak dapat dipenuhi. Misalnya, pembeli mencari celana jeans biru di toko. Jika jeans kehabisan stok di toko ini, 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 dapat terjadi jauh lebih sering daripada perubahan pada informasi katalognya. Oleh karena itu, serangkaian metode khusus disediakan untuk menangani pembaruan spesifik inventaris dalam jumlah besar. Metode ini bersifat asinkron karena pengoptimalan hilir yang mendukung ratusan update serentak per produk, tanpa mengorbankan performa.

Update inkremental

Perhatikan bahwa sebaiknya ikuti panduan pembaruan inventaris lokal untuk melakukan 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 pemenuhan tingkat tempat untuk Product. Dalam beberapa kasus, ketersediaan pemenuhan untuk beberapa tempat tertentu dapat berubah, dan Anda dapat memutuskan untuk mengeluarkan pembaruan yang menjelaskan perubahan ini, bukan menggunakan metode UpdateProduct untuk menentukan ulang seluruh informasi pemenuhan produk.

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

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

  {
    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 pemenuhan "pickup-in-store" ke ID tempat "store0" dan "store1" untuk produk yang ditentukan. Karena AddFulfillmentPlacesRequest.allow_missing ditetapkan ke benar (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 menggantikan status penyelesaian ID tempat ini. Fitur ini dibahas secara lebih mendetail di bagian berikut.

Perilakunya identik untuk RemoveFulfillmentPlacesRequest dan skemanya sangat mirip.

Saat fulfillment_types diperbarui oleh AddLocalInventories dan RemoveLocalInventories, fulfillment_types mencerminkan pemetaan dari setiap ID tempat ke daftar jenis pemenuhan yang didukungnya. Jika fulfillment_info diperbarui oleh AddFulfillmentPlaces dan RemoveFulfillmentPlaces, maka akan mencerminkan pemetaan dari setiap jenis fulfillment tertentu ke daftar ID tempat yang mendukung setiap jenis. Kedua jenis API memodifikasi informasi pemenuhan yang sama, dan efek kedua jenis API ini tercermin dalam 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 terbitkan update non-inkremental ke fulfillment_info, bukan hanya perubahan inkremental. Dalam kasus seperti itu, metode SetInventory direkomendasikan.

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

  {
    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, SetInventoryRequest.product.fulfillment_info kolom adalah deskripsi lengkap dari ID tempat yang memenuhi syarat untuk setiap jenis pemenuhan, bukan spesifikasi inkremental. Pembaruan pada "same-day-delivery" menunjukkan bahwa tidak ada ID tempat yang memenuhi syarat untuk jenis pemenuhan ini untuk produk ini. Semua jenis pemenuhan lainnya tidak diperbarui dalam permintaan ini. Dengan demikian, metode ini dapat digunakan untuk mengganti ID tempat hanya untuk sebagian kecil jenis pemenuhan, sementara jenis lainnya tidak diubah.

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 di SetInventoryRequest.set_mask, maka nilai yang ditentukan untuk kolom inventaris tersebut akan diabaikan dalam permintaan pembaruan.

Seperti pembaruan inkremental, kolom SetInventoryRequest.set_time dapat digunakan untuk menyetel waktu pembaruan yang akan dibandingkan dengan waktu pembaruan terakhir yang tercatat 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 terakhir yang dicatat untuk kolom inventaris yang relevan, dan pembaruan dilakukan jika dan hanya jika waktu pembaruan tepat setelah waktu pembaruan terakhir.

Misalnya, anggaplah ID tempat "store1" mengaktifkan jenis pemenuhan "pickup-in- store", dengan waktu pembaruan terakhir yang tercatat 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 baru dari waktu T. Hal yang sama berlaku untuk AddFulfillmentPlacesRequests.

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

Oleh karena itu, saat SetInventoryRequest diproses, pembaruan fulfillment_info secara implisit dikonversi menjadi AddFulfillmentPlacesRequest dan RemoveFulfillmentPlacesRequest untuk setiap jenis pemenuhan pesanan yang ditentukan. Artinya, jika ada tempat "store1" yang ada dengan pemenuhan "pickup-in-store" yang memiliki waktu update terakhir T yang lebih baru daripada SetInventoryRequest.set_time, maka penambahan/penghapusan implisit pada "store1" dan "pickup-in-store" tidak akan diterapkan.

Memuat informasi inventaris terlebih dahulu

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

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 kolom inventaris dapat diperbarui dengan metode CRUD Produk, pemanggil harus mengetahui secara eksplisit efek pada 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 menjadi mahal untuk mengandalkan metode ini untuk pembaruan inventaris yang sering. Jika memungkinkan, sebaiknya gunakan metode pembaruan inventaris yang disebutkan di atas.

CreateProduct

Saat CreateProduct dipanggil dengan setelan kolom inventaris apa pun, nilai yang diberikan dalam CreateProductRequest.product akan menggantikan nilai yang dimuat sebelumnya untuk kolom masing-masing 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

{
  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 eksplisit

{
  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 sebelumnya, dengan mengabaikan waktu pembaruan 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 pemenuhan "pickup-in-store" dan "same-day-delivery".

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

UpdateProduct

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

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

{
  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 informasi inventaris dapat dimuat sebelumnya menggunakan UpdateProduct dengan menetapkan UpdateProductRequest.allow_missing ke true untuk melakukan Product upsert, metode ini memerlukan penetapan kolom katalog tertentu seperti UpdateProductRequest.product.title. Oleh karena itu, sebaiknya gunakan metode update inventaris untuk kasus penggunaan pra-pemuatan.

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.