Importa eventos históricos de usuarios

En esta página, se describe cómo importar datos de eventos de usuario de forma masiva desde eventos anteriores.

Para conocer los tipos de eventos de usuario que puedes importar, consulta el eventType campo del userEvents objeto. Si importas eventos de usuario, puedes mejorar la calidad de tus resultados. Por ejemplo, los eventos de usuario afectan la clasificación de los resultados de la búsqueda. Los resultados con tasas de clics más altas se potencian, mientras que los resultados con tasas de clics más bajas se ocultan. Solo importa eventos de usuario para los documentos que ya importaste a tu almacén de datos.

Si un evento tiene documentos enumerados en userEvents.Documents, Gemini Enterprise une automáticamente los eventos con ese documento. La unión permite que Gemini Enterprise atribuya eventos como clics y vistas al documento correcto en un resultado de la búsqueda o una recomendación. En el caso de las apps de búsqueda y recomendaciones personalizadas, la unión se produce de forma asíncrona, es decir, los eventos de usuario se unen a los documentos después de que se completa la importación por lotes (lo que suele ocurrir en cuestión de minutos).

Si usas una app de búsqueda con varios almacenes de datos adjuntos, importa eventos de usuario a nivel de la ubicación en lugar de a nivel del almacén de datos. Esto permite que un evento de usuario determinado se envíe al almacén de datos con el que está asociado. Cuando importes eventos de usuario a nivel de la ubicación, incluye el campo engine en el evento de usuario para asociar el evento con la app correcta. Para ver ejemplos de eventos de usuario que incluyen el campo engine, consulta lo siguiente:

Para obtener más información sobre el método de importación, consulta userEvents.import.

Para importar eventos de usuario en tiempo real, consulta Registra eventos de usuario en tiempo real.

Puedes importar eventos históricos de las siguientes maneras:

Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la referencia de la API.

Antes de comenzar

Antes de importar eventos de usuario, haz lo siguiente:

Importa eventos históricos de usuario desde Cloud Storage

REST

Para importar eventos históricos de usuario de forma masiva desde Cloud Storage, sigue estos pasos:

  1. Crea uno o más archivos de datos para los parámetros de entrada de la importación. Usa el gcsSource objeto para que apunte a tu bucket de Cloud Storage.

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

    Reemplaza lo siguiente:

    • INPUT_FILE: Es un archivo en Cloud Storage que contiene los datos de eventos de tu usuario. Asegúrate de que cada evento de usuario esté en su propia línea única, sin saltos de línea. Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la referencia de la API. Los campos del archivo de entrada deben tener este formato: gs://<bucket>/<path-to-file>/.
    • ERROR_DIRECTORY: Es opcional. Es un directorio de Cloud Storage para obtener información sobre los errores de la importación, por ejemplo, gs://<your-gcs-bucket>/directory/import_errors. Google recomienda dejar este campo vacío para que Gemini Enterprise cree automáticamente un directorio temporal.

  2. Para importar tus eventos, realiza una solicitud POST al userEvents.import método y proporciona el nombre del archivo de datos.

    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"

Importa eventos históricos de usuario desde BigQuery

Cuando crees tablas para eventos de usuario en BigQuery, usa los esquemas que se documentan en Acerca de los eventos de usuario para apps personalizadas. Cada evento de usuario search debe incluir un campo engine para asociar el evento con una app. Para obtener más información, consulta engine.

Configura el acceso a BigQuery

Si tu conjunto de datos de BigQuery está en un proyecto diferente al de tu almacén de datos, sigue estos pasos para configurar el acceso a BigQuery.

  1. Abre la página IAM y administración en la Google Cloud consola de.
  2. Selecciona el proyecto que contiene el almacén de datos al que deseas importar eventos de usuario.
  3. Selecciona la casilla de verificación Incluir asignaciones de funciones proporcionadas por Google.
  4. Busca la cuenta de servicio con el nombre Cuenta de servicio de Discovery Engine.
  5. Si no iniciaste una operación de importación con Discovery Engine, es posible que esta cuenta de servicio no aparezca en la lista. Si no ves esta cuenta de servicio, regresa a la tarea de importación para iniciar la importación. Cuando falle debido a errores de permisos, regresa aquí y completa esta tarea. Se mostrará la cuenta de servicio de Discovery Engine.
  6. Copia el identificador para la cuenta de servicio, que se parece a una dirección de correo electrónico, por ejemplo, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
  7. Cambia a tu proyecto de BigQuery (en la misma página IAM y administración) y haz clic en Otorgar acceso.
  8. En Principales nuevos, ingresa el identificador de la cuenta de servicio y selecciona la función BigQuery > Visualizador de datos de BigQuery.
  9. Haz clic en Guardar.

Para obtener más información sobre el acceso a BigQuery, consulta Controla el acceso a los conjuntos de datos en la documentación de BigQuery.

Importa eventos desde BigQuery

REST

Para importar eventos históricos de usuario de forma masiva desde BigQuery, sigue estos pasos:

  1. Para importar tus eventos de usuario, realiza una solicitud POST al userEvents.import método y proporciona el nombre del proyecto de BigQuery, el ID del conjunto de datos y el ID de la tabla.

    Cuando importes tus eventos, usa el valor user_event para 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"
      }
    }'

Importa eventos históricos de usuario como datos JSON locales

Puedes importar eventos de usuario incluyendo datos JSON locales para los eventos en tu llamada al userEvents.import método.

Para colocar datos de eventos de usuario en un archivo JSON y especificar el archivo en una solicitud a la API, sigue estas instrucciones:

  1. Crea un archivo JSON que contenga los datos de eventos de tu usuario. Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la documentación de referencia de la API.

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

  2. Para importar tus eventos, realiza una solicitud POST al userEvents.import método y proporciona el nombre del archivo de datos.

    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"