Importar historial de eventos de usuario

En esta página se describe cómo importar datos de eventos de usuario de eventos anteriores de forma masiva. Los eventos de usuario son obligatorios para las aplicaciones multimedia. Si no usas aplicaciones multimedia, no es necesario que importes eventos de usuario. Sin embargo, se recomienda registrar eventos de usuario en las aplicaciones de búsqueda personalizada y de recomendaciones.

Para ver los tipos de eventos de usuario que puede importar, consulte el campo eventType del objeto userEvents. Si importa eventos de usuario, puede mejorar la calidad de sus resultados. Por ejemplo, los eventos de usuario influyen en la clasificación de los resultados de búsqueda. Los resultados con porcentajes de clics más altos se impulsan, mientras que los que tienen porcentajes de clics más bajos se ocultan. Importa solo los eventos de usuario de los documentos que ya hayas importado a tu almacén de datos.

Si un evento tiene documentos en userEvents.Documents, las aplicaciones de IA se unirán automáticamente a los eventos con ese documento. Al unirse, las aplicaciones de IA pueden atribuir eventos como clics y visualizaciones al documento correcto en un resultado de búsqueda o una recomendación. En el caso de las aplicaciones 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 una vez que se ha completado la importación por lotes (lo que suele ocurrir en cuestión de minutos). En el caso de las aplicaciones multimedia, la unión se produce de forma síncrona. Las aplicaciones de IA empiezan a unir eventos de usuario a documentos mientras la importación por lotes sigue en curso. Para saber cómo ver las métricas de eventos no unidos en la consola, consulta Ver información agregada de eventos de usuario.

Si usa una aplicación de búsqueda con varios almacenes de datos adjuntos, importe los eventos de usuario a nivel de ubicación en lugar de a nivel de almacén de datos. De esta forma, se puede enviar un evento de usuario determinado al almacén de datos al que esté asociado. Para importar eventos de usuario con documentos de diferentes dataStores a nivel de ubicación en lugar de a nivel de almacén de datos, consulta userEvents.import.

Para importar eventos de usuario en tiempo real, consulte Registrar eventos de usuario en tiempo real.

Puede importar eventos históricos de las siguientes formas:

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

Antes de empezar

Antes de importar eventos de usuario:

Importar historial de eventos de usuario desde Cloud Storage

Si tienes una aplicación multimedia, puedes importar eventos de usuario mediante la Google Cloud consola o la API. En el caso de otros tipos de aplicaciones, solo puede importar datos mediante la API.

Consola

Para importar eventos de usuario de aplicaciones multimedia mediante la consola, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Aplicaciones de IA.

    Aplicaciones de IA

  2. En la página Aplicaciones, haz clic en tu aplicación multimedia.

  3. Ve a la página Datos.

    En las aplicaciones de recomendaciones de contenido multimedia, la pestaña Requisitos muestra los documentos multimedia y los eventos de usuario que debe importar.

  4. Haga clic en la pestaña Eventos. Si ya ha importado algún evento, la información sobre él se muestra en esta pestaña.

  5. Haz clic en Importar eventos.

  6. Selecciona Cloud Storage como fuente de datos.

  7. Introduzca o seleccione la ubicación de Cloud Storage de sus eventos de usuario.

  8. Haz clic en Importar.

  9. En la pestaña Actividad se muestra el estado de la importación.

  10. Si se producen errores de importación, en la pestaña Actividad:

    1. Despliega el error en la columna Detalles y haz clic en Ver detalles para ver más información en el panel Detalles del registro de actividad.

    2. En el panel Detalles del registro de actividad, haz clic en Ver registros de errores completos para ver el error en Explorador de registros.

REST

Para importar de forma masiva el historial de eventos de usuario de Cloud Storage, sigue estos pasos:

  1. Crea uno o varios archivos de datos para los parámetros de entrada de la importación. Usa el objeto gcsSource para dirigirte a tu segmento de Cloud Storage.

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

    Haz los cambios siguientes:

    • INPUT_FILE: un archivo de Cloud Storage que contiene los datos de eventos de usuario. Asegúrate de que cada evento de usuario esté en una sola línea, sin saltos de línea. Para ver la representación JSON de los eventos de usuario, consulte userEvents en la referencia de la API. Los campos del archivo de entrada deben tener este formato: gs://<bucket>/<path-to-file>/.
    • ERROR_DIRECTORY: opcional. Un directorio de Cloud Storage con información sobre errores de la importación, por ejemplo, gs://<your-gcs-bucket>/directory/import_errors. Google recomienda dejar este campo vacío para que las aplicaciones de IA creen automáticamente un directorio temporal.

  2. Para importar eventos, haz una solicitud POST al método userEvents.import 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/dataStores/DATA_STORE_ID/userEvents:import"

    Si va a importar eventos de usuario a nivel de ubicación, utilice el endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importar historial de eventos de usuario de BigQuery

Cuando cree tablas para eventos de usuario en BigQuery, utilice los esquemas que se describen en el artículo Acerca de los eventos de usuario.

Configurar el acceso a BigQuery

Si tu conjunto de datos de BigQuery está en un proyecto distinto 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 consola de Google Cloud .
  2. Seleccione el proyecto que contiene el almacén de datos al que quiere importar los eventos de usuario.
  3. Selecciona la casilla Incluir concesiones de roles proporcionadas por Google.
  4. Busca la cuenta de servicio con el nombre Discovery Engine Service Account (Cuenta de servicio de Discovery Engine).
  5. Si no has iniciado ninguna 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, vuelve a la tarea de importación e inicia la importación. Si no se puede completar debido a errores de permisos, vuelve aquí y completa esta tarea. Se mostrará la cuenta de servicio de Discovery Engine.
  6. Copia el identificador de la cuenta de servicio, que tiene el formato de 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 Conceder acceso.
  8. En Nuevos principales, introduzca el identificador de la cuenta de servicio y seleccione el rol BigQuery > Lector de datos de BigQuery.
  9. Haz clic en Guardar.

Para obtener más información sobre el acceso a BigQuery, consulta el artículo Controlar el acceso a conjuntos de datos de la documentación de BigQuery.

Importar eventos de BigQuery

Si tienes una aplicación multimedia, puedes importar eventos de usuario mediante laGoogle Cloud consola o la API. En el caso de otros tipos de aplicaciones, solo puedes importar datos mediante la API.

Consola

Para importar eventos de usuario de aplicaciones multimedia mediante la consola, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Aplicaciones de IA.

    Aplicaciones de IA

  2. En la página Aplicaciones, haz clic en tu aplicación multimedia.

  3. Ve a la página Datos.

    En las aplicaciones de recomendaciones de contenido multimedia, la pestaña Requisitos muestra los documentos multimedia y los eventos de usuario que debe importar.

  4. Haga clic en la pestaña Eventos. Si ya ha importado algún evento, la información sobre él se muestra en esta pestaña.

  5. Haz clic en Importar eventos.

  6. Selecciona BigQuery como fuente de datos.

  7. Introduzca o seleccione la ruta de BigQuery de sus eventos de usuario.

  8. Haz clic en Importar.

  9. En la pestaña Actividad se muestra el estado de la importación.

  10. Si se producen errores de importación, en la pestaña Actividad:

    1. Despliega el error en la columna Detalles y haz clic en Ver detalles para ver más información en el panel Detalles del registro de actividad.

    2. En el panel Detalles del registro de actividad, haz clic en Ver registros de errores completos para ver el error en Explorador de registros.

REST

Para importar de forma masiva el historial de eventos de usuario de Cloud Storage, sigue estos pasos:

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

    Al importar los eventos, utilice 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/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

    Si va a importar eventos de usuario a nivel de ubicación, utilice el endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importar historial de eventos de usuario como datos JSON locales

Puede importar eventos de usuario incluyendo datos JSON locales de los eventos en su llamada al método userEvents.import.

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

  1. Crea un archivo JSON que contenga los datos de eventos de usuario. Para ver 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 eventos, haz una solicitud POST al método userEvents.import 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/dataStores/DATA_STORE_ID/userEvents:import"

    Si va a importar eventos de usuario a nivel de ubicación, utilice el endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.