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, mengimpor peristiwa pengguna tidak diperlukan. Namun, merekam peristiwa pengguna direkomendasikan untuk aplikasi penelusuran dan rekomendasi kustom.

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

Jika suatu peristiwa memiliki dokumen yang tercantum di userEvents.Documents, Agent Search akan otomatis menggabungkan peristiwa dengan dokumen tersebut. Penggabungan memungkinkan Agent Search mengaitkan peristiwa seperti klik dan tampilan 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 hitungan menit). Untuk aplikasi media, penggabungan terjadi secara sinkron, Agent 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.

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. Saat mengimpor peristiwa pengguna di tingkat lokasi, sertakan kolom engine dalam peristiwa pengguna untuk mengaitkan peristiwa dengan aplikasi yang benar. Untuk contoh peristiwa pengguna yang menyertakan kolom engine, lihat hal berikut:

Untuk mengetahui informasi selengkapnya tentang metode impor, 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 mengetahui representasi JSON untuk peristiwa pengguna, lihat userEvents di referensi API.

Sebelum memulai

Sebelum mengimpor peristiwa pengguna:

Mengimpor peristiwa pengguna historis dari Cloud Storage

Jika memiliki aplikasi media, Anda dapat mengimpor peristiwa pengguna menggunakan Google Cloud konsol 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 Google Cloud konsol, buka halaman AI Applications.

    AI Applications

  2. Di halaman Apps, klik aplikasi media Anda.

  3. Buka halaman Data.

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

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

  5. Klik Import events.

  6. Pilih Cloud Storage sebagai sumber data.

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

  8. Klik Import.

  9. Tab Activity menampilkan status impor Anda.

  10. Jika terjadi error impor, di tab Activity:

    1. Luaskan error di kolom Details , lalu 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:

  1. Buat satu atau beberapa file data untuk parameter input impor. Gunakan gcsSource objek untuk mengarah 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 Anda. Pastikan setiap peristiwa pengguna berada di barisnya sendiri, tanpa jeda baris. Untuk mengetahui representasi JSON untuk peristiwa pengguna, lihat userEvents di 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 Agent Search dapat otomatis membuat direktori sementara.

  2. Impor peristiwa Anda dengan membuat permintaan POST ke metode userEvents.import, yang 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/userEvents:import"

Mengimpor peristiwa pengguna historis dari BigQuery

Saat membuat tabel untuk peristiwa pengguna di BigQuery, gunakan skema yang didokumentasikan di Tentang peristiwa pengguna media dan Tentang peristiwa pengguna untuk aplikasi kustom. Setiap peristiwa pengguna search harus menyertakan kolom engine untuk mengaitkan peristiwa dengan aplikasi. Untuk mengetahui informasi selengkapnya, lihat engine.

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 Google Cloud konsol.
  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. Beralihlah ke project BigQuery Anda (di halaman IAM &Admin yang sama), lalu klik Grant Access.
  8. Untuk New principals, masukkan ID untuk akun layanan, lalu pilih peran BigQuery > BigQuery Data Viewer.
  9. Klik Save.

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 lainnya, Anda hanya dapat mengimpor menggunakan API.

Konsol

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

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

    AI Applications

  2. Di halaman Apps, klik aplikasi media Anda.

  3. Buka halaman Data.

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

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

  5. Klik Import events.

  6. Pilih BigQuery sebagai sumber data.

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

  8. Klik Import.

  9. Tab Activity menampilkan status impor Anda.

  10. Jika terjadi error impor, di tab Activity:

    1. Luaskan error di kolom Details , lalu 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 BigQuery, ikuti langkah-langkah berikut:

  1. Impor peristiwa pengguna Anda 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.

    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/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 userEvents.import metode.

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