Se usó la API de Cloud Translation para traducir esta página.

Importar eventos históricos del usuario

En esta página, se describe cómo importar datos de eventos de usuario de forma masiva desde eventos anteriores. Los modelos de API de venta minorista requieren datos de eventos de usuarios para el entrenamiento.

Después de configurar el registro de eventos en tiempo real, puede tomar bastante tiempo en registrar suficientes datos de eventos de usuario para entrenar los modelos. Puedes acelerar el entrenamiento inicial de los modelos mediante la importación masiva de datos de eventos de usuario de eventos pasados. Antes de hacerlo, revisa las prácticas recomendadas para registrar eventos de usuario y la sección Antes de comenzar de esta página.

Los procedimientos de importación de esta página se aplican a Recomendaciones IA y a la Búsqueda de venta minorista. Después de importar datos a la API de Retail, ambos servicios pueden usar esos eventos, por lo que no necesitas importar los mismos datos dos veces si usas ambos servicios.

Puedes hacer lo siguiente:

Importa eventos desde Cloud Storage.
Importa eventos desde BigQuery.
Importa eventos de Google Analytics 360 desde BigQuery.
Importe eventos de Google Analytics 4 desde BigQuery (Vista previa privada).
Importa eventos intercalados con el método userEvents.import.

Instructivo para importar eventos de Cloud Storage

En este instructivo, se muestra cómo importar eventos de usuario desde Cloud Storage.

Para obtener orientación paso a paso directamente sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

Guiarme

En las siguientes secciones, se explican los mismos pasos que cuando se hace clic en Guiarme.

Instructivo para importar eventos de BigQuery

En este instructivo, se muestra cómo importar eventos de usuario desde BigQuery.

Para obtener orientación paso a paso directamente sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

Guiarme

En las siguientes secciones, se explican los mismos pasos que cuando se hace clic en Guiarme.

Instructivo intercalado de importación de eventos

En este instructivo, se muestra cómo importar datos de eventos de usuario intercalados.

Para obtener orientación paso a paso directamente sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

Guiarme

En las siguientes secciones, se explican los mismos pasos que cuando se hace clic en Guiarme.

Antes de comenzar

Para evitar errores de importación y asegurarte de que la API de venta minorista tenga datos suficientes para generar buenos resultados, revisa la siguiente información antes de importar tus eventos de usuario.

Revisa las prácticas recomendadas para registrar eventos de usuario.
El formato de los eventos de usuario varía según el tipo de evento de usuario. Consulta Esquema de ejemplos y tipos de eventos de usuario para obtener el formato que debes especificar cuando crees tablas para cada tipo de evento.
Recomendaciones IA y búsqueda de venta minorista tienen diferentes requisitos de datos mínimos. Asegúrate de que tus eventos de usuario cumplan con los requisitos del servicio que planeas usar:
- Consulta los requisitos y las prácticas recomendadas de eventos de usuario para conocer los requisitos de la búsqueda de venta minorista y Recomendaciones IA.
- Si usas modelos de Recomendaciones IA, también consulta los Requisitos de datos de eventos de usuario, en los que se enumeran requisitos adicionales según el tipo de modelo de recomendación y el objetivo de optimización que planeas usar.

Consideraciones sobre la importación de eventos

En esta sección, se describen los métodos que se pueden usar para importar por lotes tus eventos de usuario históricos, cuándo puedes usar cada método y algunas de sus limitaciones.

Cloud Storage	Descripción	Importa datos en formato JSON desde archivos cargados en un bucket de Cloud Storage Cada archivo debe ser de 2 GB o menos, y se pueden importar hasta 100 archivos a la vez. La importación se puede realizar mediante la consola o cURL. Usa el formato de datos JSON `Product`, que permite atributos personalizados.
	Cuándo usarla	Si necesitas que se carguen grandes volúmenes de datos en un solo paso.
	Limitaciones	Si tus datos están en Google Analytics o Merchant Center, estos solo se pueden exportar a BigQuery y se requiere el paso adicional de importarlos a Cloud Storage.
BigQuery	Descripción	Importa datos de una tabla de BigQuery cargada con anterioridad que usa el esquema de venta minorista. Se puede realizar con console o cURL.
	Cuándo usarla	Si también usas datos de eventos de estadísticas o procesamiento previo antes de importarlos.
	Limitaciones	Requiere el paso adicional de crear una tabla de BigQuery que se asigne al esquema de venta minorista. Si tienes un gran volumen de eventos de usuario, también considera que BigQuery es un recurso de mayor costo que Cloud Storage.
BigQuery con Google Analytics 360	Descripción	Importa datos preexistentes de Google Analytics 360 a la venta minorista.
	Cuándo usarla	Si tienes Google Analytics 360 y realizas un seguimiento de las conversiones de recomendaciones o búsquedas No se requiere la asignación de esquemas adicionales.
	Limitaciones	Solo hay un subconjunto de atributos disponible, por lo que no se pueden usar algunas funciones avanzadas de venta minorista. Se requiere el seguimiento de las impresiones en Google Analytics si planeas usar la búsqueda de venta minorista.
BigQuery con Google Analytics 4 (vista previa privada)	Descripción	Importa datos preexistentes de Google Analytics 4 a la venta minorista.
	Cuándo usarla	Si tienes Google Analytics 4 y realizas un seguimiento de las conversiones de las recomendaciones o búsquedas No se requiere la asignación de esquemas adicionales.
	Limitaciones	Solo hay un subconjunto de atributos disponible, por lo que no se pueden usar algunas funciones avanzadas de venta minorista. Si planeas usar Retail Search, debes configurar pares clave-valor de parámetros de evento para el seguimiento; la clave recomendada es `search_query`.
Importación intercalada	Descripción	Importación mediante una llamada al método `userEvents.import`.
	Cuándo usarla	Si deseas la privacidad adicional de que todas las autenticaciones se produzcan en el backend y poder realizar una importación de backend.
	Limitaciones	Por lo general, es más complicado que una importación web.

Importa eventos de usuario desde Cloud Storage

Importa eventos de usuario desde Cloud Storage mediante la consola o el método userEvents.import.

Console

Ve a la página Datos de venta minorista en Google Cloud Console.

Ir a la página Datos
Haz clic en Importar para abrir el panel Importar datos.
Elige Eventos de usuario.
Selecciona Google Cloud Storage como la fuente de datos.
Elige Esquema de eventos de usuario de venta minorista como el esquema.
Ingresa la ubicación de Cloud Storage de tus datos.
Haga clic en Importar.

cURL

Usa el método userEvents.import para importar tus eventos de usuario.

Crea un archivo de datos para los parámetros de entrada de la importación. Usa el objeto GcsSource para que apunte a tu bucket de Cloud Storage.

Puedes proporcionar varios archivos o solo uno.
- INPUT_FILE: Son los archivos en Cloud Storage que contienen los datos de eventos de tu usuario. Consulta Eventos de usuario para ver ejemplos de cada formato de tipo de evento de usuario. Asegúrate de que cada evento de usuario esté en su propia línea única, sin saltos de línea.
- ERROR_DIRECTORY: Un directorio de Cloud Storage para obtener información sobre los errores de la importación
Los campos de archivo de entrada deben tener el formato gs://<bucket>/<path-to-file>/. El directorio de errores debe tener el formato gs://<bucket>/<folder>/. Si el directorio de errores no existe, la API de venta minorista lo crea. El bucket ya debe existir.
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

Importa la información de tu catálogo a la API de venta minorista mediante una solicitud POST al método REST userEvents:import y proporciona el nombre del archivo de datos.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl -X POST \
     -v \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
     --data @./DATA_FILE.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"
  }
}'

Importa eventos de usuario desde BigQuery

Importa eventos de usuario desde BigQuery mediante la consola o el método userEvents.import.

Console

Ve a la página Datos de venta minorista en Google Cloud Console.

Ir a la página Datos
Haz clic en Importar para abrir el panel Importar datos.
Elige Eventos de usuario.
Selecciona BigQuery como la fuente de datos.
Elige Esquema de eventos de usuario de venta minorista como el esquema.
Ingresa la tabla de BigQuery donde se encuentran tus datos.
Ingresa la ubicación de un depósito de Cloud Storage en tu proyecto como ubicación temporal para tus datos (opcional).
Si no se especifica, se usa una ubicación predeterminada. Si se especifica, el bucket de BigQuery y Cloud Storage deben estar en la misma región.
En Mostrar opciones avanzadas, ingresa la ubicación de un depósito de Cloud Storage en tu proyecto como una ubicación temporal para tus datos (opcional).

Si no se especifica, se usa una ubicación predeterminada. Si se especifica, el bucket de BigQuery y Cloud Storage deben estar en la misma región.
Haga clic en Importar.

cURL

Usa el método userEvents.import para importar tus eventos de usuario.

Cuando importes tus eventos, usa el valor user_event para dataSchema.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event"
    }
  }
}'

Si tu conjunto de datos de BigQuery pertenece a un proyecto diferente al de tu API de venta minorista, sigue las instrucciones en Configura el acceso a tu conjunto de datos de BigQuery para darle a tu cuenta de servicio de venta minorista una función de Editor de datos de BigQuery para tu proyecto de BigQuery. Modifica la solicitud de importación para especificar el ID del proyecto de BigQuery:

"bigQuerySource": {
     "projectId": "BQ_PROJECT_ID",
   }

Importe eventos de usuario de Google Analytics 360 con BigQuery

Puedes importar eventos de usuario de Google Analytics 360 si integraste Google Analytics 360 a BigQuery y usas el Comercio electrónico mejorado.

En los siguientes procedimientos, se da por sentado que estás familiarizado con el uso de BigQuery y Google Analytics 360.

Antes de comenzar

Antes de comenzar con los siguientes pasos, asegúrate de lo siguiente:

Estás usando el comercio electrónico mejorado.
Tienes BigQuery vinculado a Analytics 360.

Verifica tu fuente de datos

Asegúrate de que los datos de eventos de usuario que importarás tengan el formato correcto en una tabla de BigQuery a la que tengas acceso.

La tabla debe tener el formato project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

Consulta la documentación de Google Analytics para obtener más información sobre el formato de la tabla.
En BigQuery Google Cloud Console, selecciona la tabla del panel Explorador para obtener una vista previa de la tabla.

Verifica lo siguiente:
1. La columna clientId tiene un valor válido (por ejemplo, 123456789.123456789).
  
  Ten en cuenta que este valor es diferente del valor completo de la cookie _ga (que tiene un formato como GA1.3.123456789.123456789).
2. La columna hits.transaction.currencyCode tiene un código de moneda válido.
  
  Nota: El tipo de evento purchase-complete de venta minorista requiere un código de moneda. Si importas eventos de compra, que algunos modelos de venta minorista requieren, actualiza los informes de comercio electrónico mejorado para incluir el código de moneda.
3. Si planeas importar eventos search, verifica que haya una columna hits.page.searchKeyword o hits.customVariable.searchQuery.
  
  Se admite la importación de eventos search, pero no se asignan desde Analytics 360 de la misma manera que otros tipos de eventos, ya que Analytics 360 no admite de forma nativa el tipo de evento search. Durante la importación, la API de venta minorista construye eventos search a partir de Analytics 360 mediante la combinación de la información de la búsqueda y, si está presente, la impresión del producto.
  
  La búsqueda se deriva de hits.page.searchKeyword, o de hits.customVariables.customVarValue si hits.customVariables.customVarName es searchQuery. La impresión del producto se toma de hits.product si hits.product.isImpressions es TRUE.

Comprueba la coherencia de los ID de elementos entre el catálogo subido y la tabla de eventos del usuario de Analytics 360.

Con cualquier ID de producto de la columna hits.product.productSKU en la vista previa de la tabla de BigQuery, usa el método product.get para asegurarte de que el mismo producto esté en tu catálogo subido.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

   curl \
     -v \
     -X GET \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Importa eventos de Google Analytics 360 desde BigQuery.

Importa tus eventos de usuario mediante la inclusión de los datos de los eventos en tu llamada al método userEvents.import.

Para dataSchema, usa el valor user_event_ga360.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

Java

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Si tu conjunto de datos de BigQuery pertenece a un proyecto diferente al de tu proyecto de venta minorista, sigue las instrucciones en Configura el acceso a tu conjunto de datos de BigQuery para darle a tu cuenta de servicio de venta minorista una función de Editor de datos de BigQuery para tu proyecto de BigQuery. Modifica la solicitud de importación para especificar el ID del proyecto de BigQuery:

"bigQuerySource": {
     "projectId": "GA360_BQ_PROJECT_ID",
   }

Cómo importar eventos de usuario de Google Analytics 4 con BigQuery (vista previa privada)

Puedes importar eventos de usuario de Google Analytics 4 si integraste Google Analytics 4 a BigQuery y usas el comercio electrónico mejorado.

Antes de comenzar

Antes de comenzar, asegúrate de lo siguiente:

Estás usando el comercio electrónico mejorado.
Tienes BigQuery vinculado a Google Analytics 4.

Solicitar acceso

El acceso a esta función de vista previa privada requiere permiso:

Comunícate con el equipo de asistencia al cliente de Retail a fin de solicitar permiso o instrucciones para importar eventos de usuario de Google Analytics 4.

Importar eventos de usuario intercalados

curl

Para importar eventos de usuario intercalados, incluye los datos de los eventos en tu llamada al método userEvents.import.

La manera más sencilla de hacerlo es colocar los datos de eventos de usuario en un archivo JSON y proporcionar el archivo a cURL.

Para conocer los formatos de los tipos de eventos de usuario, consulta Eventos de usuario.

Crea el archivo JSON:

{
"inputConfig": {
  "userEventInlineSource": {
      "userEvents": [
        {
          <userEvent1>>
        },
        {
          <userEvent2>
        },
        ....
      ]
    }
  }
}

Llama al método POST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"

Java

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Datos históricos de catálogos

También puedes importar los datos históricos del catálogo que aparecen en tus eventos de usuario históricos. Estos datos históricos de catálogos pueden ser útiles porque la API de venta minorista puede usar información del producto anterior para enriquecer los eventos de usuario, lo que puede mejorar la exactitud del modelo.

Para obtener más detalles, consulta Importa datos del catálogo histórico.

¿Qué sigue?

Comienza a registrar eventos de usuario.
Administra los eventos de usuario.