Mengimpor informasi katalog

Halaman ini menjelaskan cara mengimpor informasi katalog Anda dan terus memperbaruinya.

Prosedur impor di halaman ini berlaku untuk rekomendasi dan penelusuran. Setelah Anda mengimpor data, kedua layanan dapat menggunakan data tersebut, sehingga Anda tidak perlu mengimpor data yang sama dua kali jika menggunakan kedua layanan.

Impor data katalog dari BigQuery

Tutorial ini menunjukkan cara menggunakan tabel BigQuery untuk mengimpor sejumlah besar data katalog tanpa batas.

---

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

Pandu saya

---

Mengimpor data katalog dari Cloud Storage

Tutorial ini menunjukkan cara mengimpor item dalam jumlah besar ke katalog.

---

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

Pandu saya

---

Mengimpor data katalog secara inline

Tutorial ini menunjukkan cara mengimpor produk ke dalam katalog.

---

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

Pandu saya

---

Sebelum memulai

Sebelum dapat mengimpor informasi katalog, Anda harus telah menyelesaikan petunjuk di bagian Sebelum memulai, khususnya menyiapkan project, membuat akun layanan, dan menambahkan akun layanan ke lingkungan lokal Anda.

Anda harus memiliki peran IAM Admin Retail untuk melakukan impor.

Praktik terbaik impor katalog

Data berkualitas tinggi diperlukan untuk memberikan hasil yang berkualitas tinggi. Jika data Anda tidak memiliki kolom atau memiliki nilai placeholder, bukan nilai sebenarnya, kualitas prediksi dan hasil penelusuran akan menurun.

Saat mengimpor data katalog, pastikan Anda menerapkan praktik terbaik berikut:

• Pastikan Anda berpikir cermat saat menentukan produk atau kelompok produk mana yang merupakan produk utama dan mana yang merupakan varian. Sebelum Anda mengupload data apa pun, lihat Tingkat produk.

  Mengubah konfigurasi tingkat produk setelah mengimpor data memerlukan upaya yang signifikan.

  Item utama ditampilkan sebagai hasil penelusuran atau rekomendasi. Item varian tidak.

  Misalnya, jika grup SKU utama adalah "kemeja V-neck", model rekomendasi akan menampilkan satu item kemeja V-neck, dan mungkin, kemeja crew-neck dan scoop-neck. Namun, jika varian tidak digunakan dan setiap SKU adalah yang utama, setiap kombinasi warna/ukuran kemeja V-neck akan ditampilkan sebagai item yang berbeda di panel rekomendasi: "Kemeja V-neck coklat, ukuran XL", "Kemeja V-neck cokelat, ukuran L", hingga "Kemeja V-neck putih, ukuran M", "Kemeja V-neck putih, ukuran S".

• Amati batas impor item produk.

  Untuk impor massal dari Cloud Storage, ukuran setiap file harus 2 GB atau lebih kecil. Anda dapat menyertakan hingga 100 file sekaligus dalam satu permintaan impor massal.

  Untuk impor inline, impor tidak lebih dari 5.000 item produk sekaligus.

• Pastikan semua informasi katalog yang diperlukan disertakan dan benar.

  Jangan gunakan nilai placeholder.

• Sertakan sebanyak mungkin informasi katalog opsional.

• Pastikan semua peristiwa menggunakan mata uang tunggal, terutama jika Anda berencana menggunakan Konsol Google Cloud untuk mendapatkan metrik pendapatan. Vertex AI Search for retail API tidak mendukung penggunaan beberapa mata uang per katalog.

• Perbarui terus katalog Anda.

  Idealnya, Anda harus memperbarui katalog setiap hari. Menjadwalkan impor katalog berkala akan mencegah penurunan kualitas model seiring waktu. Anda dapat menjadwalkan impor berulang otomatis saat mengimpor katalog menggunakan konsol Search for Retail. Atau, Anda dapat menggunakan Google Cloud Scheduler untuk mengotomatiskan impor.

• Jangan mencatat peristiwa pengguna untuk item produk yang belum diimpor.

• Setelah mengimpor informasi katalog, tinjau informasi pelaporan error dan logging untuk project Anda.

  Terdapat beberapa error, tetapi jika terdapat banyak error, Anda harus meninjaunya dan memperbaiki setiap masalah proses yang menyebabkan error tersebut.

Tentang mengimpor data katalog

Anda dapat mengimpor data produk dari Merchant Center, Cloud Storage, BigQuery, atau menentukan data inline dalam permintaan. Masing-masing prosedur ini adalah impor satu kali dengan pengecualian menautkan Merchant Center. Jadwalkan impor katalog reguler (idealnya, setiap hari) untuk memastikan katalog Anda sudah yang terbaru. Lihat Memastikan katalog Anda selalu yang terbaru.

Anda juga dapat mengimpor masing-masing item produk. Untuk mengetahui informasi selengkapnya, lihat Mengupload produk.

Pertimbangan impor katalog

Bagian ini menjelaskan metode yang dapat digunakan untuk mengimpor batch data katalog Anda, kapan Anda mungkin menggunakan setiap metode, dan beberapa batasannya.

Sinkronisasi Merchant Center	Deskripsi	Mengimpor data katalog melalui Merchant Center dengan menautkan akun ke Vertex AI Search untuk retail. Setelah penautan, pembaruan pada data katalog di Merchant Center akan disinkronkan secara real time ke Vertex AI Search untuk retail.
	Kapan digunakan	Jika Anda sudah memiliki integrasi dengan Merchant Center.
	Batasan	Dukungan skema terbatas. Misalnya, koleksi produk tidak didukung oleh Merchant Center. Merchant Center menjadi sumber tepercaya untuk data sampai tautannya dibatalkan, sehingga setiap atribut khusus yang diperlukan harus ditambahkan ke data Merchant Center. Kontrol terbatas. Anda tidak dapat menentukan kolom tertentu atau kumpulan item yang akan diimpor dari Merchant Center; semua item dan kolom yang ada di Merchant Center akan diimpor.
BigQuery	Deskripsi	Impor data dari tabel BigQuery yang dimuat sebelumnya yang menggunakan Vertex AI Search untuk skema retail atau skema Merchant Center. Dapat dilakukan menggunakan konsol Google Cloud atau curl.
	Kapan digunakan	Apakah Anda memiliki katalog produk dengan banyak atribut. Impor BigQuery menggunakan Vertex AI Search untuk skema retail, yang memiliki lebih banyak atribut produk daripada opsi impor lainnya, termasuk atribut khusus kunci/nilai. Jika Anda memiliki data dalam volume besar. Impor BigQuery tidak memiliki batas data. Jika Anda sudah menggunakan BigQuery.
	Batasan	Memerlukan langkah tambahan untuk membuat tabel BigQuery yang memetakan ke Vertex AI Search untuk skema retail.
Cloud Storage	Deskripsi	Mengimpor data dalam format JSON dari file yang dimuat di bucket Cloud Storage. Setiap file harus berukuran 2 GB atau lebih kecil dan maksimal 100 file sekaligus dapat diimpor. Impor dapat dilakukan menggunakan konsol Google Cloud atau curl. Menggunakan format data JSON Product, yang memungkinkan atribut khusus.
	Kapan digunakan	Jika Anda perlu memuat data dalam jumlah besar dalam satu langkah.
	Batasan	Tidak cocok untuk katalog dengan inventaris yang sering diperbarui dan pembaruan harga karena perubahan tidak langsung diterapkan.
Impor inline	Deskripsi	Impor menggunakan panggilan ke metode Product.import. Menggunakan objek ProductInlineSource, yang memiliki atribut katalog produk lebih sedikit daripada Vertex AI Search untuk skema retail, tetapi mendukung atribut kustom.
	Kapan digunakan	Jika Anda memiliki data katalog tetap dan non-relasional atau frekuensi kuantitas atau pembaruan harga yang tinggi.
	Batasan	Tidak lebih dari 100 item katalog dapat diimpor sekaligus. Namun, banyak langkah pemuatan yang dapat dilakukan; tidak ada batas item.

Hapus permanen cabang katalog

Jika Anda mengimpor data katalog baru ke cabang yang sudah ada, cabang katalog harus kosong. Hal ini memastikan integritas data yang diimpor ke cabang tersebut. Jika cabang kosong, Anda dapat mengimpor data katalog baru, lalu menautkan cabang ke akun penjual.

Jika Anda menayangkan prediksi langsung atau traffic penelusuran dan berencana untuk menghapus cabang default, sebaiknya tentukan cabang lain terlebih dahulu sebagai default sebelum menghapus permanen. Karena cabang default akan menyajikan hasil kosong setelah dihapus permanen, menghapus permanen cabang default aktif dapat menyebabkan pemadaman layanan.

Untuk menghapus permanen data dari cabang katalog, selesaikan langkah-langkah berikut:

1. Buka halaman Data> di konsol Search for Retail.
   
   Buka halaman Data

2. Pilih cabang katalog dari kolom Nama cabang.

3. Dari menu tiga titik di samping kolom Branch name, pilih Purge branch.

   Sebuah pesan akan ditampilkan yang memperingatkan Anda bahwa Anda akan menghapus semua data di cabang serta atribut apa pun yang dibuat untuk cabang tersebut.

   Catatan: Anda tidak dapat mengurungkan penghapusan data cabang katalog.

4. Masukkan cabang, lalu klik Konfirmasi untuk menghapus data katalog dari cabang.

   Operasi yang berjalan lama akan mulai menghapus permanen data dari cabang katalog. Setelah operasi penghapusan permanen selesai, status penghapusan akan ditampilkan di daftar Katalog produk di jendela Status aktivitas.

   Catatan: Daftar data katalog cabang tidak otomatis diperbarui setelah penghapusan permanen selesai. Anda harus memuat ulang halaman guna melihat daftar terbaru untuk cabang tersebut.

Menyinkronkan Merchant Center ke Vertex AI Search untuk retail

Agar sinkronisasi berkelanjutan antara Merchant Center dan Vertex AI Search untuk retail, Anda dapat menautkan akun Merchant Center ke Vertex AI Search untuk retail. Setelah melakukan penautan, informasi katalog di akun Merchant Center Anda akan langsung diimpor ke Vertex AI Search untuk retail.

Meskipun Vertex AI Search untuk retail ditautkan ke akun Merchant Center, perubahan pada data produk Anda di akun Merchant Center otomatis diperbarui dalam hitungan menit di Vertex AI Search untuk retail. Jika ingin agar perubahan Merchant Center tidak disinkronkan ke Vertex AI Search untuk retail, Anda dapat membatalkan tautan akun Merchant Center.

Membatalkan tautan akun Merchant Center tidak akan menghapus produk apa pun di Vertex AI Search untuk retail. Untuk menghapus produk yang diimpor, lihat Menghapus informasi produk.

Sinkronkan akun Merchant Center Anda

Untuk menyinkronkan akun Merchant Center, selesaikan langkah-langkah berikut.

Konsol

1. Buka halaman Data> di konsol Search for Retail.
   
   Buka halaman Data
2. Klik Import untuk membuka panel Import Data.
3. Pilih Katalog produk.
4. Pilih Sinkronisasi Merchant Center sebagai sumber data Anda.
5. Pilih akun Merchant Center Anda. Periksa Akses Pengguna jika Anda tidak melihat akun.
6. Opsional: Pilih filter feed Merchant Center untuk mengimpor hanya penawaran dari feed yang dipilih.
   
   Jika tidak ditentukan, penawaran dari semua feed akan diimpor (termasuk feed mendatang).
7. Opsional: Untuk mengimpor hanya penawaran yang ditargetkan ke negara atau bahasa tertentu, luaskan Tampilkan Opsi Lanjutan, lalu pilih negara penjualan dan bahasa Merchant Center yang ingin difilter.
8. Pilih cabang tempat Anda akan mengupload katalog.
9. Klik Import.

curl

1. Pastikan akun layanan di lingkungan lokal Anda memiliki akses ke akun Merchant Center dan Vertex AI Search untuk retail. Untuk mencari tahu akun yang memiliki akses ke akun Merchant Center Anda, lihat Akses pengguna untuk Merchant Center.

2. Gunakan metode MerchantCenterAccountLink.create untuk membuat link.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
    --data '{
     "merchantCenterAccountId": MERCHANT_CENTER_ID,
     "branchId": "BRANCH_ID",
     "feedFilters": [
       {"primaryFeedId": PRIMARY_FEED_ID_1}
       {"primaryFeedId": PRIMARY_FEED_ID_2}
     ],
     "languageCode": "LANGUAGE_CODE",
     "feedLabel": "FEED_LABEL",
    }' \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
   

   • MERCHANT_CENTER_ID: ID akun Merchant Center.
   • BRANCH_ID: ID cabang yang akan digunakan untuk membuat link. Menerima nilai '0', '1', atau '2'.
   • LANGUAGE_CODE: (OPSIONAL) Kode bahasa dua huruf produk yang ingin Anda impor. Seperti yang terlihat di Merchant Center pada kolom Language pada produk. Jika tidak disetel, semua bahasa akan diimpor.
   • FEED_LABEL: (OPSIONAL) Label feed produk yang ingin Anda impor. Anda dapat melihat label feed di Merchant Center pada produk kolom Label Feed produk. Jika tidak ditetapkan, semua label feed akan diimpor.
   • FEED_FILTERS: (OPSIONAL) Daftar feed utama tempat produk akan diimpor. Jika feed tidak dipilih, semua feed akun Merchant Center akan dibagikan. ID ini dapat ditemukan di resource datafeed Content API atau dengan mengunjungi Merchant Center, memilih feed, dan mendapatkan ID feed dari parameter dataSourceId di URL situs. Sebagai contoh, mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID

Untuk melihat Merchant Center tertaut, buka halaman Data Search for Retail console, lalu klik tombol Merchant Center di kanan atas halaman. Tindakan ini akan membuka panel Akun Merchant Center Tertaut. Anda juga dapat menambahkan akun Merchant Center lain dari panel ini.

Baca artikel Melihat informasi gabungan tentang katalog Anda untuk mendapatkan petunjuk cara melihat produk yang telah diimpor.

Menampilkan daftar penautan akun Merchant Center

Cantumkan penautan akun Merchant Center Anda.

Konsol

1. Buka halaman Data> di konsol Search for Retail.
   
   Buka halaman Data

2. Klik tombol Merchant Center di kanan atas halaman untuk membuka daftar akun Merchant Center yang tertaut.

curl

Gunakan metode MerchantCenterAccountLink.list untuk mencantumkan resource link.

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Batalkan tautan akun Merchant Center Anda

Membatalkan tautan akun Merchant Center akan menghentikan sinkronisasi data katalog ke Vertex AI Search untuk retail dari akun tersebut. Prosedur ini tidak menghapus produk apa pun di Vertex AI Search untuk retail yang telah diupload.

Konsol

1. Buka halaman Data> di konsol Search for Retail.
   
   Buka halaman Data

2. Klik tombol Merchant Center di kanan atas halaman untuk membuka daftar akun Merchant Center yang tertaut.

3. Klik Batalkan tautan di samping akun Merchant Center yang akan Anda batalkan tautannya, lalu konfirmasi pilihan Anda pada dialog yang muncul.

curl

Gunakan metode MerchantCenterAccountLink.delete untuk menghapus resource MerchantCenterAccountLink.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Batasan penautan ke Merchant Center

• Akun Merchant Center dapat ditautkan ke sejumlah cabang katalog, tetapi satu cabang katalog hanya dapat ditautkan ke satu akun Merchant Center.

• Akun Merchant Center tidak boleh berupa akun multiklien (MCA). Namun, Anda dapat menautkan sub-akun satu per satu.

• Proses impor pertama setelah menautkan akun Merchant Center mungkin membutuhkan waktu berjam-jam. Durasi waktu ini bergantung pada jumlah penawaran di akun Merchant Center.

• Setiap modifikasi produk yang menggunakan metode API akan dinonaktifkan untuk cabang yang ditautkan ke akun Merchant Center. Setiap perubahan pada data katalog produk di cabang tersebut harus dilakukan menggunakan Merchant Center. Perubahan tersebut kemudian otomatis disinkronkan ke Vertex AI Search untuk retail.

• Jenis produk koleksi tidak didukung untuk cabang yang menggunakan penautan Merchant Center.

• Akun Merchant Center Anda hanya dapat ditautkan ke cabang katalog yang kosong untuk memastikan ketepatan data. Untuk menghapus produk dari cabang katalog, lihat Menghapus informasi produk.

Impor data katalog dari Merchant Center

Merchant Center adalah alat yang dapat Anda gunakan agar data toko dan produk Anda tersedia untuk iklan Shopping dan layanan Google lainnya.

Anda dapat mengimpor data katalog secara massal dari Merchant Center sebagai prosedur satu kali dari BigQuery menggunakan skema Merchant Center (khusus rekomendasi).

Impor massal dari Merchant Center

Anda dapat mengimpor data katalog dari Merchant Center menggunakan Search for Retail console atau metode products.import. Impor massal adalah prosedur satu kali, dan hanya didukung untuk rekomendasi.

Untuk mengimpor katalog dari Merchant Center, selesaikan langkah-langkah berikut:

1. Dengan petunjuk dalam transfer Merchant Center, siapkan transfer dari Merchant Center ke BigQuery.

   Anda akan menggunakan skema tabel produk Google Merchant Center. Konfigurasi transfer Anda agar berulang setiap hari, tetapi konfigurasikan waktu habis masa berlaku set data pada 2 hari.

2. Jika set data BigQuery Anda berada dalam project lain, konfigurasikan izin yang diperlukan agar Vertex AI Search untuk retail dapat mengakses set data BigQuery. Pelajari lebih lanjut.

3. Impor data katalog Anda dari BigQuery ke Vertex AI Search untuk retail.

   Konsol

   1. Buka halaman Data> di konsol Search for Retail.
      
      Buka halaman Data

   2. Klik Import untuk membuka panel Import.

   3. Pilih Katalog produk.

   4. Pilih BigQuery sebagai sumber data Anda.

   5. Pilih cabang tempat Anda akan mengupload katalog.

   6. Pilih Merchant Center sebagai skema data.

   7. Masukkan tabel BigQuery tempat data Anda berada.

   8. Opsional: Masukkan lokasi bucket Cloud Storage dalam project Anda sebagai lokasi sementara untuk data Anda.

      Jika tidak ditentukan, lokasi default akan digunakan. Jika ditentukan, bucket BigQuery dan Cloud Storage harus berada di region yang sama.

   9. Pilih apakah akan menjadwalkan upload berulang data katalog Anda atau tidak.

   10. Jika ini adalah pertama kalinya Anda mengimpor katalog, atau Anda mengimpor ulang katalog setelah menghapusnya,pilih tingkat produk. Pelajari lebih lanjut tingkat produk.

       Mengubah konfigurasi tingkat produk setelah mengimpor data memerlukan upaya yang signifikan.

       Penting: Anda tidak dapat mengaktifkan penelusuran project dengan katalog produk yang telah diserap hanya sebagai varian. Jika Anda ingin menggunakan varian penelusuran dan penyerapan, gunakan tingkat produk primary.

   11. Klik Import.

   curl

   1. Jika ini adalah pertama kalinya Anda mengupload katalog, atau Anda mengimpor ulang katalog setelah menghapusnya, tetapkan tingkat produk menggunakan metode Catalog.patch. Operasi ini memerlukan peran Admin Retail. Pelajari lebih lanjut tingkat produk.

      • ingestionProductType: Mendukung nilai primary (default) dan variant.
      • merchantCenterProductIdField: Mendukung nilai offerId (default) dan itemGroupId. Jika Anda tidak menggunakan Merchant Center, tetapkan ke nilai default offerId.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT_TYPE",
        "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Impor katalog Anda menggunakan metode Products.import.

      • DATASET_ID: ID set data BigQuery.
      • TABLE_ID: ID tabel BigQuery yang menyimpan data Anda.
      • STAGING_DIRECTORY: Opsional. Direktori Cloud Storage yang digunakan sebagai lokasi sementara untuk data Anda sebelum diimpor ke BigQuery. Biarkan kolom ini kosong untuk membuat direktori sementara secara otomatis (direkomendasikan).
      • ERROR_DIRECTORY: Opsional. Direktori Cloud Storage untuk informasi error tentang impor. Biarkan kolom ini kosong untuk membuat direktori sementara secara otomatis (direkomendasikan).
      • dataSchema: Untuk properti dataSchema, gunakan nilai product_merchant_center. Lihat skema tabel produk Merchant Center.

      Sebaiknya Anda tidak menentukan direktori staging atau error. Dengan begitu, bucket Cloud Storage dengan direktori staging dan error baru dapat dibuat otomatis. Direktori ini dibuat di region yang sama dengan set data BigQuery, dan bersifat unik untuk setiap impor (yang mencegah beberapa tugas impor mengatur data staging ke direktori yang sama, dan berpotensi mengimpor ulang data yang sama). Setelah tiga hari, bucket dan direktori akan otomatis dihapus untuk mengurangi biaya penyimpanan.

      Nama bucket yang dibuat secara otomatis mencakup project ID, region bucket, dan nama skema data, yang dipisahkan dengan garis bawah (misalnya, 4321_us_catalog_retail). Direktori yang dibuat secara otomatis disebut staging atau errors, yang ditambahkan dengan angka (misalnya staging2345 atau errors5678).

      Jika Anda menentukan direktori, bucket Cloud Storage harus berada di region yang sama dengan set data BigQuery, atau impor akan gagal. Berikan direktori staging dan error dalam format gs://<bucket>/<folder>/; keduanya harus berbeda.

     curl -X POST \
          -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
          -H "Content-Type: application/json; charset=utf-8" \
          --data '{
            "inputConfig":{
               "bigQuerySource": {
                 "datasetId":"DATASET_ID",
                 "tableId":"TABLE_ID",
                 "dataSchema":"product_merchant_center"
               }
             }
         }' \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
   

Impor data katalog dari BigQuery

Untuk mengimpor data katalog dalam format yang benar dari BigQuery, gunakan Vertex AI Search untuk skema retail guna membuat tabel BigQuery dengan format yang benar dan memuat tabel kosong dengan data katalog Anda. Kemudian, upload data Anda ke Vertex AI Search untuk retail.

Untuk mendapatkan bantuan lebih lanjut terkait tabel BigQuery, lihat Pengantar tabel. Untuk mendapatkan bantuan terkait kueri BigQuery, lihat Ringkasan cara mengkueri data BigQuery.

---

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

Pandu saya

---

Untuk mengimpor katalog Anda:

1. Jika set data BigQuery Anda berada dalam project lain, konfigurasikan izin yang diperlukan agar Vertex AI Search untuk retail dapat mengakses set data BigQuery. Pelajari lebih lanjut.

2. Impor data katalog Anda ke Vertex AI Search untuk retail.

   Konsol

   1. Buka halaman Data> di konsol Search for Retail.
      
      Buka halaman Data
   2. Klik Import untuk membuka panel Import Data.
   3. Pilih Katalog produk.
   4. Pilih BigQuery sebagai sumber data Anda.
   5. Pilih cabang tempat Anda akan mengupload katalog.
   6. Pilih Skema Katalog Produk Retail. Ini adalah Skema produk untuk Vertex AI Search untuk retail.
   7. Masukkan tabel BigQuery tempat data Anda berada.
   8. Opsional: Di bagian Tampilkan opsi lanjutan, masukkan lokasi bucket Cloud Storage dalam project Anda sebagai lokasi sementara untuk data Anda.
      
      Jika tidak ditentukan, lokasi default akan digunakan. Jika ditentukan, bucket BigQuery dan Cloud Storage harus berada di region yang sama.
   9. Jika Anda tidak mengaktifkan penelusuran dan menggunakan skema Merchant Center, pilih tingkat produk.
      
      Anda harus memilih tingkat produk jika ini adalah pertama kalinya Anda mengimpor katalog, atau Anda mengimpor ulang katalog setelah menghapusnya secara permanen. Pelajari lebih lanjut tingkat produk. Mengubah tingkat produk setelah Anda mengimpor data memerlukan upaya yang signifikan.
      
      Penting: Anda tidak dapat mengaktifkan penelusuran project dengan katalog produk yang telah diserap sebagai varian.
   10. Klik Import.

   curl

   1. Jika ini adalah pertama kalinya Anda mengupload katalog, atau Anda mengimpor ulang katalog setelah menghapusnya, tetapkan tingkat produk menggunakan metode Catalog.patch. Operasi ini memerlukan peran Admin Retail.

      • ingestionProductType: Mendukung nilai primary (default) dan variant.
      • merchantCenterProductIdField: Mendukung nilai offerId dan itemGroupId. Jika tidak menggunakan Merchant Center, Anda tidak perlu menyiapkan kolom ini.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"
      

   2. Buat file data untuk parameter input untuk impor.

      Gunakan objek BigQuerySource untuk mengarah ke set data BigQuery Anda.

      • DATASET_ID: ID set data BigQuery.
      • TABLE_ID: ID tabel BigQuery yang menyimpan data Anda.
      • PROJECT_ID: Project ID tempat sumber BigQuery berada. Jika tidak ditentukan, project ID diwariskan dari permintaan induk.
      • STAGING_DIRECTORY: Opsional. Direktori Cloud Storage yang digunakan sebagai lokasi sementara untuk data Anda sebelum diimpor ke BigQuery. Biarkan kolom ini kosong untuk membuat direktori sementara secara otomatis (direkomendasikan).
      • ERROR_DIRECTORY: Opsional. Direktori Cloud Storage untuk informasi error tentang impor. Biarkan kolom ini kosong untuk membuat direktori sementara secara otomatis (direkomendasikan).
      • dataSchema: Untuk properti dataSchema, gunakan nilai product (default). Anda akan menggunakan Vertex AI Search untuk skema retail.

      Sebaiknya Anda tidak menentukan direktori staging atau error. Dengan begitu, bucket Cloud Storage dengan direktori staging dan error baru dapat dibuat otomatis. Direktori ini dibuat di region yang sama dengan set data BigQuery, dan bersifat unik untuk setiap impor (yang mencegah beberapa tugas impor mengatur data staging ke direktori yang sama, dan berpotensi mengimpor ulang data yang sama). Setelah tiga hari, bucket dan direktori akan otomatis dihapus untuk mengurangi biaya penyimpanan.

      Nama bucket yang dibuat secara otomatis mencakup project ID, region bucket, dan nama skema data, yang dipisahkan dengan garis bawah (misalnya, 4321_us_catalog_retail). Direktori yang dibuat secara otomatis disebut staging atau errors, yang ditambahkan dengan angka (misalnya staging2345 atau errors5678).

      Jika Anda menentukan direktori, bucket Cloud Storage harus berada di region yang sama dengan set data BigQuery, atau impor akan gagal. Berikan direktori staging dan error dalam format gs://<bucket>/<folder>/; keduanya harus berbeda.

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }
      

   3. Impor informasi katalog Anda dengan membuat permintaan POST ke metode REST Products:import, dengan memberikan nama file data (di sini, ditampilkan sebagai input.json).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
      

      Anda dapat memeriksa status secara terprogram menggunakan API. Anda akan menerima objek respons yang terlihat seperti ini:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }
      

      Kolom nama adalah ID objek operasi. Untuk meminta status objek ini, ganti kolom nama dengan nilai yang ditampilkan oleh metode import, sampai kolom done ditampilkan sebagai true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"
      

      Setelah operasi selesai, objek yang ditampilkan memiliki nilai done sebesar true, dan menyertakan objek Status yang mirip dengan contoh berikut:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }
      

      Anda dapat memeriksa file dalam direktori error di Cloud Storage untuk melihat apakah terjadi error selama proses impor.

Menyiapkan akses ke set data BigQuery Anda

Untuk menyiapkan akses saat set data BigQuery Anda berada di project yang berbeda dengan Vertex AI Search untuk layanan retail, selesaikan langkah-langkah berikut.

1. Buka halaman IAM di konsol Google Cloud.

   Buka halaman IAM

2. Pilih Vertex AI Search Anda untuk project retail.

3. Temukan akun layanan dengan nama Akun Layanan Retail.

   Jika Anda belum pernah memulai operasi impor, akun layanan ini mungkin tidak tercantum. Jika Anda tidak melihat akun layanan ini, kembali ke tugas impor dan mulai impor. Jika gagal karena error izin, kembali ke sini dan selesaikan tugas ini.

4. Salin ID untuk akun layanan, yang terlihat seperti alamat email (misalnya, [e-mail]).

5. Beralihlah ke project BigQuery Anda (di halaman IAM & Admin yang sama) lalu klik  Grant Access.

6. Untuk Akun utama baru, masukkan ID Vertex AI Search untuk akun layanan retail, lalu pilih peran BigQuery > BigQuery User.

7. Klik Tambahkan peran lain dan pilih BigQuery > BigQuery Data Editor.

   Jika tidak ingin memberikan peran Editor Data ke seluruh project, Anda dapat menambahkan peran ini langsung ke set data. Pelajari lebih lanjut.

8. Klik Save.

Mengimpor data katalog dari Cloud Storage

Untuk mengimpor data katalog dalam format JSON, buat satu atau beberapa file JSON yang berisi data katalog yang ingin diimpor, lalu upload ke Cloud Storage. Dari sana, Anda dapat mengimpornya ke Vertex AI Search untuk retail.

Untuk contoh format item produk JSON, lihat Format data JSON item produk.

Untuk mendapatkan bantuan terkait cara mengupload file ke Cloud Storage, lihat Mengupload objek.

1. Pastikan Vertex AI Search untuk akun layanan retail memiliki izin untuk membaca dan menulis ke bucket.

   Vertex AI Search untuk akun layanan retail tercantum di halaman IAM di Konsol Google Cloud dengan nama Retail Service Account. Gunakan ID akun layanan, yang terlihat seperti alamat email (misalnya, [e-mail]), saat menambahkan akun ke izin bucket Anda.

2. Impor data katalog Anda.

   Konsol

   1. Buka halaman Data> di konsol Search for Retail.
      
      Buka halaman Data
   2. Klik Import untuk membuka panel Import Data.
   3. Pilih Katalog produk sebagai sumber data Anda.
   4. Pilih cabang tempat Anda akan mengupload katalog.
   5. Pilih Skema Katalog Produk Retail sebagai skema.
   6. Masukkan lokasi Cloud Storage data Anda.
   7. Jika penelusuran tidak diaktifkan, pilih tingkat produk.
      
      Anda harus memilih tingkat produk jika ini adalah pertama kalinya Anda mengimpor katalog atau mengimpor ulang katalog setelah menghapusnya. Pelajari lebih lanjut tingkat produk. Mengubah tingkat produk setelah Anda mengimpor data memerlukan upaya yang signifikan.
      
      Penting: Anda tidak dapat mengaktifkan penelusuran project dengan katalog produk yang telah diserap sebagai varian.
   8. Klik Import.

   curl

   1. Jika ini adalah pertama kalinya Anda mengupload katalog, atau Anda mengimpor ulang katalog setelah menghapusnya, tetapkan tingkat produk menggunakan metode Catalog.patch. Pelajari lebih lanjut tingkat produk.

      • ingestionProductType: Mendukung nilai primary (default) dan variant.
      • merchantCenterProductIdField: Mendukung nilai offerId dan itemGroupId. Jika tidak menggunakan Merchant Center, Anda tidak perlu menyiapkan kolom ini.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"
      

   2. Buat file data untuk parameter input untuk impor. Gunakan objek GcsSource untuk mengarah ke bucket Cloud Storage Anda.

      Anda dapat memberikan beberapa file, atau hanya satu; contoh ini menggunakan dua file.

      • INPUT_FILE: File di Cloud Storage yang berisi data katalog Anda.
      • ERROR_DIRECTORY: Direktori Cloud Storage untuk informasi error tentang impor.

      Kolom file input harus dalam format gs://<bucket>/<path-to-file>/. Direktori error harus dalam format gs://<bucket>/<folder>/. Jika tidak ada, direktori error akan dibuat. Bucket harus sudah ada.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }
      

   3. Impor informasi katalog Anda dengan membuat permintaan POST ke metode REST Products:import, dengan memberikan nama file data (di sini, ditampilkan sebagai input.json).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
      

      Cara termudah untuk memeriksa status operasi impor Anda adalah dengan menggunakan Konsol Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Melihat status untuk operasi integrasi tertentu.

      Anda juga dapat memeriksa status secara terprogram menggunakan API. Anda akan menerima objek respons yang terlihat seperti ini:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }
      

      Kolom nama adalah ID objek operasi. Anda meminta status objek ini, dengan mengganti kolom nama dengan nilai yang ditampilkan oleh metode impor, sampai kolom done ditampilkan sebagai true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"
      

      Setelah operasi selesai, objek yang ditampilkan akan memiliki nilai done yaitu true, dan menyertakan objek Status yang mirip dengan contoh berikut:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }
      

      Anda dapat memeriksa file dalam direktori error di Cloud Storage untuk melihat jenis error yang terjadi selama proses impor.

Mengimpor data katalog secara inline

curl

Anda dapat mengimpor informasi katalog secara inline dengan membuat permintaan POST ke metode REST Products:import, menggunakan objek productInlineSource untuk menentukan data katalog Anda.

Tampilkan seluruh produk dalam satu baris. Setiap produk harus berada pada barisnya sendiri.

Untuk contoh format item produk JSON, lihat Format data JSON item produk.

1. Buat file JSON untuk produk Anda dan beri nama ./data.json:

   {
   "inputConfig": {
   "productInlineSource": {
     "products": [
       { PRODUCT_1 }
       { PRODUCT_2 }
     ]
   }
   }
   }
   

2. Panggil metode POST:

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @./data.json \
   "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
   

Java

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

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

  return operationName;
}

Format data JSON item produk

Entri Product dalam file JSON Anda akan terlihat seperti contoh berikut.

Tampilkan seluruh produk dalam satu baris. Setiap produk harus berada pada barisnya sendiri.

Penting: Jeda baris dalam contoh ini agar lebih mudah dibaca. Kecuali untuk jeda baris antarproduk, jangan sertakan jeda baris di data JSON Anda.

Kolom minimum yang wajib diisi:

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

Objek lengkap:

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

Data katalog historis

Vertex AI Search untuk retail mendukung pengimporan dan pengelolaan data katalog historis. Data katalog historis dapat berguna saat Anda menggunakan peristiwa pengguna historis untuk pelatihan model. Informasi produk terdahulu dapat digunakan untuk memperkaya data peristiwa pengguna historis dan meningkatkan akurasi model.

Produk historis disimpan sebagai produk yang sudah tidak berlaku. Keduanya tidak ditampilkan dalam respons penelusuran, tetapi terlihat oleh panggilan API Update, List, dan Delete.

Mengimpor data katalog historis

Jika kolom expireTime produk ditetapkan ke stempel waktu yang lalu, produk ini dianggap sebagai produk historis. Tetapkan availability [ketersediaan] produk ke OUT_OF_STOCK agar tidak memengaruhi rekomendasi.

Sebaiknya gunakan metode berikut untuk mengimpor data katalog historis:

• Memanggil metode Product.Create.
• Mengimpor produk kedaluwarsa secara inline.
• Mengimpor produk yang telah habis masa berlakunya dari BigQuery.

Memanggil metode Product.Create

Gunakan metode Product.Create untuk membuat entri Product dengan kolom expireTime ditetapkan ke stempel waktu yang lalu.

Produk inline yang kedaluwarsa

Langkah-langkahnya identik dengan impor inline, kecuali bahwa produk harus memiliki kolom expireTime yang ditetapkan ke stempel waktu yang telah berlalu.

Tampilkan seluruh produk dalam satu baris. Setiap produk harus berada pada barisnya sendiri.

Penting: Jeda baris dalam contoh ini agar lebih mudah dibaca. Kecuali untuk jeda baris antarproduk, jangan sertakan jeda baris di data JSON Anda.

Contoh ./data.json yang digunakan dalam permintaan impor inline:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Impor produk yang habis masa berlakunya dari BigQuery atau Cloud Storage

Gunakan prosedur yang sama dengan yang didokumentasikan untuk mengimpor data katalog dari BigQuery atau mengimpor data katalog dari Cloud Storage. Namun, pastikan untuk menetapkan kolom expireTime ke stempel waktu yang lalu.

Perbarui terus katalog Anda

Untuk hasil terbaik, katalog Anda harus berisi informasi terbaru. Sebaiknya Anda mengimpor katalog setiap hari untuk memastikan katalog Anda selalu yang terbaru. Anda dapat menggunakan Google Cloud Scheduler untuk menjadwalkan impor, atau memilih opsi penjadwalan otomatis saat mengimpor data menggunakan Konsol Google Cloud.

Anda hanya dapat memperbarui item produk baru atau yang diubah, atau mengimpor seluruh katalog. Jika Anda mengimpor produk yang sudah ada di katalog, produk tersebut tidak akan ditambahkan lagi. Item apa pun yang telah berubah akan diperbarui.

Catatan: Jika item sudah tidak berlaku lagi, tetapkan statusnya ke OUT_OF_STOCK, bukan menghapusnya, agar peristiwa pengguna sebelumnya yang mereferensikannya tidak dibatalkan.

Untuk memperbarui satu item, lihat Memperbarui informasi produk.

Update massal

Anda dapat menggunakan metode impor untuk memperbarui katalog dalam batch. Langkah ini dilakukan dengan cara yang sama seperti saat Anda melakukan impor awal; ikuti langkah-langkah dalam Mengimpor data katalog.

Memantau kondisi impor

Untuk memantau kondisi dan penyerapan katalog:

1. Lihat informasi gabungan tentang katalog Anda dan pratinjau produk yang diupload di tab Catalog pada halaman Data Penelusuran Retail.

   Buka halaman Data

2. Lakukan penilaian apakah Anda perlu memperbarui data katalog untuk meningkatkan kualitas hasil penelusuran dan membuka tingkat performa penelusuran di halaman Kualitas data.

   Untuk mengetahui informasi selengkapnya tentang cara memeriksa kualitas data penelusuran dan melihat tingkat performa penelusuran, lihat Membuka tingkat performa penelusuran. Untuk ringkasan metrik katalog yang tersedia di halaman ini, lihat Metrik kualitas katalog.

   Buka halaman Kualitas Data

3. Untuk membuat pemberitahuan yang memberi tahu Anda jika terjadi masalah pada upload data, ikuti prosedur dalam Menyiapkan pemberitahuan Cloud Monitoring.

   Selalu memperbarui katalog Anda sangat penting untuk mendapatkan hasil yang berkualitas tinggi. Gunakan pemberitahuan untuk memantau tingkat error impor dan mengambil tindakan jika diperlukan.

Langkah selanjutnya

• Mulai merekam peristiwa pengguna.
• Lihat informasi gabungan tentang katalog Anda.
• Siapkan notifikasi upload data.