Mengimpor peristiwa pengguna historis

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

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 mencantumkan dokumen di userEvents.Documents, maka Gemini Enterprise akan otomatis bergabung ke acara tersebut dengan dokumen itu. Penggabungan memungkinkan Gemini Enterprise mengatribusikan 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 beberapa 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. 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 untuk peristiwa pengguna, lihat userEvents dalam referensi API.

Sebelum memulai

Sebelum Anda 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 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 dalam satu barisnya sendiri, tanpa jeda baris. Untuk representasi JSON untuk peristiwa pengguna, lihat userEvents dalam 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 Gemini Enterprise 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 Anda, 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 Grant Access.
  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

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.