Cette page a été traduite par l'API Cloud Translation.

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 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é des données dans l'API Retail, 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 de manière intégrée avec la méthode userEvents.import.

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

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. Peut être effectué à l'aide de Cloud Console ou de cURL.
	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	Importer des données préexistantes depuis Google Analytics vers Retail.
	Contexte d'utilisation	Si vous utilisez Google Analytics et que vous assurez le suivi des 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.
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 en utilisant Cloud Console ou la méthode userEvents.import.

Console

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

Accéder à la page "Données"
Cliquez sur Importer pour ouvrir le panneau d'importation.
Sélectionnez Événements utilisateur.
Sélectionnez la branche dans laquelle vous allez importer vos événements.
Sélectionnez Cloud Storage comme source de données.
Saisissez l'emplacement Cloud Storage de vos données.
(Facultatif) 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.
(Facultatif) Choisissez si vous souhaitez planifier une importation récurrente de vos événements utilisateur.

Cette option n'est disponible que si vous avez réussi à importer au moins une fois des événements utilisateur avec l'API Retail.
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 depuis BigQuery

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

Console

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

Accéder à la page "Données"
Cliquez sur Importer pour ouvrir le panneau d'importation.
Sélectionnez Événements utilisateur.
Sélectionnez la branche dans laquelle vous allez importer vos événements.
Sélectionnez BigQuery comme source de données.
Renseignez la table BigQuery dans laquelle se trouvent vos données.
(Facultatif) 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.
(Facultatif) Choisissez si vous souhaitez planifier une importation récurrente de vos événements utilisateur.

Cette option n'est disponible que si vous avez réussi à importer au moins une fois des événements utilisateur avec l'API Retail.
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

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 Google Cloud Console 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.
  
  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 de manière intégrée

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.

Étape suivante

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