Importer des informations du catalogue

Cette page explique comment importer les informations de votre catalogue et les maintenir à jour.

Les procédures d'importation présentées 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 les utiliser. Vous n'avez donc pas besoin d'importer les mêmes données deux fois si vous utilisez les deux services.

Importer des données de catalogue à partir de BigQuery

Ce tutoriel vous explique comment utiliser une table BigQuery pour importer de grandes quantités de données de catalogue sans limite.

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

Importer des données de catalogue depuis Cloud Storage

Ce tutoriel vous explique comment importer un grand nombre d'articles dans un catalogue.

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

Importer des données de catalogue de manière intégrée

Ce tutoriel explique comment importer des produits dans un catalogue de façon 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 pouvoir importer les informations de votre catalogue, 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 Administrateur Retail pour effectuer l'importation.

Bonnes pratiques concernant l'importation de catalogues

Des données de haute qualité sont nécessaires pour générer des résultats de haute qualité. Si des champs sont manquants dans vos données ou si elles contiennent des valeurs d'espace réservé plutôt que des valeurs réelles, la qualité de vos prédictions et des résultats de recherche en souffrira.

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

• Réfléchissez bien avant de déterminer quels produits ou groupes de produits sont principaux et lesquels sont des variantes. Avant d'importer des données, consultez la section Niveaux de produit.

  La modification de la configuration au niveau du produit après l'importation de données nécessite un effort considérable.

  Les éléments principaux sont renvoyés sous forme de résultats de recherche ou de recommandations. Les articles de variantes ne le sont pas.

  Par exemple, si le groupe de codes SKU principal est "Chemise à col en V", le modèle de recommandation renvoie une chemise à col en V, et peut-être une chemise à col rond et une chemise à col en V. Toutefois, si les variantes ne sont pas utilisées et que chaque SKU est un SKU principal, chaque combinaison de couleur/taille de la chemise à col en V est renvoyée en tant qu'article distinct dans le panneau de recommandations: "Chemise à col en V marron, taille XL", "Chemise à col en V marron, taille L", jusqu'à "Chemise à col en V blanche, taille M", "Chemise à col en V blanche, taille S".

  Les collections peuvent être reconnues ensemble, car les ID de variante longs sont inclus avec les ID de produits principaux dans collectionMemberIds[]. Une collection de produits, à partir de laquelle un utilisateur peut avoir acheté un ou plusieurs produits de l'ensemble, est ainsi capturée dans l'événement utilisateur, et l'ensemble entier est crédité de l'achat. Cela permet de proposer à l'utilisateur d'autres produits d'une collection donnée lors d'une requête associée ultérieure. Par exemple, d'autres produits d'une collection de draps sont retournés, comme les taies d'oreiller et le drap-housse assortis après qu'un utilisateur a déjà acheté la housse de couette.

• Respectez les limites d'importation de produits.

  Pour les importations groupées depuis Cloud Storage, la taille de chaque fichier doit être inférieure ou égale à 2 Go. Vous pouvez inclure jusqu'à 100 fichiers à la fois dans une seule requête d'importation groupée.

  Pour l'importation intégrée, vous ne pouvez pas importer plus de 5000 produits à la fois.

• Assurez-vous que toutes les informations requises sur le catalogue sont bien incluses et correctes.

  N'utilisez pas de valeurs d'espace réservé.

• Incluez autant d'informations de catalogue facultatives que possible.

• Assurez-vous que tous vos événements utilisent une seule devise, en particulier si vous prévoyez d'utiliser la console Google Cloud pour obtenir des métriques de revenus. L'API Vertex AI Search pour le commerce n'est pas compatible avec l'utilisation de plusieurs devises par catalogue.

• Maintenez votre catalogue à jour.

  Idéalement, vous devez mettre à jour votre catalogue quotidiennement. La planification des importations périodiques du catalogue empêche la qualité du modèle de se dégrader au fil du temps. Vous pouvez planifier des importations récurrentes automatiques lorsque vous importez votre catalogue à l'aide de la console de recherche pour le commerce. Vous pouvez également utiliser Google Cloud Scheduler pour automatiser les importations.

• N'enregistrez pas d'événements utilisateur pour les produits qui n'ont pas encore été importés.

• Une fois que vous avez importé les informations de catalogue, consultez les informations des rapports d'erreurs et de journalisation de votre projet.

  Il est normal qu'il y ait quelques erreurs, mais si vous rencontrez un grand nombre d'erreurs, vous devez les examiner et résoudre les problèmes de processus à l'origine de ces erreurs.

À propos de l'importation de données de catalogue

Vous pouvez importer vos données produit à partir de Merchant Center, Cloud Storage et BigQuery, ou spécifier les données de manière intégrée dans la requête. Ces procédures permettent de réaliser des importations ponctuelles, à l'exception de l'association de Merchant Center. Planifiez des importations régulières de catalogue (idéalement, tous les jours) pour vous assurer que votre catalogue reste bien à jour. Consultez Maintenir votre catalogue à jour.

Vous pouvez également importer des produits individuels. Pour en savoir plus, consultez la section Importer un produit.

Remarques concernant l'importation de catalogues

Cette section décrit les méthodes pouvant être utilisées pour l'importation par lot des données de catalogue, leurs différents cas d'utilisation et certaines de leurs limites.

Supprimer définitivement les branches de catalogue

Si vous importez de nouvelles données de catalogue dans une branche existante, il est important que la branche de catalogue soit vide. Cela garantit l'intégrité des données importées dans la branche. Lorsque la branche est vide, vous pouvez importer de nouvelles données de catalogue, puis associer la branche à un compte marchand.

Si vous diffusez du trafic de prédiction ou de recherche en direct et que vous prévoyez de purger votre branche par défaut, pensez à spécifier d'abord une autre branche comme branche par défaut avant de la purger. Étant donné que la branche par défaut affichera des résultats vides après avoir été purgée, la purge d'une branche par défaut active peut entraîner une panne.

Pour purger les données d'une branche de catalogue, procédez comme suit:

1. Accédez à la page Données> dans la console de la recherche pour le commerce.
   
   Accéder à la page "Données"

2. Sélectionnez une branche de catalogue dans le champ Nom de la branche.

3. Dans le menu à trois points à côté du champ Nom de la branche, sélectionnez Purger la branche.

   Un message s'affiche pour vous avertir que vous êtes sur le point de supprimer toutes les données de la branche, ainsi que tous les attributs créés pour elle.

4. Saisissez la branche, puis cliquez sur Confirmer pour supprimer définitivement les données du catalogue de la branche.

   Une opération de longue durée est lancée pour purger les données de la branche du catalogue. Une fois l'opération de purge terminée, son état s'affiche dans la liste Catalogue de produits de la fenêtre État de l'activité.

Synchroniser Merchant Center avec Vertex AI Search pour le commerce

Pour assurer la synchronisation continue entre Merchant Center et Vertex AI Search pour le commerce, vous pouvez associer votre compte Merchant Center à Vertex AI Search pour le commerce. Une fois l'association effectuée, les informations de catalogue de votre compte Merchant Center sont immédiatement importées dans Vertex AI Search for retail.

Lorsque vous configurez une synchronisation Merchant Center pour Vertex AI Search pour le commerce, vous devez disposer du rôle d'administrateur dans Merchant Center. Bien qu'un rôle d'accès standard vous permette de lire les flux Merchant Center dans l'interface utilisateur, vous recevrez un message d'erreur lorsque vous tenterez de synchroniser Merchant Center avec Vertex AI Search pour le commerce. Par conséquent, avant de pouvoir synchroniser votre compte Merchant Center avec Vertex AI Search pour le commerce, vous devez mettre à niveau votre rôle.

Lorsque Vertex AI Search pour le commerce est associé au compte Merchant Center, les modifications apportées à vos données produit dans le compte Merchant Center sont automatiquement propagées en quelques minutes dans Vertex AI Search pour le commerce. Si vous souhaitez empêcher la synchronisation des modifications Merchant Center avec Vertex AI Search for retail, vous pouvez dissocier votre compte Merchant Center.

La dissociation de votre compte Merchant Center ne supprime pas de produits dans Vertex AI Search pour le commerce. Pour supprimer les produits importés, consultez la section Supprimer des informations produit.

Synchroniser votre compte Merchant Center

Pour synchroniser votre compte Merchant Center, procédez comme suit :

Pour afficher votre compte Merchant Center associé, accédez à la page Données de la console de recherche pour le commerce, puis cliquez sur le bouton Merchant Center en haut à droite de la page. Le panneau Comptes Merchant Center associés s'affiche. Vous pouvez également ajouter des comptes Merchant Center supplémentaires à partir de ce panneau.

Consultez la section Afficher des informations agrégées sur votre catalogue pour savoir comment afficher les produits importés.

Lister les associations à votre compte Merchant Center

Répertoriez les associations de votre compte Merchant Center.

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

Dissocier votre compte Merchant Center

La dissociation de votre compte Merchant Center empêche la synchronisation des données de catalogue de ce compte par Vertex AI Search pour le commerce. Cette procédure ne supprime pas les produits qui ont déjà été importés dans Vertex AI Search pour le commerce.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Limites de l'association à Merchant Center

• Un compte Merchant Center peut être associé à un nombre illimité de branches de catalogue, mais une branche de catalogue donnée ne peut être associée qu'à un seul compte Merchant Center.

• Un compte Merchant Center ne peut pas être un multicompte (MC). Vous pouvez toutefois associer des sous-comptes individuels.

• La première importation après l'association de votre compte Merchant Center peut prendre plusieurs heures. La durée dépend du nombre d'offres dans le compte Merchant Center.

• Les modifications produit effectuées par les méthodes d'API sont désactivées pour les branches associées à un compte Merchant Center. Toute modification des données de catalogue de produits dans ces branches doit être effectuée via Merchant Center. Ces modifications sont ensuite automatiquement synchronisées avec Vertex AI Search pour le commerce.

• Le type de produit de collection n'est pas compatible avec les branches utilisant l'association à Merchant Center.

• Votre compte Merchant Center ne peut être associé qu'à des branches de catalogue vides pour garantir l'exactitude des données. Pour supprimer des produits d'une branche de catalogue, consultez la section Supprimer des informations produit.

Importer des données de catalogue à partir de Merchant Center

Merchant Center est un outil que vous pouvez utiliser pour rendre vos données de magasins et de produits disponibles pour les annonces Shopping et d'autres services Google.

Vous pouvez importer des données de catalogue de façon groupée depuis Merchant Center en tant que procédure ponctuelle à partir de BigQuery à l'aide du schéma Merchant Center (recommandations uniquement).

Importation groupée à partir de Merchant Center

Vous pouvez importer des données de catalogue à partir de Merchant Center en utilisant la console de recherche pour le commerce ou la méthode products.import. L'importation groupée est une procédure ponctuelle, qui n'est compatible qu'avec les recommandations.

Pour importer votre catalogue à partir de Merchant Center, procédez comme suit :

1. À l'aide des instructions de la section Transferts Merchant Center, configurez un transfert de Merchant Center vers BigQuery.

   Vous utiliserez le schéma des tables de produits Google Merchant Center. Configurez votre transfert de manière à ce qu'il se répète quotidiennement, mais configurez le délai d'expiration de l'ensemble de données à deux jours.

2. Si votre ensemble de données BigQuery se trouve dans un autre projet, configurez les autorisations requises pour que Vertex AI Search for retail puisse y accéder. En savoir plus

3. Importez vos données de catalogue depuis BigQuery dans la recherche Vertex AI pour le commerce.

   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 d'importation.

   3. Sélectionnez Catalogue de produits.

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

   5. Sélectionnez la branche dans laquelle vous allez importer votre catalogue.

   6. Sélectionnez Merchant Center comme schéma de données.

   7. Renseignez la table BigQuery dans laquelle se trouvent vos données.

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

   9. Choisissez de planifier ou non une importation récurrente de vos données de catalogue.

   10. Si vous importez votre catalogue pour la première fois ou si vous le réimportez après sa suppression, sélectionnez les niveaux de produit. En savoir plus sur les niveaux de produit.

       La modification de la configuration au niveau du produit après l'importation de données nécessite un effort considérable.

   11. Cliquez sur Importer.

   curl

   1. Si vous importez votre catalogue pour la première fois ou si vous le réimportez après sa suppression, définissez vos niveaux de produits à l'aide de la méthode Catalog.patch. Cette opération nécessite le rôle "Administrateur Retail". En savoir plus sur les niveaux de produit.

      • ingestionProductType : accepte les valeurs primary (par défaut) et variant.
      • merchantCenterProductIdField : accepte les valeurs offerId (par défaut) et itemGroupId. Si vous n'utilisez pas Merchant Center, définissez la valeur par défaut offerId.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT_TYPE",
        "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Importez votre catalogue en utilisant la méthode Products.import.

      • DATASET_ID : ID de l'ensemble de données BigQuery.
      • TABLE_ID : ID de la table BigQuery contenant vos données.
      • STAGING_DIRECTORY : facultatif. Un répertoire Cloud Storage utilisé comme emplacement provisoire pour vos données avant leur importation dans BigQuery. Laissez ce champ vide pour créer automatiquement un répertoire temporaire (recommandé).
      • ERROR_DIRECTORY : facultatif. Un répertoire Cloud Storage contenant des informations sur les erreurs d'importation. Laissez ce champ vide pour créer automatiquement un répertoire temporaire (recommandé).
      • dataSchema : pour la propriété dataSchema, utilisez la valeur product_merchant_center. Consultez le schéma des tables de produits Merchant Center.

      Nous vous recommandons de ne pas spécifier de répertoires de préproduction ou d'erreur. Vous pourrez ainsi créer automatiquement un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur. Ces répertoires sont créés dans la même région que l'ensemble de données BigQuery et sont uniques pour chaque importation (ce qui empêche plusieurs tâches d'importation de préparer des données dans le même répertoire et de potentiellement réimporter les mêmes données). Après trois jours, le bucket et les répertoires sont automatiquement supprimés afin de réduire les coûts de stockage.

      Un nom de bucket créé automatiquement inclut l'ID du projet, la région du bucket et le nom du schéma de données, séparés par des traits de soulignement (par exemple, 4321_us_catalog_retail). Les répertoires créés automatiquement sont appelés staging ou errors, et un numéro (par exemple, staging2345 ou errors5678) leur est ajouté.

      Si vous spécifiez des répertoires, le bucket Cloud Storage doit se trouver dans la même région que l'ensemble de données BigQuery. Dans le cas contraire, l'importation échoue. Fournissez les répertoires de préproduction et d'erreur au format gs://<bucket>/<folder>/ (ils doivent être différents).

     curl -X POST \
          -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
          -H "Content-Type: application/json; charset=utf-8" \
          --data '{
            "inputConfig":{
               "bigQuerySource": {
                 "datasetId":"DATASET_ID",
                 "tableId":"TABLE_ID",
                 "dataSchema":"product_merchant_center"
               }
             }
         }' \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Importer des données de catalogue à partir de BigQuery

Pour importer des données de catalogue au format approprié à partir de BigQuery, utilisez le schéma Vertex AI Search for retail pour créer une table BigQuery au format approprié et remplissez la table vide avec vos données de catalogue. Ensuite, importez vos données dans Vertex AI Search pour le commerce.

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.

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

Pour importer votre catalogue, procédez comme suit :

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

2. Importez vos données de catalogue dans Vertex AI Search pour le commerce.

   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 Catalogue de produits.
   4. Sélectionnez BigQuery comme source de données.
   5. Sélectionnez la branche dans laquelle vous allez importer votre catalogue.
   6. Sélectionnez Schéma Retail pour les catalogues de produits. Voici le schéma de produit pour Vertex AI Search pour le commerce.
   7. Renseignez la table BigQuery dans laquelle se trouvent vos données.
   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. Si la recherche n'est pas activée et que vous utilisez le schéma Merchant Center, sélectionnez le niveau de produit.
      
      Vous devez sélectionner le niveau de produit si vous importez votre catalogue pour la première fois ou si vous le réimportez après l'avoir supprimé. En savoir plus sur les niveaux de produit La modification des niveaux de produit après l'importation de données nécessite un effort considérable.
      
      Important:Vous ne pouvez pas activer la recherche pour les projets avec un catalogue de produits ingéré en tant que variantes.
   10. Cliquez sur Importer.

   curl

   1. Si vous importez votre catalogue pour la première fois ou si vous le réimportez après sa suppression, définissez vos niveaux de produits à l'aide de la méthode Catalog.patch. Cette opération nécessite le rôle "Administrateur Retail".

      • ingestionProductType : accepte les valeurs primary (par défaut) et variant.
      • merchantCenterProductIdField : accepte les valeurs offerId et itemGroupId. Si vous n'utilisez pas Merchant Center, vous n'avez pas besoin de définir ce champ.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Créez un fichier de données pour les paramètres d'entrée de l'importation.

      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.
      • PROJECT_ID : ID du projet dans lequel se trouve la source BigQuery S'il n'est pas spécifié, l'ID du projet est hérité de la requête parente.
      • STAGING_DIRECTORY : facultatif. Un répertoire Cloud Storage utilisé comme emplacement provisoire pour vos données avant leur importation dans BigQuery. Laissez ce champ vide pour créer automatiquement un répertoire temporaire (recommandé).
      • ERROR_DIRECTORY : facultatif. Un répertoire Cloud Storage contenant des informations sur les erreurs d'importation. Laissez ce champ vide pour créer automatiquement un répertoire temporaire (recommandé).
      • dataSchema : pour la propriété dataSchema, utilisez la valeur product (par défaut). Vous utiliserez le schéma Vertex AI Search pour le commerce.

      Nous vous recommandons de ne pas spécifier de répertoires de préproduction ou d'erreur. Vous pourrez ainsi créer automatiquement un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur. Ces répertoires sont créés dans la même région que l'ensemble de données BigQuery et sont uniques pour chaque importation (ce qui empêche plusieurs tâches d'importation de préparer des données dans le même répertoire et de potentiellement réimporter les mêmes données). Après trois jours, le bucket et les répertoires sont automatiquement supprimés afin de réduire les coûts de stockage.

      Un nom de bucket créé automatiquement inclut l'ID du projet, la région du bucket et le nom du schéma de données, séparés par des traits de soulignement (par exemple, 4321_us_catalog_retail). Les répertoires créés automatiquement sont appelés staging ou errors, et un numéro (par exemple, staging2345 ou errors5678) leur est ajouté.

      Si vous spécifiez des répertoires, le bucket Cloud Storage doit se trouver dans la même région que l'ensemble de données BigQuery. Dans le cas contraire, l'importation échoue. Fournissez les répertoires de préproduction et d'erreur au format gs://<bucket>/<folder>/ (ils doivent être différents).

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }

   3. Importez vos informations de catalogue en envoyant une requête POST à la méthode REST Products:import, en fournissant le nom du fichier de données (ici, comme suit : 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/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products: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/import-products-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 import, jusqu'à ce que le champ done renvoie true :

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-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/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.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.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Vous pouvez inspecter les fichiers du répertoire d'erreurs dans Cloud Storage pour voir si des erreurs se sont produites lors de l'importation.

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 de recherche Vertex AI pour le commerce, procédez comme suit :

1. Ouvrez la page "IAM" dans Google Cloud Console.

   Ouvrir la page IAM

2. Sélectionnez votre projet Vertex AI Search pour le commerce.

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

   Si vous n'avez pas encore lancé d'opération d'importation, 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, service-525@gcp-sa-retail.iam.gserviceaccount.com).

5. Basculez vers votre projet BigQuery (sur la même page IAM et administration), puis cliquez sur person_add Accorder l'accès.

6. Pour Nouveaux principaux, saisissez l'identifiant du compte de service Vertex AI Search for retail et sélectionnez le rôle BigQuery > Utilisateur BigQuery.

7. Cliquez sur Ajouter un autre rôle, puis sélectionnez BigQuery > Éditeur de données BigQuery.

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

8. Cliquez sur Enregistrer.

Importer des données de catalogue depuis Cloud Storage

Pour importer des données de catalogue au format JSON, créez un ou plusieurs fichiers JSON contenant les données de catalogue que vous souhaitez importer, puis importez ces données dans Cloud Storage. Vous pouvez ensuite les importer dans Vertex AI Search pour le commerce.

Pour obtenir un exemple de format d'élément de produit JSON, consultez la section Format de données JSON d'élément de produit.

Pour obtenir de l'aide concernant l'importation de fichiers dans Cloud Storage, consultez la page Importer des objets.

1. Assurez-vous que le compte de service Vertex AI Search pour le commerce est autorisé à lire et écrire dans le bucket.

   Le compte de service Vertex AI Search for retail est répertorié sur la page IAM de la console Google Cloud sous le nom Compte de service Retail. Utilisez l'identifiant du compte de service qui ressemble à une adresse e-mail (par exemple, service-525@gcp-sa-retail.iam.gserviceaccount.com) pour ajouter le compte à vos autorisations de bucket.

2. Importez les données de votre catalogue.

   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 Catalogue de produits comme source de données.
   4. Sélectionnez la branche dans laquelle vous allez importer votre catalogue.
   5. Sélectionnez Schéma des catalogues de produits Retail comme schéma.
   6. Saisissez l'emplacement Cloud Storage de vos données.
   7. Si la recherche n'est pas activée, sélectionnez les niveaux de produit.
      
      Vous devez sélectionner les niveaux de produit si vous importez votre catalogue pour la première fois ou si vous le réimportez après l'avoir supprimé. En savoir plus sur les niveaux de produit La modification des niveaux de produit après l'importation de données nécessite un effort considérable.
      
      Important:Vous ne pouvez pas activer la recherche pour les projets avec un catalogue de produits ingéré en tant que variantes.
   8. Cliquez sur Importer.

   curl

   1. Si vous importez votre catalogue pour la première fois ou si vous le réimportez après sa suppression, définissez vos niveaux de produits à l'aide de la méthode Catalog.patch. En savoir plus sur les niveaux de produit.

      • ingestionProductType : accepte les valeurs primary (par défaut) et variant.
      • merchantCenterProductIdField : accepte les valeurs offerId et itemGroupId. Si vous n'utilisez pas Merchant Center, vous n'avez pas besoin de définir ce champ.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. 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 ; cet exemple utilise deux fichiers.

      • INPUT_FILE : un ou plusieurs fichiers Cloud Storage contenant vos données de catalogue.
      • 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, il est créé. Le bucket doit déjà exister.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }

   3. Importez vos informations de catalogue en envoyant une requête POST à la méthode REST Products:import, en fournissant le nom du fichier de données (ici, comme suit : 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/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      Le moyen le plus simple de vérifier l'état de votre opération d'importation consiste à utiliser la console Google Cloud. Pour en savoir plus, consultez la section Afficher l'état d'une opération d'intégration spécifique.

      Vous pouvez aussi 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/import-products-123456",
      "done": false
      }

      Le champ de nom est l'ID de l'objet d'opération. Il vous suffit d'interroger l'état de cet objet en remplaçant le champ de nom par la valeur renvoyée par la méthode d'importation jusqu'à ce que le champ done renvoie true :

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

      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/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.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.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Vous pouvez inspecter les fichiers du répertoire d'erreurs dans Cloud Storage pour voir le type d'erreurs survenues lors de l'importation.

Importer des données de catalogue de manière intégrée

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Format des données JSON de produit

Les entrées Product de votre fichier JSON doivent ressembler aux exemples suivants.

Fournissez chaque produit sur une seule ligne. et chaque produit doit se trouver sur une ligne distincte.

Champs obligatoires minimum :

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

Objet complet :

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

Historique de données de catalogue

Vertex AI Search pour le commerce permet d'importer et de gérer l'historique des données de catalogue. L'historique des données de catalogue peut être utile lorsque vous utilisez l'historique des événements utilisateur pour l'entraînement de modèle. Les informations sur les anciens produits peuvent être utilisées pour enrichir l'historique des données d'événements utilisateur et améliorer la précision du modèle.

Les anciens produits sont stockés sous la forme de produits arrivés à expiration. Ils ne sont pas renvoyés dans les réponses de recherche, mais sont visibles par les appels d'API Update, List et Delete.

Importer l'historique de données de catalogue

Lorsque le champ expireTime d'un produit est défini sur un horodatage antérieur, ce produit est considéré comme un ancien produit. Définissez le champ de disponibilité du produit sur OUT_OF_STOCK (ÉPUISÉ) pour ne pas affecter les recommandations.

Nous vous recommandons d'utiliser les méthodes suivantes pour importer les données de l'historique du catalogue :

• Appel de la méthode Product.Create.
• Importation intégrée de produits arrivés à expiration
• Importer des produits arrivés à expiration à partir de BigQuery

Appeler la méthode Product.Create

Utilisez la méthode Product.Create pour créer une entrée Product avec le champ expireTime défini sur un horodatage antérieur.

Importation intégrée de produits arrivés à expiration

Les étapes sont identiques à celles de l'importation intégrée, à la différence que les champs expireTime des produits doivent être définis sur un horodatage dans le passé.

Fournissez chaque produit sur une seule ligne. et chaque produit doit se trouver sur une ligne distincte.

Voici un exemple de ./data.json utilisé dans la requête d'importation intégrée :

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Importer des produits arrivés à expiration à partir de BigQuery ou de Cloud Storage

Suivez les mêmes procédures que celles décrites pour importer des données de catalogue à partir de BigQuery ou importer des données de catalogue à partir de Cloud Storage. Veillez toutefois à définir le champ expireTime sur un code temporel passé.

Maintenir votre catalogue à jour

Pour obtenir des résultats optimaux, votre catalogue doit contenir des informations à jour. Nous vous recommandons d'importer votre catalogue quotidiennement pour vous assurer qu'il reste bien à jour. Vous pouvez utiliser Google Cloud Scheduler pour planifier les importations ou choisir une option de planification automatique lorsque vous importez des données à l'aide de la console Google Cloud.

Vous pouvez ne mettre à jour que les produits nouveaux ou modifiés, ou importer l'intégralité du catalogue. Si vous importez des produits qui figurent déjà dans votre catalogue, ils ne sont pas ajoutés à nouveau. Tous les produits modifiés sont mis à jour.

Pour mettre à jour un seul produit, consultez la section Mettre à jour les informations produit.

Mise à jour groupée

Vous pouvez utiliser la méthode d'importation pour mettre à jour votre catalogue de manière groupée. 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 catalogue.

Surveiller l'état des importations

Pour surveiller l'ingestion et l'état du catalogue:

1. Affichez des informations agrégées sur votre catalogue et prévisualisez les produits importés dans l'onglet Catalogue de la page Rechercher des données.

   Accéder à la page "Données"

2. Évaluez si vous devez mettre à jour les données du catalogue pour améliorer la qualité des résultats de recherche et débloquer les niveaux de performances de recherche sur la page Qualité des données.

   Pour savoir comment vérifier la qualité des données de recherche et afficher les niveaux de performances de recherche, consultez Débloquer les niveaux de performances de recherche. Pour obtenir un récapitulatif des métriques de qualité du catalogue disponibles sur cette page, consultez la section Métriques de qualité du catalogue.

   Accéder à la page "Qualité des données"

3. Pour créer des alertes qui vous informent en cas de problème avec vos importations de données, suivez les procédures décrites dans Configurer des alertes Cloud Monitoring.

   Pour obtenir des résultats de haute qualité, il est important de maintenir votre catalogue à jour. Utilisez des alertes pour surveiller les taux d'erreur d'importation et prendre des mesures, le cas échéant.

Étape suivante

• Commencez à enregistrer des événements utilisateur.
• Affichez des informations agrégées sur votre catalogue.
• Configurez des alertes d'importation de données.