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 données de saisie semi-automatique

La saisie semi-automatique est une fonctionnalité permettant de prédire la fin d'un mot saisi par un utilisateur, ce qui améliore l'expérience de recherche des utilisateurs. Cette fonctionnalité peut fournir des suggestions basées sur l'ensemble de données ou sur les événements utilisateur que vous lui fournissez.

Cette page explique comment importer l'ensemble de données de saisie semi-automatique dans Retail. Ces instructions ne concernent que l'importation de vos propres données de saisie semi-automatique. Prévoyez des mises à jour régulières si vous comptez utiliser systématiquement votre propre ensemble de données de saisie semi-automatique. Pour mettre en œuvre la saisie semi-automatique, consultez la section CompletionService.CompleteQuery. Les données de saisie semi-automatique ne sont utilisées que pour Retail Search. Ces données ne sont pas utilisées par Recommendations AI.

Avant de commencer

Pour pouvoir importer vos informations de saisie semi-automatique, vous devez avoir suivi les instructions de la section Avant de commencer, en particulier celles spécifiques à la configuration de votre projet, à la création d'un compte de service et à l'ajout de votre compte de service à votre environnement local.

Vous devez disposer du rôle IAM Éditeur Retail pour pouvoir effectuer l'importation.

Bonnes pratiques relatives à l'importation de saisie semi-automatique

Lorsque vous importez des données de saisie semi-automatique, veillez à mettre en œuvre les bonnes pratiques suivantes :

  • Lisez les fichiers de schéma présentés dans les sections suivantes et la documentation de l'API.

    N'utilisez pas de valeurs factices ou de remplacement (espaces réservés).

  • Incluez autant de champs que possible.

  • Si vous prévoyez d'utiliser votre propre ensemble de données importé, veillez à maintenir votre propre ensemble de données de saisie semi-automatique à jour.

Importer des données de saisie semi-automatique

Importer des données de saisie semi-automatique depuis BigQuery

Pour importer des données de saisie semi-automatique au format approprié à partir de BigQuery, utilisez le schéma de saisie semi-automatique de Retail pour créer une table BigQuery au bon format puis insérez dans la table vos données de saisie semi-automatique. Ensuite, importez vos données dans Retail.

Pour plus d'informations sur les tables BigQuery, consultez la page Présentation des tables. Pour obtenir de l'aide sur les requêtes BigQuery, consultez la page Présentation des requêtes de données dans BigQuery.

Insérer des données dans BigQuery

Utilisez le schéma de saisie semi-automatique de Retail pour importer vos données de saisie semi-automatique dans BigQuery.

BigQuery peut utiliser le schéma pour vérifier si les données au format JSON présentent des noms et des types de champ corrects (tels que STRING, INTEGER et RECORD), mais n'est pas capable de vérifier :

  • Si un champ de chaîne est mappé sur une valeur d'énumération reconnaissable.
  • Si un champ de chaîne utilise le format approprié.
  • Si la valeur d'un champ de type entier ou nombre à virgule flottante se situe dans une plage valide.
  • Si un champ manquant est un champ obligatoire.

Pour garantir la qualité de vos données et de l'expérience de recherche des utilisateurs finaux, veillez à vous reporter au schéma et à la documentation de référence pour plus de détails sur les valeurs et sur les formats à utiliser.

Importer des données de saisie semi-automatique dans Retail

curl

  1. Si votre ensemble de données BigQuery se trouve dans un autre projet, configurez les autorisations requises pour que Retail puisse y accéder. En savoir plus

  2. Créez un fichier de données pour les paramètres d'entrée de l'importation. Les valeurs de vos paramètres d'entrée varient selon que vous importez depuis Cloud Storage ou BigQuery.

    Utilisez l'objet BigQuerySource pour pointer vers votre ensemble de données BigQuery.

    • dataset-id : ID de l'ensemble de données BigQuery.
    • table-id : ID de la table BigQuery contenant vos données.
    • data-schema : pour la propriété dataSchema, utilisez les valeurs suggestions (par défaut), allowlist et denylist. Vous utiliserez le schéma de saisie semi-automatique Retail.
    {
      "inputConfig":{
        "bigQuerySource": {
          "datasetId":"dataset-id",
          "tableId":"table-id",
          "dataSchema":"data-schema"
        }
      }
    }
    
  3. Importez vos informations de saisie semi-automatique dans Retail en envoyant une requête POST à la méthode REST CompletionData:import, en fournissant le nom du fichier de données (affiché ici sous la forme input.json).

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" -d @./input.json
    "https://retail.googleapis.com/v2alpha/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/completionData:import"
    

    Vous pouvez vérifier l'état de manière automatisée avec l'API. Vous devriez recevoir un objet de réponse ressemblant à ceci :

    {
      "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456",
      "done": false
    }
    

    Le champ de nom est l'ID de l'objet d'opération. Pour demander l'état de cet objet, remplacez le champ de nom par la valeur renvoyée par la méthode d'importation, jusqu'à ce que le champ done affiche true :

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2alpha/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456"
    

    Une fois l'opération terminée, l'objet renvoyé a une valeur done de true et inclut un objet "Status" semblable à l'exemple suivant :

    {
      "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true
      "response": {
        "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
      }
    }
    

Configurer l'accès à votre ensemble de données BigQuery

Pour configurer l'accès lorsque l'ensemble de données BigQuery se trouve dans un projet différent de celui de votre service Retail, procédez comme suit.

  1. Ouvrez la page IAM dans Cloud Console.

    Ouvrir la page IAM

  2. Sélectionnez votre projet Retail.

  3. Recherchez le compte de service intitulé Compte de service Retail.

    Si vous n'avez pas encore lancé d'opération d'importation avec Retail, ce compte de service peut ne pas être répertorié. Si vous ne voyez pas le compte de service, revenez à la tâche d'importation et lancez l'importation. Si la tâche échoue en raison d'erreurs d'autorisation, revenez sur la page et cherchez à nouveau le compte de service.

  4. Copiez l'identifiant du compte de service, qui ressemble à une adresse e-mail (par exemple, cloud-retail-customer-data-access@system.gserviceaccount.com).

  5. Dans IAM et administration, cliquez sur Ajouter.

  6. Saisissez l'identifiant du compte de service Retail et sélectionnez le rôle BigQuery > Lecteur de données BigQuery.

    Si vous ne souhaitez pas attribuer le rôle de lecteur de données sur l'ensemble du projet, vous pouvez l'ajouter directement au niveau de l'ensemble de données. En savoir plus

  7. Cliquez sur Enregistrer.

Format des données de saisie semi-automatique

Votre fichier JSON doit ressembler aux exemples suivants. Les sauts de ligne ne sont là que pour des raisons de lisibilité. Vous devez fournir une suggestion entière sur une seule ligne. Chaque suggestion doit figurer sur une ligne distincte.

Champs obligatoires pour la suggestion :

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

ou

{
  "suggestion": "ABC",
  "frequency": "100"
}

Durée d'importation des données de saisie semi-automatique

Généralement, il faut environ 10 heures pour effectuer une importation depuis BigQuery. Cette opération de longue durée transfère l'ensemble de données pour la diffusion en production. Une fois que l'ensemble de données est prêt pour la diffusion, le champ done de l'objet d'opération est marqué comme "true". Avant l'opération done, il n'est pas garanti que vous obteniez la dernière suggestion de l'ensemble de données d'importation.

Maintenir votre ensemble de données de saisie semi-automatique à jour

Si vous prévoyez d'utiliser votre propre ensemble de données importé, il est recommandé de maintenir régulièrement l'ensemble de données importé à jour.

Mise à jour groupée

Vous pouvez utiliser la méthode d'importation pour la mise à jour groupée de votre saisie semi-automatique. Vous procédez de la même manière que pour l'importation initiale. Il suffit de suivre la procédure décrite dans la section Importer des données de saisie semi-automatique. Cette action remplacera l'intégralité de l'ensemble de données importé.

Surveiller l'état des importations

Pour toujours obtenir des suggestions de haute qualité lorsque vous utilisez la saisie semi-automatique, il est important de maintenir votre ensemble de données à jour. Vous devez surveiller les taux d'erreur d'importation et prendre des mesures, le cas échéant.

Schéma de saisie semi-automatique

Lorsque vous importez un ensemble de données de saisie semi-automatique depuis BigQuery, utilisez le schéma Retail ci-dessous pour créer des tables BigQuery au format approprié dans lesquelles vous pourrez charger vos données de saisie semi-automatique.

Schéma des suggestions

Cet ensemble de données permet de suggérer des expressions en utilisant "typeahead".

Schéma de la liste de blocage

Cet ensemble de données est utilisé comme liste de blocage pour empêcher la suggestion de certaines expressions.

Schéma de la liste d'autorisation

Cet ensemble de données permet d'ignorer les processus de post-traitement (correction orthographique, par exemple) pour toutes les expressions présentes dans cette liste d'autorisation.