Ce document concerne Recommendations AI, Retail Search et la nouvelle console Retail. Pour utiliser Retail Search dans la phase en disponibilité limitée, contactez le service commercial Cloud.

Si vous n'utilisez que Recommendations AI, restez dans la console Recommendations AI et consultez la documentation sur Recommendations AI.

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 :

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.

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

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

    Accéder à la page "Données"

  2. Cliquez sur Importer pour ouvrir le panneau d'importation.

  3. Sélectionnez Événements utilisateur.

  4. Sélectionnez la branche dans laquelle vous allez importer vos événements.

  5. Sélectionnez Cloud Storage comme source de données.

  6. Saisissez l'emplacement Cloud Storage de 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 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.

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

  9. Cliquez sur Import (Importer).

cURL

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

  1. 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"}
    }
    
  2. 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

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

    Accéder à la page "Données"

  2. Cliquez sur Importer pour ouvrir le panneau d'importation.

  3. Sélectionnez Événements utilisateur.

  4. Sélectionnez la branche dans laquelle vous allez importer vos événements.

  5. Sélectionnez BigQuery comme source de données.

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

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

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

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.

    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.

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

    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.

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

  1. Créez le fichier JSON :

    {
    "inputConfig": {
      "userEventInlineSource": {
          "userEvents": [
            {
              <userEvent1>>
            },
            {
              <userEvent2>
            },
            ....
          ]
        }
      }
    }
    
  2. 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