Importer des é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 Vertex AI Search pour le commerce 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 décrites sur cette page s'appliquent à la fois aux recommandations et à la recherche. Une fois que vous avez importé des données, les deux services peuvent utiliser ces événements. Vous n'avez donc pas besoin d'importer les mêmes données deux fois 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.
• Importer des événements Google Analytics 4 à partir de BigQuery
• Importer des événements de manière intégrée avec la méthode userEvents.import.

Importer des événements depuis Cloud Storage

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

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

Visite guidée

Tutoriel Importer des événements depuis BigQuery

Ce tutoriel explique comment importer des événements utilisateur depuis BigQuery.

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

Visite guidée

Tutoriel Importer des événements de manière intégrée

Ce tutoriel explique comment importer des données d'événements utilisateur de manière intégrée.

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

Visite guidée

Avant de commencer

Pour éviter les erreurs d'importation et vous assurer qu'il y a 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 les recommandations et la recherche sont différentes. Assurez-vous que vos événements utilisateur répondent aux exigences du service que vous prévoyez d'utiliser :

  • Consultez la section Exigences et bonnes pratiques concernant les événements utilisateur pour connaître les exigences applicables à la recherche et aux recommandations.

  • Si vous utilisez des modèles de recommandation, 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 l'importation par lot de votre historique d'événements utilisateur, les cas de figure dans lesquels vous pouvez les utiliser et certaines de leurs limitations.

Importer des événements utilisateur depuis Cloud Storage

Importez des événements utilisateur à partir de Cloud Storage en utilisant la console Google Cloud ou la méthode userEvents.import.

Importer des événements utilisateur depuis BigQuery

Importez des événements utilisateur à partir de BigQuery en utilisant la console Google Cloud ou la méthode userEvents.import.

Configurer l'accès à BigQuery

Suivez les instructions de la section Configurer l'accès à votre ensemble de données BigQuery pour attribuer à votre compte de service Vertex AI Search for retail le rôle Propriétaire de données BigQuery pour votre ensemble de données BigQuery.

Importer vos événements utilisateur depuis BigQuery

Vous pouvez importer des événements 360 à l'aide de la console Search for Retail ou de la méthode userEvents.import.

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

Importer des événements utilisateur Analytics 360 avec BigQuery

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

Les procédures suivantes supposent que vous maîtrisez BigQuery et 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

1. 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.

   Assurez-vous que la table est nommée project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

   Pour en savoir plus sur le format et le nom des tables, consultez la documentation Google Analytics.

2. Dans la console Google Cloud pour BigQuery, 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.

   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.

      Bien que Vertex AI Search for retail nécessite à la fois searchQuery et productDetails pour renvoyer une liste de résultats de recherche, Analytics 360 ne stocke pas à la fois les requêtes de recherche et les impressions de produits dans un même événement. Pour que Vertex AI Search pour le commerce fonctionne, vous devez créer une balise au niveau de la couche de données ou un pixel JavaScript afin de pouvoir importer les deux types d'événements utilisateur à partir de sources Google Analytics:

      • searchQuery, qui est lu à partir du paramètre search_term ou des événements view_search_results, est dérivé de hits.page.searchKeyword ou de hits.customVariables.customVarValue si hits.customVariables.customVarName est searchQuery.
      • productDetails, l'impression produit lue à partir du paramètre items de l'événement view_item_list, est extraite de hits.product si hits.product.isImpressions est TRUE.

3. 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 Analytics 360

Vous pouvez importer des événements Google Analytics 360 à l'aide de la console Search for Retail ou de la méthode userEvents.import.

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

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;
}

Importer vos vues de page d'accueil Analytics 360 avec BigQuery

Dans Analytics 360, les événements de page vue d'accueil ne sont pas distingués des autres événements de page vue. Cela signifie que les événements "home-page-view" ne sont pas importés en tant qu'événements avec les autres types d'événements (tels que "detail-page-view") dans Importer vos événements Analytics 360.

La procédure suivante explique comment extraire des événements de vue de la page d'accueil à partir de vos données Analytics 360 et les importer dans Vertex AI Search for retail. En résumé, cela se fait en extrayant les vues de la page d'accueil des utilisateurs (identifiées par le chemin d'accès à la page d'accueil) dans une nouvelle table BigQuery, puis en important les données de cette nouvelle table dans la recherche Vertex AI pour le commerce.

Pour importer des événements de vue de la page d'accueil depuis Analytics 360 dans Vertex AI Search pour le commerce:

1. Créez un ensemble de données BigQuery ou assurez-vous d'en avoir un disponible auquel vous pouvez ajouter une table.

   Cet ensemble de données peut se trouver dans votre projet Vertex AI Search pour le commerce ou dans le projet dans lequel se trouvent vos données Analytics 360. Il s'agit du jeu de données cible dans lequel vous allez copier les événements de consultation de la page d'accueil Analytics 360.

2. Créez une table BigQuery dans l'ensemble de données comme suit:

   1. Remplacez les variables dans le code SQL suivant comme suit.

      • target_project_id::projet dans lequel se trouve l'ensemble de données de l'étape 1.

      • target_dataset::nom de l'ensemble de données de l'étape 1.

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. Copiez l'exemple de code SQL.

   3. Ouvrez la page BigQuery dans la console Google Cloud.

      Accéder à la page "BigQuery"

   4. Si ce n'est pas déjà fait, sélectionnez le projet cible.

   5. Dans le volet Éditeur, collez l'exemple de code SQL.

   6. Cliquez sur play_circle Run (Exécuter) et attendez la fin de l'exécution de la requête.

   L'exécution de ce code crée une table au format target_project_id:target_dataset.ga_homepage_YYYYMMDD (par exemple, my-project:view_events.ga_homepage_20230115).

3. Copiez les événements de vue de la page d'accueil Analytics 360 de votre table de données Analytics 360 dans la table créée à l'étape 2 précédente.

   1. Remplacez les variables dans l'exemple de code SQL suivant comme suit:

      • source_project_id::ID du projet contenant les données Analytics 360 dans une table BigQuery.

      • source_dataset::ensemble de données du projet source contenant les données Analytics 360 dans une table BigQuery.

      • source_table::table du projet source contenant les données Analytics 360.

      • target_project_id::même ID de projet cible que dans l'étape 2 précédente.

      • target_dataset::même ensemble de données cible que dans l'étape 2 précédente.

      • path:chemin d'accès à la page d'accueil. Il s'agit généralement de /, par exemple si la page d'accueil est example.com/. Toutefois, si la page d'accueil est semblable à examplepetstore.com/index.html, le chemin d'accès est /index.html.

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. Copiez l'exemple de code SQL.

   3. Ouvrez la page BigQuery dans la console Google Cloud.

      Accéder à la page "BigQuery"

   4. Si ce n'est pas déjà fait, sélectionnez le projet cible.

   5. Dans le volet Éditeur, collez l'exemple de code SQL.

   6. Cliquez sur play_circle Run (Exécuter) et attendez la fin de l'exécution de la requête.

4. Suivez les instructions de la section Importer des événements utilisateur depuis BigQuery pour importer les événements de vue de la page d'accueil à partir de la table cible. Lors de la sélection du schéma, si vous importez à l'aide de la console, sélectionnez Schéma d'événement utilisateur Retail. Si vous importez à l'aide de userEvents.import, spécifiez user_event pour la valeur dataSchema.

5. Supprimez la table et l'ensemble de données que vous avez créés aux étapes 1 et 2.

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

Vous pouvez importer des événements utilisateur Google Analytics 4 si vous avez intégré Google Analytics 4 à BigQuery et que vous utilisez Google Analytics Ecommerce.

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

Avant de commencer

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

• Vous utilisez E-commerce Google Analytics.
• Vous avez associé BigQuery à Google Analytics 4.

Vérifier votre source de données

Pour vous assurer que vos données d'événement utilisateur sont prêtes à être importées, procédez comme suit.

Pour obtenir un tableau des champs Google Analytics 4 utilisés par Vertex AI Search pour le commerce et les champs Vertex AI Search pour le commerce auxquels ils sont mappés, consultez Champs d'événement utilisateur Google Analytics 4.

Pour connaître tous les paramètres d'événement Google Analytics, consultez la documentation de référence sur les événements Google Analytics.

1. 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.

   • L'ensemble de données doit être nommé analytics_PROPERTY_ID.
   • La table doit être nommée events_YYYYMMDD.

   Pour en savoir plus sur les noms et le format des tables, consultez la documentation Google Analytics.

2. Dans la console Google Cloud pour BigQuery, sélectionnez l'ensemble de données dans le panneau Explorer, puis recherchez la table des événements utilisateur que vous prévoyez d'importer.

   Vérifiez les points suivants :

   1. La colonne event_params.key contient une clé currency et sa valeur de chaîne associée est un code de devise valide.

   2. Si vous envisagez d'importer des événements search, vérifiez que la colonne event.event_params.key comporte une clé search_term et une valeur associée.

      Alors que Retail Search Vertex AI nécessite à la fois searchQuery et productDetails pour renvoyer une liste de résultats de recherche, Google Analytics 4 ne stocke pas à la fois les requêtes de recherche et les impressions de produits dans un même événement. Pour que Vertex AI Search pour le commerce fonctionne, vous devez créer une balise au niveau de la couche de données ou à partir d'un pixel JavaScript afin de pouvoir importer les deux types d'événements utilisateur à partir de sources Google Analytics:

      • searchQuery, qui est lu à partir du paramètre search_term ou des événements view_search_results.
      • productDetails, l'impression du produit lue à partir du paramètre items de l'événement view_item_list.

      Pour en savoir plus sur search dans Google Analytics 4, consultez search dans la documentation Google Analytics.

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

   Pour vous assurer qu'un produit de la table des utilisateurs Google Analytics 4 se trouve également dans votre catalogue importé, copiez un ID produit de la colonne event.items.item_id dans l'aperçu de la table BigQuery, puis utilisez la méthode product.get pour vérifier si cet ID 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"

Configurer l'accès à BigQuery

Suivez les instructions de la section Configurer l'accès à votre ensemble de données BigQuery pour attribuer à votre compte de service Vertex AI Search for retail le rôle Propriétaire de données BigQuery pour votre ensemble de données BigQuery.

Importer vos événements Google Analytics 4

Vous pouvez importer des événements Google Analytics 4 à l'aide de la console Search for Retail ou de la méthode userEvents.import.

Importer des événements Google Analytics 4 à l'aide de la console

1. Accédez à la page Données> dans la console de la recherche pour le commerce.
   
   Accéder à la page "Données"
2. Cliquez sur Importer pour ouvrir le panneau Importer les données.
3. Sélectionnez Événements utilisateur.
4. Sélectionnez BigQuery comme source de données.

5. Sélectionnez le schéma de données.

   • Google Analytics 4: à utiliser pour les événements Google Analytics 4.
   • Google Analytics 360: à utiliser pour les événements Google Analytics 360, sauf si vous importez uniquement des événements "vues de la page d'accueil" à partir de Google Analytics 360 (dans ce cas, utilisez le schéma des événements utilisateur dans le commerce).
   • Schéma des événements utilisateur dans le commerce: utilisez-le pour importer des événements à partir d'autres sources que Google Analytics et pour importer uniquement des événements de vue de la page d'accueil à partir de Google Analytics 360.
6. Renseignez la table BigQuery dans laquelle se trouvent vos données.
7. Facultatif: saisissez l'emplacement d'un bucket Cloud Storage de votre projet en tant qu'emplacement temporaire pour vos données.
   Si cet emplacement n'est pas spécifié, un emplacement par défaut est utilisé. Si vous spécifiez un emplacement, BigQuery et le bucket Cloud Storage doivent se trouver dans la même région.
8. Facultatif: Sous Afficher les options avancées, saisissez l'emplacement d'un bucket Cloud Storage de votre projet en tant qu'emplacement temporaire pour vos données.
   
   Si aucun emplacement n'est spécifié, un emplacement par défaut est utilisé. Si vous spécifiez un emplacement, BigQuery et le bucket Cloud Storage doivent se trouver dans la même région.
9. Cliquez sur Importer.

Importer des événements Google Analytics 4 à l'aide de l'API

Importez les événements utilisateur en incluant les données des événements dans votre appel à la méthode userEvents.import. Consultez la documentation de référence de l'API userEvents.import.

Pour dataSchema, utilisez la valeur user_event_ga4.

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": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

Importer des événements utilisateur de manière intégrée

Vous pouvez importer des é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 section À propos des événements utilisateur.

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, car les informations sur les produits passés peuvent être utilisé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.

Afficher les événements importés

Consultez les métriques d'intégration des événements dans l'onglet Événements de la page Données de la console Search for Retail. Cette page présente tous les événements écrits ou importés au cours de l'année précédente. Les métriques peuvent mettre jusqu'à 24 heures à s'afficher après l'ingestion des données.

Accéder à la page "Données"

Étape suivante

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