Halaman ini diterjemahkan oleh Cloud Translation API.

Mengimpor peristiwa pengguna historis

Halaman ini menjelaskan cara mengimpor data peristiwa pengguna dari peristiwa sebelumnya secara massal. Peristiwa pengguna diperlukan untuk rekomendasi media. Jika Anda tidak menggunakan rekomendasi media, Anda tidak perlu mengimpor peristiwa pengguna. Namun, direkomendasikan untuk aplikasi penelusuran media.

Untuk jenis peristiwa pengguna yang dapat Anda impor, lihat kolom eventType objek userEvents. Dengan mengimpor peristiwa pengguna, Anda dapat meningkatkan kualitas rekomendasi serta peringkat hasil penelusuran. Hasil penelusuran dengan rasio klik-tayang yang lebih tinggi akan dioptimalkan, sedangkan hasil dengan rasio klik-tayang yang lebih rendah akan disembunyikan. Jangan mengimpor peristiwa pengguna untuk dokumen yang belum Anda impor.

Jika peristiwa memiliki dokumen yang tercantum di userEvents.Documents, Vertex AI Search akan otomatis menggabungkan peristiwa dengan dokumen tersebut. Penggabungan memungkinkan Vertex AI Search mengatribusikan peristiwa seperti klik dan tayangan ke dokumen yang benar dalam hasil penelusuran atau rekomendasi. Untuk aplikasi kasus penggunaan umum, penggabungan terjadi secara asinkron, yaitu, peristiwa pengguna digabungkan ke dokumen setelah impor batch selesai (umumnya terjadi dalam hitungan menit). Untuk aplikasi media, penggabungan terjadi secara sinkron, Vertex AI Search mulai menggabungkan peristiwa pengguna ke dokumen saat impor batch masih berlangsung. Untuk mengetahui cara melihat metrik peristiwa yang tidak digabungkan di konsol, lihat Melihat informasi peristiwa pengguna gabungan.

Untuk mengimpor peristiwa pengguna secara real-time, lihat Merekam peristiwa pengguna real-time.

Anda dapat mengimpor peristiwa historis dengan cara berikut:

Dari Cloud Storage
Dari BigQuery
Sebagai data JSON lokal

Untuk representasi JSON peristiwa pengguna, lihat userEvents dalam referensi API.

Sebelum memulai

Sebelum mengimpor peristiwa pengguna:

Buat penyimpanan data dan aplikasi.
Tinjau Tentang peristiwa pengguna untuk mengetahui persyaratan peristiwa pengguna.

Mengimpor peristiwa pengguna historis dari Cloud Storage

Jika memiliki aplikasi media, Anda dapat mengimpor peristiwa pengguna menggunakan konsol Google Cloud atau API. Untuk jenis aplikasi lainnya, Anda hanya dapat mengimpor menggunakan API.

Konsol

Untuk mengimpor peristiwa pengguna untuk aplikasi media menggunakan konsol, ikuti langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Agent Builder.

Agent Builder
Di halaman Aplikasi, klik aplikasi media Anda.
Buka halaman Data.

Untuk aplikasi rekomendasi media, tab Persyaratan menampilkan dokumen media dan peristiwa pengguna yang perlu Anda impor.
Klik tab Events. Jika Anda telah mengimpor peristiwa, informasi tentang peristiwa tersebut akan ditampilkan di tab ini.
Klik Impor acara.
Pilih Cloud Storage sebagai sumber data Anda.
Masukkan atau pilih lokasi Cloud Storage peristiwa pengguna Anda.
Klik Import.
Tab Aktivitas menampilkan status impor Anda.
Jika terjadi error impor, di tab Aktivitas:
1. Luaskan error di kolom Details dan klik View details untuk melihat informasi selengkapnya di panel Activity log details.
2. Di panel Activity log details, klik View full error logs untuk melihat error di Logs Explorer.

REST

Untuk mengimpor peristiwa pengguna historis secara massal dari Cloud Storage, ikuti langkah-langkah berikut:

Buat satu atau beberapa file data untuk parameter input untuk impor. Gunakan objek gcsSource untuk mengarah ke bucket Cloud Storage Anda.
```
{
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}
```
- INPUT_FILE: File di Cloud Storage yang berisi data peristiwa pengguna Anda. Pastikan setiap peristiwa pengguna berada di barisnya sendiri, tanpa jeda baris. Untuk representasi JSON peristiwa pengguna, lihat userEvents dalam referensi API. Kolom file input harus dalam format ini: gs://<bucket>/<path-to-file>/.
- ERROR_DIRECTORY: Opsional. Direktori Cloud Storage untuk informasi error tentang impor—misalnya, gs://<your-gcs-bucket>/directory/import_errors. Google merekomendasikan untuk mengosongkan kolom ini agar Vertex AI Agent Builder otomatis membuat direktori sementara.

Impor peristiwa Anda dengan membuat permintaan POST ke metode userEvents:import, yang memberikan nama file data.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl -X POST \
    -v \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

Mengimpor peristiwa pengguna historis dari BigQuery

Saat membuat tabel untuk peristiwa pengguna di BigQuery, gunakan skema yang didokumentasikan di Tentang peristiwa pengguna.

Menyiapkan akses BigQuery

Jika set data BigQuery Anda berada dalam project yang berbeda dengan penyimpanan data Anda, ikuti langkah-langkah berikut untuk menyiapkan akses ke BigQuery.

Buka halaman IAM & Admin di konsol Google Cloud.
Pilih project yang berisi penyimpanan data tempat Anda ingin mengimpor peristiwa pengguna.
Centang kotak Include Google-provided role grants.
Temukan akun layanan dengan nama Akun Layanan Discovery Engine.
Jika Anda belum memulai operasi impor dengan Discovery Engine, 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. Akun layanan Discovery Engine akan tercantum.
Salin ID untuk akun layanan, yang terlihat seperti alamat email—misalnya, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
Beralihlah ke project BigQuery Anda (di halaman IAM & Admin yang sama) dan klik Berikan Akses.
Untuk New principals, masukkan ID untuk akun layanan dan pilih peran BigQuery > BigQuery Data Viewer.
Klik Simpan.

Untuk mengetahui informasi selengkapnya tentang akses BigQuery, lihat artikel Mengontrol akses ke set data dalam dokumentasi BigQuery.

Mengimpor peristiwa dari BigQuery

Jika memiliki aplikasi media, Anda dapat mengimpor peristiwa pengguna menggunakan konsol Google Cloud atau API. Untuk jenis aplikasi lainnya, Anda hanya dapat mengimpor menggunakan API.

Konsol

Untuk mengimpor peristiwa pengguna untuk aplikasi media menggunakan konsol, ikuti langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Agent Builder.

Agent Builder
Di halaman Aplikasi, klik aplikasi media Anda.
Buka halaman Data.

Untuk aplikasi rekomendasi media, tab Persyaratan menampilkan dokumen media dan peristiwa pengguna yang perlu Anda impor.
Klik tab Events. Jika Anda telah mengimpor peristiwa, informasi tentang peristiwa tersebut akan ditampilkan di tab ini.
Klik Impor acara.
Pilih BigQuery sebagai sumber data Anda.
Masukkan atau pilih jalur BigQuery untuk peristiwa pengguna Anda.
Klik Import.
Tab Aktivitas menampilkan status impor Anda.
Jika terjadi error impor, di tab Aktivitas:
1. Luaskan error di kolom Details dan klik View details untuk melihat informasi selengkapnya di panel Activity log details.
2. Di panel Activity log details, klik View full error logs untuk melihat error di Logs Explorer.

REST

Untuk mengimpor peristiwa pengguna historis secara massal dari Cloud Storage, ikuti langkah-langkah berikut:

Impor peristiwa pengguna dengan membuat permintaan POST ke metode userEvents:import, yang memberikan nama project BigQuery, ID set data, dan ID tabel.

Saat mengimpor peristiwa, gunakan nilai user_event untuk dataSchema.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

Mengimpor peristiwa pengguna historis sebagai data JSON lokal

Anda dapat mengimpor peristiwa pengguna dengan menyertakan data JSON lokal untuk peristiwa dalam panggilan ke metode userEvents:import.

Untuk memasukkan data peristiwa pengguna ke dalam file JSON dan menentukan file dalam permintaan API, ikuti petunjuk berikut:

Buat file JSON yang berisi data peristiwa pengguna Anda. Untuk representasi JSON untuk peristiwa pengguna, lihat userEvents dalam dokumentasi referensi API.

{
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

Impor peristiwa Anda dengan membuat permintaan POST ke metode userEvents:import, yang memberikan nama file data.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"