Mengimpor peristiwa pengguna historis

Halaman ini menjelaskan cara mengimpor data peristiwa pengguna dari peristiwa sebelumnya secara massal.

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 diturunkan. Hanya impor peristiwa pengguna untuk dokumen yang sudah Anda impor ke penyimpanan data.

Jika suatu peristiwa memiliki dokumen yang tercantum di userEvents.Documents, Gemini Enterprise akan otomatis menggabungkan peristiwa dengan dokumen tersebut. Penggabungan memungkinkan Gemini Enterprise 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).

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

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 untuk mengarahkan ke bucket Cloud Storage Anda.gcsSource

    {
"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 Gemini Enterprise dapat membuat direktori sementara secara otomatis.

  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 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) dan klik Grant Access.
  8. Untuk New principals, masukkan ID untuk akun layanan dan 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

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"