Mengimpor informasi katalog

Halaman ini menjelaskan cara mengimpor informasi katalog dan membuatnya selalu terbaru.

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

Impor data katalog dari BigQuery

Tutorial ini menunjukkan cara menggunakan tabel BigQuery untuk mengimpor data katalog dalam jumlah besar 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 sejumlah besar item 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 katalog secara inline.

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 menyelesaikan petunjuk di Sebelum memulai, khususnya menyiapkan project, membuat akun layanan, dan menambahkan akun layanan ke lingkungan lokal.

Anda harus memiliki peran IAM Retail Admin untuk melakukan impor.

Praktik terbaik impor katalog

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

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

  • Pastikan untuk memikirkan dengan cermat saat menentukan produk atau grup produk mana yang utama dan mana yang merupakan varian. Sebelum mengupload data apa pun, lihat Tingkat produk.

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

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

    Misalnya, jika grup SKU utama adalah "kaos V-neck", maka model rekomendasi akan menampilkan satu item kemeja V-neck, dan, mungkin, kaos crew-neck dan kemeja scoop-neck. Namun, jika varian tidak digunakan dan setiap SKU adalah varian 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 coklat, ukuran L", hingga "Kemeja V-neck putih, ukuran M", "Kemeja V-neck putih, ukuran S".

    Koleksi dapat dikenali bersama-sama selama ID varian disertakan bersama dengan ID produk utama di collectionMemberIds[]. Hal ini menyebabkan koleksi produk, yang mungkin telah dibeli oleh pengguna satu atau beberapa produk dalam set, akan dicatat dalam peristiwa pengguna, yang akan mengkreditkan seluruh set ke pembelian. Hal ini memfasilitasi penayangan produk lain kepada pengguna yang sama dalam koleksi tertentu pada kueri terkait di masa mendatang. Misalnya, produk lain dalam koleksi seprai ditampilkan, seperti sarung bantal dan sprei yang cocok setelah pengguna membeli selimut.

  • Perhatikan 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 sudah benar.

    Jangan gunakan nilai placeholder.

  • Sertakan sebanyak mungkin informasi katalog opsional.

  • Pastikan semua peristiwa Anda menggunakan satu mata uang, terutama jika Anda berencana menggunakan konsol Google Cloud untuk mendapatkan metrik pendapatan. Vertex AI Search untuk 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 kualitas model menurun seiring waktu. Anda dapat menjadwalkan impor berulang otomatis saat mengimpor katalog menggunakan konsol Penelusuran untuk Retail. Atau, Anda dapat menggunakan Google Cloud Scheduler untuk mengotomatiskan impor.

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

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

    Beberapa error mungkin terjadi, tetapi jika Anda mengalami banyak error, Anda harus meninjaunya dan memperbaiki masalah proses yang menyebabkan error.

Tentang mengimpor data katalog

Anda dapat mengimpor data produk dari Merchant Center, Cloud Storage, BigQuery, atau menentukan data secara inline dalam permintaan. Setiap prosedur ini adalah impor satu kali kecuali 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 setiap item produk. Untuk informasi selengkapnya, lihat Mengupload produk.

Pertimbangan impor katalog

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

Sinkronisasi Merchant Center Deskripsi Mengimpor data katalog melalui Merchant Center dengan menautkan akun dengan 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 hingga dihapus tautannya, sehingga atribut kustom yang diperlukan harus ditambahkan ke data Merchant Center.

Kontrol terbatas. Anda tidak dapat menentukan kolom atau kumpulan item tertentu untuk 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 skema retail Vertex AI Search atau skema Merchant Center. Dapat dilakukan menggunakan Konsol Google Cloud atau curl.
Kapan digunakan Jika 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 kustom kunci/nilai.

Jika Anda memiliki data dalam jumlah besar. Impor BigQuery tidak memiliki batas data.

Jika Anda sudah menggunakan BigQuery.
Batasan Memerlukan langkah tambahan untuk membuat tabel BigQuery yang dipetakan ke skema Vertex AI Search untuk 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 kustom.
Kapan digunakan Jika Anda perlu memuat data dalam jumlah besar dalam satu langkah.
Batasan Tidak ideal untuk katalog dengan pembaruan inventaris dan harga yang sering karena perubahan tidak langsung diterapkan.
Impor inline Deskripsi Impor menggunakan panggilan ke metode Product.import. Menggunakan objek ProductInlineSource, yang memiliki lebih sedikit atribut katalog produk daripada skema Vertex AI Search untuk retail, tetapi mendukung atribut kustom.
Kapan digunakan Jika Anda memiliki data katalog datar non-relasional atau frekuensi pembaruan kuantitas atau harga yang tinggi.
Batasan Anda hanya dapat mengimpor maksimal 100 item katalog sekaligus. Namun, banyak langkah pemuatan dapat dilakukan; tidak ada batasan item.

Menghapus cabang katalog

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

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

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

  1. Buka halaman Data> di konsol Penelusuran untuk Retail.

    Buka halaman Data

  2. Pilih cabang katalog dari kolom Nama cabang.

  3. Dari menu tiga titik di samping kolom Nama cabang, pilih Hapus cabang.

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

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

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

Menyinkronkan Merchant Center ke Vertex AI Search untuk retail

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

Saat menyiapkan sinkronisasi Merchant Center untuk Vertex AI Search untuk retail, Anda harus memiliki peran Admin yang ditetapkan di Merchant Center. Meskipun peran Akses standar akan mengizinkan Anda membaca feed Merchant Center di UI, saat mencoba menyinkronkan Merchant Center ke Vertex AI Search untuk retail, Anda akan menerima pesan error. Oleh karena itu, sebelum berhasil menyinkronkan Merchant Center ke Vertex AI Search untuk retail, Anda harus mengupgrade peran Anda.

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

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

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

Konsol

  1. Buka halaman Data> di konsol Penelusuran untuk Retail.

    Buka halaman Data
  2. Klik Impor untuk membuka panel Impor 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 Anda.
  6. Opsional: Pilih Filter feed Merchant Center untuk hanya mengimpor penawaran dari feed yang dipilih.

    Jika tidak ditentukan, penawaran dari semua feed akan diimpor (termasuk feed mendatang).
  7. Opsional: Untuk hanya mengimpor penawaran yang ditargetkan ke negara atau bahasa tertentu, luaskan Tampilkan Opsi Lanjutan, lalu pilih negara penjualan dan bahasa Merchant Center yang akan 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 memeriksa akun mana 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 produk. Jika tidak ditetapkan, semua bahasa akan diimpor.
    • FEED_LABEL: (OPSIONAL) Label feed produk yang ingin Anda impor. Anda dapat melihat label feed di Merchant Center di kolom produk Label Feed produk. Jika tidak ditetapkan, semua label feed akan diimpor.
    • FEED_FILTERS: (OPSIONAL) Daftar feed utama tempat produk akan diimpor. Jika tidak memilih feed, semua feed akun Merchant Center akan dibagikan. ID tersebut dapat ditemukan di referensi feed data 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 konsol Penelusuran untuk Retail, 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 tambahan dari panel ini.

Lihat Melihat informasi gabungan tentang katalog Anda untuk mengetahui petunjuk cara melihat produk yang telah diimpor.

Cantumkan penautan akun Merchant Center Anda.

Konsol

  1. Buka halaman Data> di konsol Penelusuran untuk Retail.

    Buka halaman Data

  2. Klik tombol Merchant Center di kanan atas halaman untuk membuka daftar akun Merchant Center 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"

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

Konsol

  1. Buka halaman Data> di konsol Penelusuran untuk Retail.

    Buka halaman Data

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

  3. Klik Batalkan tautan di samping akun Merchant Center yang ingin Anda batalkan tautannya, lalu konfirmasi pilihan Anda di 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 untuk menautkan 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 setiap sub-akun.

  • Impor pertama setelah menautkan akun Merchant Center mungkin memerlukan waktu berjam-jam untuk selesai. Durasi waktu ini bergantung pada jumlah penawaran di akun Merchant Center.

  • Semua perubahan produk yang menggunakan metode API 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 kosong untuk memastikan kebenaran data. Untuk menghapus produk dari cabang katalog, lihat Menghapus informasi produk.

Mengimpor data katalog dari Merchant Center

Merchant Center adalah alat yang dapat Anda gunakan untuk menyediakan data toko dan produk 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 konsol Penelusuran untuk Retail 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 menggunakan petunjuk di Transfer Merchant Center, siapkan transfer dari Merchant Center ke BigQuery.

    Anda akan menggunakan skema tabel produk Google Merchant Center. Konfigurasikan transfer untuk diulang setiap hari, tetapi konfigurasikan waktu habis masa berlaku set data Anda menjadi 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 Penelusuran untuk Retail.

      Buka halaman Data

    2. Klik Impor untuk membuka panel Impor.

    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 di 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.

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

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

    11. Klik Import.

    curl

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

      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. Kosongkan kolom ini 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 secara otomatis. Direktori ini dibuat di region yang sama dengan set data BigQuery, dan bersifat unik untuk setiap impor (yang mencegah beberapa tugas impor melakukan staging data 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 for retail schema untuk 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 pembuatan kueri data BigQuery.

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

Pandu saya

Untuk mengimpor katalog:

  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. Mengimpor data katalog ke Vertex AI Search untuk retail.

    Konsol

    1. Buka halaman Data> di konsol Penelusuran untuk Retail.

      Buka halaman Data
    2. Klik Impor untuk membuka panel Impor Data.
    3. Pilih Katalog produk.
    4. Pilih BigQuery sebagai sumber data Anda.
    5. Pilih cabang tempat Anda akan mengupload katalog.
    6. Pilih Retail Product Catalogs Schema. 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 di 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. Pelajari lebih lanjut tingkat produk. Mengubah tingkat produk setelah Anda mengimpor data apa pun memerlukan upaya yang signifikan.

      Penting: Anda tidak dapat mengaktifkan penelusuran untuk project dengan katalog produk yang telah diserap sebagai varian.
    10. Klik Import.

    curl

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

      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: ID project tempat sumber BigQuery berada. Jika tidak ditentukan, project ID akan diwarisi 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. Kosongkan kolom ini untuk membuat direktori sementara secara otomatis (direkomendasikan).
      • dataSchema: Untuk properti dataSchema, gunakan nilai product (default). Anda akan menggunakan skema Vertex AI Search untuk retail.

      Sebaiknya Anda tidak menentukan direktori staging atau error. Dengan begitu, bucket Cloud Storage dengan direktori staging dan error baru dapat dibuat secara otomatis. Direktori ini dibuat di region yang sama dengan set data BigQuery, dan bersifat unik untuk setiap impor (yang mencegah beberapa tugas impor melakukan staging data 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, yang 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, hingga 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"

      Saat operasi selesai, objek yang ditampilkan memiliki nilai done 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 di direktori error di Cloud Storage untuk melihat apakah error terjadi selama impor.

Menyiapkan akses ke set data BigQuery

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

  1. Buka halaman IAM di konsol Google Cloud.

    Buka halaman IAM

  2. Pilih project Vertex AI Search untuk retail Anda.

  3. Temukan akun layanan dengan nama Retail Service Account.

    Jika Anda belum memulai operasi impor sebelumnya, 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, service-525@gcp-sa-retail.iam.gserviceaccount.com).

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

  6. Untuk New principals, masukkan ID untuk akun layanan Vertex AI Search for retail, lalu pilih peran BigQuery > BigQuery User.

  7. Klik Add another role, lalu pilih BigQuery > BigQuery Data Editor.

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

  8. Klik Simpan.

Mengimpor data katalog dari Cloud Storage

Untuk mengimpor data katalog dalam format JSON, Anda membuat satu atau beberapa file JSON yang berisi data katalog yang ingin diimpor, lalu menguploadnya 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 dalam mengupload file ke Cloud Storage, lihat Mengupload objek.

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

    Akun layanan Vertex AI Search untuk retail tercantum di halaman IAM di konsol Google Cloud dengan nama Retail Service Account. Gunakan ID akun layanan, yang terlihat seperti alamat email (misalnya, service-525@gcp-sa-retail.iam.gserviceaccount.com), saat menambahkan akun ke izin bucket Anda.

  2. Mengimpor data katalog.

    Konsol

    1. Buka halaman Data> di konsol Penelusuran untuk Retail.

      Buka halaman Data
    2. Klik Impor untuk membuka panel Impor Data.
    3. Pilih Katalog produk sebagai sumber data Anda.
    4. Pilih cabang tempat Anda akan mengupload katalog.
    5. Pilih Retail Product Catalogs Schema sebagai skema.
    6. Masukkan lokasi Cloud Storage data Anda.
    7. Jika Anda tidak mengaktifkan penelusuran, pilih tingkat produk.

      Anda harus memilih tingkat produk jika ini adalah pertama kalinya Anda mengimpor katalog atau Anda mengimpor ulang katalog setelah menghapusnya. Pelajari lebih lanjut tingkat produk. Mengubah tingkat produk setelah Anda mengimpor data apa pun memerlukan upaya yang signifikan.

      Penting: Anda tidak dapat mengaktifkan penelusuran untuk 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 level produk.

      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: Satu atau beberapa 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, yang 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 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, mengganti kolom nama dengan nilai yang ditampilkan oleh metode impor, hingga 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]"

      Saat operasi selesai, objek yang ditampilkan memiliki nilai done 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 di direktori error di Cloud Storage untuk melihat jenis error yang terjadi selama impor.

Mengimpor data katalog secara inline

curl

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

Berikan seluruh produk dalam satu baris. Setiap produk harus berada di barisnya masing-masing.

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.

Berikan seluruh produk dalam satu baris. Setiap produk harus berada di barisnya masing-masing.

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 impor dan pengelolaan data katalog historis. Data katalog historis dapat membantu saat Anda menggunakan peristiwa pengguna historis untuk pelatihan model. Informasi produk sebelumnya dapat digunakan untuk memperkaya data peristiwa pengguna historis dan meningkatkan akurasi model.

Produk historis disimpan sebagai produk yang sudah tidak berlaku. Data ini tidak ditampilkan dalam respons penelusuran, tetapi dapat dilihat oleh panggilan API Update, List, dan Delete.

Mengimpor data katalog historis

Jika kolom expireTime produk ditetapkan ke stempel waktu mantan, produk ini dianggap sebagai produk historis. Tetapkan ketersediaan produk ke OUT_OF_STOCK untuk menghindari dampak pada rekomendasi.

Sebaiknya gunakan metode berikut untuk mengimpor data katalog historis:

Memanggil metode Product.Create

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

Mengimpor produk yang sudah tidak berlaku secara inline

Langkah-langkahnya sama dengan impor inline, kecuali produk harus memiliki kolom expireTime yang ditetapkan ke stempel waktu terdahulu.

Berikan seluruh produk dalam satu baris. Setiap produk harus berada di barisnya masing-masing.

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

Mengimpor produk yang sudah tidak berlaku dari BigQuery atau Cloud Storage

Gunakan prosedur yang sama 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 mendapatkan hasil terbaik, katalog Anda harus berisi informasi terbaru. Sebaiknya impor katalog Anda setiap hari untuk memastikan katalog Anda sudah yang terbaru. Anda dapat menggunakan Google Cloud Scheduler untuk menjadwalkan impor, atau memilih opsi penjadwalan otomatis saat mengimpor data menggunakan Konsol Google Cloud.

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

Untuk memperbarui satu item, lihat Memperbarui informasi produk.

Update massal

Anda dapat menggunakan metode impor untuk memperbarui katalog secara massal. Anda melakukannya dengan cara yang sama seperti melakukan impor awal; ikuti langkah-langkah di Mengimpor data katalog.

Memantau kondisi impor

Untuk memantau penyerapan dan kondisi katalog:

  1. Lihat informasi gabungan tentang katalog Anda dan lihat pratinjau produk yang diupload di tab Katalog di halaman Telusuri Data Retail.

    Buka halaman Data

  2. Evaluasi 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 Memanfaatkan 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 dengan upload data, ikuti prosedur di Menyiapkan pemberitahuan Cloud Monitoring.

    Memperbarui katalog Anda adalah hal yang penting untuk mendapatkan hasil berkualitas tinggi. Gunakan pemberitahuan untuk memantau tingkat error impor dan mengambil tindakan jika diperlukan.

Langkah selanjutnya