Mengimpor informasi katalog

Halaman ini menjelaskan cara mengimpor informasi katalog dan terus memperbaruinya.

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

Video tutorial

Tonton video ini untuk mempelajari cara mengimpor katalog menggunakan Retail API.

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 dalam 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 Admin Retail 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 terpengaruh.

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

• Pastikan untuk membedakan produk utama dan produk varian dengan cermat. Sebelum mengupload data apa pun, lihat Tingkat produk.

  • Mengubah konfigurasi tingkat produk setelah berupaya keras mengimpor data. Item utama—bukan item varian—ditampilkan sebagai hasil penelusuran atau rekomendasi.

  • Contoh: Jika grup SKU utama adalah Kaus V-neck, maka model rekomendasi akan menampilkan kaus V-neck, dan mungkin, kaus crew-neck dan scoop-neck. Namun, jika varian tidak digunakan dan setiap SKU adalah yang utama, maka setiap kombinasi warna atau ukuran kemeja V-neck akan ditampilkan sebagai item yang berbeda di panel rekomendasi: Kemeja V-neck cokelat, ukuran XL, Kemeja V-neck cokelat, ukuran L, hingga Kemeja V-neck putih, ukuran M, Kemeja V-neck putih, ukuran S.

  • Koleksi dapat dikenali bersama selama ID varian panjang disertakan bersama dengan ID produk utama di collectionMemberIds[]. Hal ini menyebabkan kumpulan produk, yang mungkin telah dibeli satu atau beberapa produknya oleh pengguna dalam set, dicatat dalam peristiwa pengguna, dengan mengatribusikan seluruh set ke pembelian. Hal ini memfasilitasi penayangan produk lain dalam koleksi tertentu kepada pengguna yang sama dalam kueri terkait di masa mendatang.

  • Contoh: Pengguna sebelumnya membeli sarung duvet, sehingga produk yang cocok dalam koleksi seprai, seperti sarung bantal, akan ditampilkan.

• 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 informasi katalog yang diperlukan disertakan dan benar. Jangan gunakan nilai placeholder.

• Sertakan sebanyak mungkin informasi katalog opsional.

• Pastikan semua peristiwa Anda menggunakan satu mata uang, terutama jika Anda berencana menggunakan konsolGoogle Cloud untuk mendapatkan metrik pendapatan. API Vertex AI Search untuk commerce tidak mendukung penggunaan beberapa mata uang per katalog.

• Perbarui katalog Anda, sebaiknya setiap hari. Menjadwalkan impor katalog berkala mencegah kualitas model menurun seiring waktu. Anda dapat menjadwalkan impor otomatis dan berulang saat mengimpor katalog menggunakan konsol Search for commerce. Atau, Anda dapat menggunakan Google Cloud Scheduler untuk mengotomatiskan impor.

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

• Setelah mengimpor informasi katalog, tinjau informasi pelaporan error dan logging untuk project Anda. Jika Anda menemukan lebih dari beberapa error, tinjau error tersebut dan perbaiki masalah proses yang menyebabkan error.

Tentang mengimpor data katalog

Anda dapat mengimpor data produk dari BigQuery atau menentukan data secara inline dalam permintaan. Setiap prosedur ini adalah impor satu kali, kecuali penautan Merchant Center. Jadwalkan impor katalog reguler (sebaiknya setiap hari) untuk memverifikasi bahwa katalog Anda sudah terbaru.

Lihat Memastikan katalog Anda selalu ter-update.

Anda juga dapat mengimpor item produk satu per satu. Untuk mengetahui informasi selengkapnya, lihat Mengupload produk.

Pertimbangan impor katalog

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

Struktur data produk untuk penyerapan katalog

Bagian ini menjelaskan cara menyiapkan data produk untuk penyerapan katalog.

Produk utama

Produk utama berfungsi sebagai penampung untuk mengelompokkan produk varian dan sebagai entri dalam petak penelusuran. Hanya atribut umum yang dibagikan di seluruh varian yang ditentukan untuk produk utama. Fitur tersebut meliputi:

• ID produk utama
• ID Produk (sama dengan ID produk utama)
• Judul
• Deskripsi

Produk varian

Produk varian mewarisi atribut umum dari produk utama, tetapi juga dapat menentukan nilai unik.

Atribut wajib mencakup:

• Semua atribut yang ditentukan untuk produk utama (judul, deskripsi). Harga, judul, dan deskripsi dapat berbeda dari produk utama.
• Atribut varian tertentu (warna, ukuran, dan variasi produk lainnya yang relevan).

Pengambilan atribut

Proses pengambilan mempertimbangkan semua atribut yang dapat ditelusuri untuk produk utama dan varian.

Penskoran relevansi

Pemberian skor relevansi hanya didasarkan pada kolom judul dan deskripsi. Untuk menjaga perbedaan yang tepat, ubah sedikit varian dari judul produk utama (misalnya, Nama Produk + Warna).

Pencocokan varian di hasil penelusuran

Pencocokan varian (misalnya, gaun biru) memfilter hasil berdasarkan atribut varian yang telah ditentukan sebelumnya seperti warna dan ukuran. Hasil penelusuran menampilkan hingga lima varian yang cocok untuk setiap produk utama.

Menghapus permanen cabang katalog

Jika Anda mengimpor data katalog baru ke cabang yang ada, penting agar cabang katalog kosong untuk menjaga integritas data yang diimpor ke cabang. Jika cabang kosong, Anda dapat mengimpor data katalog baru, dan menautkan cabang ke akun penjual.

Jika Anda menayangkan prediksi langsung atau traffic penelusuran dan berencana menghapus cabang default, pertimbangkan untuk menentukan cabang lain sebagai default terlebih dahulu sebelum menghapus. Karena cabang default akan menampilkan hasil kosong setelah dihapus, menghapus cabang default aktif dapat menyebabkan gangguan.

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

1. Buka halaman Data> di konsol Search for Commerce.
   
   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 di daftar Katalog produk di jendela Status aktivitas.

Menyinkronkan Merchant Center ke Vertex AI Search untuk commerce

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

Untuk sinkronisasi berkelanjutan antara Merchant Center dan Vertex AI Search untuk commerce, Anda dapat menautkan akun Merchant Center ke Vertex AI Search untuk commerce.

Saat menyiapkan sinkronisasi Merchant Center untuk Vertex AI Search untuk commerce, Anda harus memiliki peran IAM Admin yang ditetapkan di Merchant Center. Meskipun peran akses Standar akan mengizinkan Anda membaca feed Merchant Center, saat Anda mencoba menyinkronkan Merchant Center ke Vertex AI Search untuk commerce, Anda akan mendapatkan pesan error. Jadi, sebelum Anda dapat berhasil menyinkronkan Merchant Center ke Vertex AI Search untuk commerce, tingkatkan peran Anda.

Menautkan akun Merchant Center Anda

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

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

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

Menyinkronkan akun Merchant Center Anda

Untuk melihat Merchant Center tertaut, buka halaman Data di konsol penelusuran untuk e-commerce, 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.

Mencantumkan penautan akun Merchant Center Anda

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 Anda

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

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 masing-masing sub-akun.

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

• Setiap modifikasi produk 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. Kemudian, perubahan tersebut akan otomatis disinkronkan ke Vertex AI Search untuk commerce.

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

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

Mengimpor data katalog dari Merchant Center

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 e-commerce 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. Konfigurasi transfer Anda agar berulang setiap hari, tetapi konfigurasi waktu habis masa berlaku set data Anda pada 2 hari.

2. Jika set data BigQuery Anda berada di project lain, konfigurasi izin yang diperlukan agar Vertex AI Search untuk e-commerce dapat mengakses set data BigQuery. Pelajari lebih lanjut.

3. Impor data katalog Anda dari BigQuery ke Vertex AI Search untuk e-commerce.

   Cloud Console

   1. Buka halaman Data> di konsol Search for Commerce.
      
      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 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 Admin Retail. Pelajari lebih lanjut level 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. Kosongkan kolom ini 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 penyiapan atau error, sehingga bucket Cloud Storage dengan direktori penyiapan dan error baru dapat dibuat secara otomatis. Direktori ini dibuat di region yang sama dengan set data BigQuery, dan unik untuk setiap impor (yang mencegah beberapa tugas impor melakukan penyiapan 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 ID project, 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 penyiapan 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 skema Vertex AI Search untuk e-commerce 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 commerce.

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 di project lain, konfigurasi izin yang diperlukan agar Vertex AI Search untuk e-commerce dapat mengakses set data BigQuery. Pelajari lebih lanjut.

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

   Cloud Console

   1. Buka halaman Data> di konsol Search for Commerce.
      
      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 Skema Katalog Produk Retail. Ini adalah skema Produk untuk Vertex AI Search untuk commerce.
   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 level 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 di-ingest sebagai varian.
   10. Klik Import.

   curl

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

      • ingestionProductType: Mendukung nilai primary (default) dan variant.
      • merchantCenterProductIdField: Mendukung nilai offerId dan itemGroupId. Jika Anda tidak menggunakan Merchant Center, Anda tidak perlu menyetel 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 impor.

      Gunakan objek BigQuerySource untuk mengarahkan 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. Kosongkan kolom ini 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 skema Vertex AI Search untuk commerce.

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

      Setelah 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 terjadi error selama pengimporan.

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 Commerce, selesaikan langkah-langkah berikut.

1. Buka halaman IAM di konsol Google Cloud .

   Buka halaman IAM

2. Pilih project Vertex AI Search untuk commerce Anda.

3. Temukan akun layanan dengan nama Retail Service Account.

   Jika Anda belum pernah 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 kesalahan 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. Beralih ke project BigQuery Anda (di halaman IAM & Admin yang sama) lalu klik person_add Grant Access.

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

7. Klik Add another role, lalu 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 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 commerce.

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 untuk e-commerce memiliki izin untuk membaca dan menulis ke bucket.

   Akun layanan Vertex AI Search untuk e-commerce 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. Impor data katalog Anda.

   Cloud Console

   1. Buka halaman Data> di konsol Search for Commerce.
      
      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 level 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 di-ingest sebagai varian.
   8. 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. Pelajari lebih lanjut level produk.

      • ingestionProductType: Mendukung nilai primary (default) dan variant.
      • merchantCenterProductIdField: Mendukung nilai offerId dan itemGroupId. Jika Anda tidak menggunakan Merchant Center, Anda tidak perlu menyetel 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 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 atau 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 direktori error tidak ada, direktori tersebut 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 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]"

      Setelah 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

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

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.

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

Kolom wajib diisi minimum:

  {
    "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 commerce mendukung pengimporan dan pengelolaan data katalog historis. Data katalog historis dapat berguna 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 terlihat oleh panggilan API Update, List, dan Delete.

Mengimpor data katalog historis

Jika kolom expireTime produk ditetapkan ke stempel waktu lampau, 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.
• Mengimpor produk yang sudah tidak berlaku secara inline.
• Mengimpor produk yang sudah habis masa berlakunya dari BigQuery.

Panggil metode Product.Create

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

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

Cantumkan 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 habis masa berlakunya 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 menyetel kolom expireTime ke stempel waktu sebelumnya.

Memastikan katalog Anda selalu yang terbaru

Untuk mendapatkan hasil terbaik, katalog Anda harus berisi informasi terkini. Sebaiknya impor katalog Anda setiap hari untuk memastikan katalog Anda selalu terbaru. Anda dapat menggunakan Google Cloud Scheduler untuk menjadwalkan impor, atau memilih opsi penjadwalan otomatis saat mengimpor data menggunakan konsolGoogle 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 batch

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

Memantau kondisi impor

Untuk memantau penyerapan dan kualitas katalog:

1. Lihat informasi gabungan tentang katalog Anda dan pratinjau produk yang diupload di tab Katalog pada halaman Data Penelusuran untuk e-commerce.

   Buka halaman Data

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

   Memastikan katalog Anda selalu ter-update penting untuk mendapatkan hasil berkualitas tinggi. Gunakan pemberitahuan untuk memantau tingkat error impor dan mengambil tindakan jika diperlukan.

Langkah berikutnya

• Mulai merekam peristiwa pengguna.
• Melihat informasi gabungan tentang katalog Anda.
• Siapkan pemberitahuan upload data.