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 :
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 :
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 :
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 formatgs://<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 RESTuserEvents: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 :
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
).La colonne
hits.transaction.currencyCode
contient un code de devise valide.Si vous envisagez d'importer des événements
search
, vérifiez qu'une colonnehits.page.searchKeyword
ouhits.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énementsearch
. Lors de l'importation, l'API Retail crée des événementssearch
à 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 dehits.customVariables.customVarValue
sihits.customVariables.customVarName
estsearchQuery
. L'impression produit est issue dehits.product
sihits.product.isImpressions
est défini surTRUE
.
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éthodeproduct.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
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
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.