Importer les événements utilisateur historiques

Cette page explique comment importer des données d'événements utilisateur passés de façon groupée. Les modèles de l'API Retail nécessitent des données d'événement utilisateur pour l'entraînement.

Une fois que vous avez configuré l'enregistrement des événements en temps réel, l'enregistrement des données d'événements utilisateur nécessaires à l'entraînement de vos modèles peut prendre un temps considérable. Vous pouvez accélérer l'entraînement initial du modèle en important de façon groupée les données d'événements utilisateur passés. Avant cela, consultez les bonnes pratiques pour enregistrer des événements utilisateur et la section Avant de commencer de la présente page.

Les procédures d'importation présentées sur cette page s'appliquent à Recommendations AI et à Retail Search. Une fois que vous avez importé les données dans l'API Retail, les deux services peuvent utiliser ces événements. Vous n'avez donc pas besoin d'importer deux fois les mêmes données si vous utilisez les deux services.

Vous pouvez :

Importer des événements à partir de Cloud Storage.
Importer des événements à partir de BigQuery.
Importer des événements Google Analytics 360 à partir de BigQuery.
Importez les événements Google Analytics 4 depuis BigQuery (aperçu privé).
Importer des événements de manière intégrée avec la méthode userEvents.import.

Tutoriel sur l'importation d'événements à partir de Cloud Storage

Ce tutoriel vous explique comment importer des événements utilisateur depuis Cloud Storage.

Pour obtenir des conseils détaillés sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

La procédure décrite dans les sections suivantes, est la même que si vous cliquez sur Visite guidée.

Tutoriel sur l'importation d'événements à partir de BigQuery

Ce tutoriel explique comment importer des événements utilisateur à partir de BigQuery.

Pour obtenir des conseils détaillés sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

La procédure décrite dans les sections suivantes, est la même que si vous cliquez sur Visite guidée.

Tutoriel intégré sur l'importation d'événements

Ce tutoriel vous explique comment importer des données d'événements utilisateur de façon intégrée.

Pour obtenir des conseils détaillés sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

La procédure décrite dans les sections suivantes, est la même que si vous cliquez sur Visite guidée.

Avant de commencer

Pour éviter les erreurs d'importation et vous assurer que l'API Retail dispose de suffisamment de données pour générer de bons résultats, consultez les informations suivantes avant d'importer vos événements utilisateur.

Passez en revue les bonnes pratiques pour l'enregistrement des événements utilisateur.
La mise en forme des événements utilisateur varie en fonction du type d'événement utilisateur. Consultez la section Types d'événements utilisateur et exemple de schéma pour connaître le format à spécifier lors de la création de tables pour chaque type d'événement.
Les exigences minimales relatives aux données pour Recommendations AI et Retail Search sont différentes. Assurez-vous que vos événements utilisateur répondent aux exigences du service que vous prévoyez d'utiliser :
- Consultez la page Exigences et bonnes pratiques pour les événements utilisateur afin de connaître les exigences applicables à Retail Search et Recommendations AI.
- Si vous utilisez des modèles Recommendations AI, consultez également la section Exigences relatives aux données des événements utilisateur, qui répertorie les exigences supplémentaires en fonction du type de modèle de recommandation et de l'objectif d'optimisation que vous prévoyez d'utiliser.

Remarques concernant l'importation d'événements

Cette section décrit les méthodes pouvant être utilisées pour importer par lot des événements utilisateur historiques, quand vous pouvez utiliser chaque méthode et certaines de leurs limites.

Cloud Storage	Description	Importer des données au format JSON à partir de fichiers chargés dans un bucket Cloud Storage. Chaque fichier doit avoir une taille inférieure ou égale à 2 Go, et vous pouvez importer jusqu'à 100 fichiers à la fois. L'importation peut être effectuée à l'aide de Cloud Console ou de cURL. Utilise le format de données JSON `Product`, qui permet d'utiliser des attributs personnalisés.
	Contexte d'utilisation	Si vous avez besoin de charger des volumes de données importants en une seule étape.
	Limites	Si vos données se trouvent dans Google Analytics ou Merchant Center, elles ne peuvent être exportées que vers BigQuery et nécessitent donc une étape supplémentaire d'importation vers Cloud Storage.
BigQuery	Description	Importer des données à partir d'une table BigQuery précédemment chargée qui utilise le schéma Retail. Cloud Console ou cURL peuvent être utilisés.
	Contexte d'utilisation	Si vous appliquez également des fonctions analytiques ou un prétraitement des données d'événement avant l'importation.
	Limites	Nécessite l'étape supplémentaire de la création d'une table BigQuery mappée sur le schéma Retail. Si vous avez un volume élevé d'événements utilisateur, pensez également que BigQuery est une ressource moins coûteuse que Cloud Storage.
BigQuery avec Google Analytics 360	Description	Importez des données préexistantes depuis Google Analytics 360 vers le commerce.
	Contexte d'utilisation	Si vous utilisez Google Analytics 360 et suivez les conversions pour les recommandations ou les recherches. Aucun mappage de schéma supplémentaire n'est requis.
	Limites	Seul un sous-ensemble d'attributs est disponible. Par conséquent, certaines fonctionnalités avancées de Retail ne peuvent pas être utilisées. Le suivi des impressions dans Google Analytics est requis si vous prévoyez d'utiliser Retail Search.
BigQuery avec Google Analytics 4 (aperçu privé)	Description	Importez des données préexistantes depuis Google Analytics 4 vers la vente au détail.
	Contexte d'utilisation	Si vous utilisez Google Analytics 4 et que vous suivez les conversions pour les recommandations ou les recherches. Aucun mappage de schéma supplémentaire n'est requis.
	Limites	Seul un sous-ensemble d'attributs est disponible. Par conséquent, certaines fonctionnalités avancées de Retail ne peuvent pas être utilisées. Si vous prévoyez d'utiliser Retail Search, vous devez configurer des paires clé/valeur de paramètre d'événement pour le suivi. La clé recommandée est `search_query`.
Importation intégrée	Description	Importer à l'aide d'un appel à la méthode `userEvents.import`
	Contexte d'utilisation	Si vous souhaitez améliorer la confidentialité de l'ensemble des processus d'authentification sur le backend et être en mesure d'effectuer une importation backend.
	Limites	Généralement plus complexe qu'une importation Web.

Importer des événements utilisateur à partir de Cloud Storage

Importez des événements utilisateur à partir de Cloud Storage à l'aide de Cloud Console ou de la méthode userEvents.import.

Console

Accédez à la page "Données de détail" dans Google Cloud Console.

Accéder à la page "Données"
Cliquez sur Import (Importer) pour ouvrir le panneau Import Data (Importer des données).
Sélectionnez Événements utilisateur.
Sélectionnez Google Cloud Storage en tant que source de données.
Choisissez le schéma Commerce des événements de l'utilisateur.
Saisissez l'emplacement Cloud Storage de vos données.
Cliquez sur Import (Importer).

cURL

Utilisez la méthode userEvents.import pour importer vos événements utilisateur.

Créez un fichier de données pour les paramètres d'entrée de l'importation. Utilisez l'objet GcsSource pour pointer vers votre bucket Cloud Storage.

Vous pouvez fournir plusieurs fichiers ou un seul.
- INPUT_FILE : un ou plusieurs fichiers Cloud Storage contenant vos données d'événements utilisateur. Pour obtenir des exemples de chaque type d'événement utilisateur, consultez la section Événements utilisateur. Assurez-vous que chaque événement utilisateur figure sur une ligne unique, sans saut de ligne.
- ERROR_DIRECTORY : répertoire Cloud Storage contenant des informations sur les erreurs d'importation.
Les champs du fichier d'entrée doivent être au format gs://<bucket>/<path-to-file>/. Le répertoire d'erreur doit être au format gs://<bucket>/<folder>/. Si le répertoire d'erreur n'existe pas, l'API Retail le crée. Le bucket doit déjà exister.
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

Importez vos informations de catalogue dans l'API Retail en envoyant une requête POST à la méthode REST userEvents:import, en fournissant le nom du fichier de données.

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"
  }
}'

Importer des événements utilisateur à partir de BigQuery

Importez des événements utilisateur à partir de BigQuery à l'aide de Cloud Console ou de la méthode userEvents.import.

Console

Accédez à la page "Données de détail" dans Google Cloud Console.

Accéder à la page "Données"
Cliquez sur Import (Importer) pour ouvrir le panneau Import Data (Importer des données).
Sélectionnez Événements utilisateur.
Sélectionnez BigQuery comme source de données.
Choisissez le schéma Commerce des événements de l'utilisateur.
Renseignez la table BigQuery dans laquelle se trouvent vos données.
(Facultatif) Indiquez l'emplacement d'un bucket Cloud Storage dans votre projet en tant qu'emplacement temporaire de vos données.
Si ce paramètre n'est pas spécifié, un emplacement par défaut est utilisé. Si cet attribut est spécifié, le bucket BigQuery et Cloud Storage doivent se trouver dans la même région.
(Facultatif) Sous Afficher les options avancées, saisissez l'emplacement d'un bucket Cloud Storage dans votre projet en tant qu'emplacement temporaire de vos données.

Si aucune valeur n'est spécifiée, un emplacement par défaut est utilisé. Si cet attribut est spécifié, le bucket BigQuery et Cloud Storage doivent se trouver dans la même région.
Cliquez sur Import (Importer).

cURL

Utilisez la méthode userEvents.import pour importer vos événements utilisateur.

Lorsque vous importez vos événements, utilisez la valeur user_event pour 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 votre ensemble de données BigQuery appartient à un projet différent de celui de votre projet d'API Retail, suivez les instructions de la section Configurer l'accès à votre ensemble de données BigQuery pour attribuer à votre compte de service Retail le rôle Éditeur de données BigQuery pour votre projet BigQuery Modifiez la requête d'importation pour spécifier l'ID du projet BigQuery :

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

Importer des événements utilisateur Google Analytics 360 avec BigQuery

Vous pouvez importer des événements utilisateur Google Analytics 360 si vous avez intégré Google Analytics 360 à BigQuery et que vous utilisez la fonction d'e-commerce amélioré.

Les procédures suivantes supposent que vous maîtrisez BigQuery et Google Analytics 360.

Avant de commencer

Avant de commencer les étapes suivantes, assurez-vous que :

Vous utilisez la fonction d'e-commerce amélioré.
Vous avez associé BigQuery à Analytics 360.

Vérifier votre source de données

Assurez-vous que les données d'événement utilisateur que vous allez importer sont correctement formatées dans une table BigQuery à laquelle vous avez accès.

La table doit être au format project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

Pour en savoir plus sur le format de la table, consultez la documentation Google Analytics.
Dans BigQuery Google Cloud Console, sélectionnez la table dans le panneau Explorateur pour la prévisualiser.

Vérifiez les points suivants :
1. La colonne clientId possède une valeur valide (par exemple, 123456789.123456789).
  
  Notez que cette valeur est différente de la valeur complète du cookie "_ga" (dont le format est similaire à GA1.3.123456789.123456789).
2. La colonne hits.transaction.currencyCode contient un code de devise valide.
  
  Remarque : Le type d'événement Retail purchase-complete nécessite un code de devise. Si vous importez des événements d'achat requis par certains modèles Retail, mettez à jour les rapports d'e-commerce amélioré pour inclure le code de devise.
3. Si vous envisagez d'importer des événements search, vérifiez qu'une colonne hits.page.searchKeyword ou hits.customVariable.searchQuery est présente.
  
  L'importation d'événements search est acceptée, mais les événements ne sont pas mappées à partir d'Analytics 360 de la même manière que les autres types d'événements, car Analytics 360 n'est pas compatible de manière native avec le type d'événement search. Lors de l'importation, l'API Retail crée des événements search à partir d'Analytics 360 en combinant les informations de requête de recherche avec celles de l'impression produit, le cas échéant.
  
  La requête de recherche est dérivée de hits.page.searchKeyword, ou de hits.customVariables.customVarValue si hits.customVariables.customVarName est searchQuery. L'impression produit est issue de hits.product si hits.product.isImpressions est défini sur TRUE.

Vérifiez la cohérence des ID d'article entre le catalogue importé et la table des événements utilisateur Analytics 360.

À l'aide de n'importe quel ID produit de la colonne hits.product.productSKU de l'aperçu de la table BigQuery, utilisez la méthode product.get pour vous assurer que le même produit se trouve dans votre catalogue importé.

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"

Importer vos événements Google Analytics 360

Importez les événements utilisateur en incluant les données des événements dans votre appel à la méthode userEvents.import.

Pour dataSchema, utilisez la valeur 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 votre ensemble de données BigQuery appartient à un projet différent de votre projet Retail, suivez les instructions de la section Configurer l'accès à votre ensemble de données BigQuery pour attribuer à votre compte de service Retail le rôle Éditeur de données BigQuery sur votre projet BigQuery. Modifiez la requête d'importation pour spécifier l'ID du projet BigQuery :

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

Importer des événements utilisateur Google Analytics 4 avec BigQuery (aperçu privé)

Vous pouvez importer des événements utilisateur Google Analytics 4 si vous avez intégré Google Analytics 4 à BigQuery et utilisez l'e-commerce amélioré.

Avant de commencer

Avant de commencer:

Vous utilisez la fonction d'e-commerce amélioré.
BigQuery est associé à Google Analytics 4.

Demander l'accès

L'accès à cette fonctionnalité d'aperçu privé nécessite l'autorisation suivante:

Contactez l'équipe d'assistance Retail pour demander l'autorisation et les instructions nécessaires pour importer les événements utilisateur Google Analytics 4.

Importer les événements utilisateur directement

curl

Vous importez les événements utilisateur de manière intégrée en incluant les données associées aux événements dans votre appel à la méthode userEvents.import.

Le moyen le plus simple consiste à placer vos données d'événements utilisateur dans un fichier JSON et à fournir ce fichier à cURL.

Pour connaître les formats des types d'événements utilisateur, consultez la page Événements utilisateur.

Créez le fichier JSON :

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

Appelez la méthode 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;
}

Historique de données de catalogue

Vous pouvez également importer l'historique des données de catalogue qui apparaissent dans votre historique d'événements utilisateur. Cet historique des données de catalogue peut être utile à l'API Retail car elle peut utiliser les informations produits passées pour enrichir les événements utilisateur, ce qui peut améliorer la précision du modèle.

Pour en savoir plus, consultez la page Importer l'historique des données de catalogue.

Étapes suivantes

Commencez à enregistrer des événements utilisateur.
Gérez vos événements utilisateur