Mengimpor peristiwa pengguna historis

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

Untuk jenis peristiwa pengguna yang dapat Anda impor, lihat kolom eventType dari objek userEvents. Dengan mengimpor peristiwa pengguna, Anda dapat meningkatkan kualitas hasil Anda. Misalnya, peristiwa pengguna memengaruhi peringkat hasil penelusuran. Hasil dengan rasio klik-tayang yang lebih tinggi akan dipromosikan, sementara hasil dengan rasio klik-tayang yang lebih rendah akan disembunyikan. Hanya impor peristiwa pengguna untuk dokumen yang sudah diimpor ke penyimpanan data Anda.

Jika suatu acara memiliki dokumen yang tercantum di userEvents.Documents, maka Aplikasi AI akan otomatis bergabung ke acara dengan dokumen tersebut. Bergabung memungkinkan Aplikasi AI mengatribusikan peristiwa seperti klik dan penayangan ke dokumen yang benar dalam hasil penelusuran atau rekomendasi. Untuk aplikasi penelusuran dan rekomendasi kustom, penggabungan terjadi secara asinkron, yaitu peristiwa pengguna digabungkan ke dokumen setelah impor batch selesai (biasanya terjadi dalam beberapa menit). Untuk aplikasi media, penggabungan terjadi secara sinkron, Aplikasi AI 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.

Jika Anda menggunakan aplikasi penelusuran dengan beberapa penyimpanan data terlampir, impor peristiwa pengguna di tingkat lokasi, bukan tingkat penyimpanan data. Hal ini memungkinkan peristiwa pengguna tertentu dikirim ke penyimpanan data yang terkait dengannya. Untuk mengimpor peristiwa pengguna dengan dokumen dari dataStores yang berbeda di tingkat lokasi, bukan tingkat penyimpanan data, lihat userEvents.import.

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

Anda dapat mengimpor peristiwa historis dengan cara berikut:

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

Sebelum memulai

Sebelum Anda mengimpor 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:

  1. Di konsol Google Cloud , buka halaman AI Applications.

    Aplikasi AI

  2. Di halaman Aplikasi, klik aplikasi media Anda.

  3. Buka halaman Data.

    Untuk aplikasi rekomendasi media, tab Persyaratan menampilkan dokumen media dan peristiwa pengguna yang perlu Anda impor.

  4. Klik tab Events. Jika Anda telah mengimpor peristiwa, informasi tentang peristiwa tersebut ditampilkan di tab ini.

  5. Klik Impor acara.

  6. Pilih Cloud Storage sebagai sumber data Anda.

  7. Masukkan atau pilih lokasi Cloud Storage untuk peristiwa pengguna Anda.

  8. Klik Import.

  9. Tab Aktivitas menampilkan status impor Anda.

  10. Jika terjadi error impor, di tab Aktivitas:

    1. Perluas error di kolom Detail, lalu klik Lihat detail untuk melihat informasi selengkapnya di panel Detail log aktivitas.

    2. Di panel Detail log aktivitas, klik Lihat log error lengkap untuk melihat error di Logs Explorer.

REST

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

  1. Buat satu atau beberapa file data untuk parameter input impor. Gunakan objek gcsSource untuk mengarahkan ke bucket Cloud Storage Anda.

    {
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}

    Ganti kode berikut:

    • INPUT_FILE: file di Cloud Storage yang berisi data peristiwa pengguna. Pastikan setiap peristiwa pengguna berada di satu barisnya sendiri, tanpa jeda baris. Untuk representasi JSON untuk peristiwa pengguna, lihat userEvents di referensi API. Kolom file input harus dalam format ini: gs://<bucket>/<path-to-file>/.
    • ERROR_DIRECTORY: optional. Direktori Cloud Storage untuk informasi error tentang impor—misalnya, gs://<your-gcs-bucket>/directory/import_errors. Google merekomendasikan agar Anda mengosongkan kolom ini agar Aplikasi AI dapat membuat direktori sementara secara otomatis.

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

    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/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    Jika Anda mengimpor peristiwa pengguna di tingkat lokasi, gunakan endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Mengimpor peristiwa pengguna historis dari BigQuery

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

Menyiapkan akses BigQuery

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

  1. Buka halaman IAM & Admin di konsol Google Cloud .
  2. Pilih project yang berisi penyimpanan data tempat Anda ingin mengimpor peristiwa pengguna.
  3. Centang kotak Include Google-provided role grants.
  4. Temukan akun layanan dengan nama Discovery Engine Service Account.
  5. Jika Anda belum pernah 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.
  6. Salin ID untuk akun layanan, yang terlihat seperti alamat email—misalnya, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
  7. Beralih ke project BigQuery Anda (di halaman IAM & Admin yang sama) lalu klik Berikan Akses.
  8. Untuk New principals, masukkan ID akun layanan dan pilih peran BigQuery > BigQuery Data Viewer.
  9. Klik Simpan.

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

Mengimpor peristiwa dari BigQuery

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

Konsol

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

  1. Di konsol Google Cloud , buka halaman AI Applications.

    Aplikasi AI

  2. Di halaman Aplikasi, klik aplikasi media Anda.

  3. Buka halaman Data.

    Untuk aplikasi rekomendasi media, tab Persyaratan menampilkan dokumen media dan peristiwa pengguna yang perlu Anda impor.

  4. Klik tab Events. Jika Anda telah mengimpor peristiwa, informasi tentang peristiwa tersebut ditampilkan di tab ini.

  5. Klik Impor acara.

  6. Pilih BigQuery sebagai sumber data Anda.

  7. Masukkan atau pilih jalur BigQuery untuk peristiwa pengguna Anda.

  8. Klik Import.

  9. Tab Aktivitas menampilkan status impor Anda.

  10. Jika terjadi error impor, di tab Aktivitas:

    1. Perluas error di kolom Detail, lalu klik Lihat detail untuk melihat informasi selengkapnya di panel Detail log aktivitas.

    2. Di panel Detail log aktivitas, klik Lihat log error lengkap untuk melihat error di Logs Explorer.

REST

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

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

    Saat mengimpor peristiwa, gunakan nilai user_event untuk dataSchema.

    curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1/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"
      }
    }'

    Jika Anda mengimpor peristiwa pengguna di tingkat lokasi, gunakan endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

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:

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

  2. Impor peristiwa Anda dengan membuat permintaan POST ke metode userEvents.import, dengan 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/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    Jika Anda mengimpor peristiwa pengguna di tingkat lokasi, gunakan endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.