Importer les informations du catalogue

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

Les procédures d'importation de cette page s'appliquent à la fois aux recommandations et à la recherche. Une fois les données importé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.

Importer des données de catalogue à partir de BigQuery

Ce tutoriel 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'éléments 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 intégrés 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

---

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é. S'il manque des champs dans vos données ou qu'elles contiennent des valeurs d'espace réservé à la place de valeurs réelles, la qualité de vos prédictions et des résultats de recherche en pâtira.

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

• Veillez à bien réfléchir lorsque vous déterminez quels produits ou groupes de produits sont les produits principaux et ceux qui sont des variantes. Avant d'importer des données, consultez Niveaux de produit.

  Modifier la configuration au niveau du produit après avoir importé des données nécessite un effort important.

  Les éléments principaux sont renvoyés sous forme de résultats de recherche ou de recommandations. Ce n'est pas le cas des éléments de variante.

  Par exemple, si le groupe de SKU principal est "T-shirt à col en V", le modèle de recommandation renvoie une chemise à col en V et, éventuellement, une chemise à col ras-du-cou et une chemise à col scoop. Toutefois, si les variantes ne sont pas utilisées et que chaque SKU est un code principal, chaque combinaison couleur/taille de chemise à col en V est renvoyée en tant qu'article distinct dans le panneau des recommandations: "chemise à col en V marron, taille XL", "chemise à col en V marron, taille L", "chemise à col en V blanc, taille M", "chemise à col en V blanc, taille S".

• 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 sur les revenus. L'API Vertex AI Search pour le commerce ne permet pas d'utiliser 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 Search for Retail. 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. Chacune de ces procédures est une importation unique, sauf en cas d'association de Merchant Center. Planifiez des importations régulières de votre catalogue (idéalement, tous les jours) pour vous assurer que votre catalogue est à jour. Consultez Mettre à jour votre catalogue.

Vous pouvez également importer des produits individuels. Pour en savoir plus, consultez 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.

Synchronisation Merchant Center	Description	Importe les données du catalogue via Merchant Center en associant le compte à Vertex AI Search pour le commerce. Une fois l'association effectuée, les mises à jour des données du catalogue dans Merchant Center sont synchronisées en temps réel avec Vertex AI Search pour le commerce.
	Contexte d'utilisation	Si vous disposez déjà d'une intégration avec Merchant Center.
	Limites	Compatibilité limitée des schémas. Par exemple, les collections de produits ne sont pas compatibles avec Merchant Center. Merchant Center devient la source unique de données jusqu'à ce qu'il soit dissocié. Par conséquent, tous les attributs personnalisés nécessaires doivent être ajoutés aux données Merchant Center. Contrôle limité. Vous ne pouvez pas spécifier de champs ou d'ensembles d'éléments spécifiques à importer depuis Merchant Center. Tous les éléments et champs existants dans Merchant Center sont importés automatiquement.
BigQuery	Description	Importez des données à partir d'une table BigQuery précédemment chargée qui utilise le schéma Vertex AI Search pour le commerce ou le schéma Merchant Center. Cette méthode peut être effectuée à l'aide de la console Google Cloud ou de curl.
	Contexte d'utilisation	Si vous avez des catalogues de produits avec de nombreux attributs. L'importation BigQuery utilise le schéma Vertex AI Search pour le commerce, qui comporte plus d'attributs de produit que d'autres options d'importation, y compris les attributs personnalisés de clé-valeur. Si vous disposez d'importants volumes de données. L'importation BigQuery n'a pas de limite de données. Si vous utilisez déjà BigQuery.
	Limites	Nécessite une étape supplémentaire pour créer une table BigQuery mappée au schéma Vertex AI Search pour le commerce.
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 la console Google Cloud ou de curl. Utilise le format de données JSON Product, qui permet d'utiliser des attributs personnalisés.
	Contexte d'utilisation	Si vous devez charger une grande quantité de données en une seule étape.
	Limites	Non idéal pour les catalogues avec des mises à jour fréquentes de l'inventaire et des prix, car les modifications ne sont pas immédiatement prises en compte.
Importation intégrée	Description	Importer à l'aide d'un appel à la méthode Product.import Utilise l'objet ProductInlineSource, qui comporte moins d'attributs de catalogue de produits que le schéma Vertex AI Search pour le commerce, mais qui accepte les attributs personnalisés.
	Contexte d'utilisation	Si vous disposez de données de catalogue plates et non relationnelles, ou d'une fréquence élevée de mises à jour des quantités ou des prix.
	Limites	Vous ne pouvez pas importer plus de 100 éléments de catalogue à la fois. Cependant, il est possible d'effectuer de nombreuses étapes de chargement et aucune limite ne s'applique aux éléments.

Supprimer définitivement les branches du 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 recherche ou de prédiction en temps réel et que vous prévoyez de supprimer définitivement votre branche par défaut, envisagez de spécifier une autre branche par défaut avant de la supprimer définitivement. Étant donné que la branche par défaut affiche des résultats vides après sa suppression définitive, la purge d'une branche par défaut active peut entraîner une panne.

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

1. Accédez à la page Données> de la console Search for Retail.
   
   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 Purge branche (Supprimer définitivement 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 la branche.

   Remarque :Vous ne pouvez pas annuler la suppression définitive des données d'une branche de catalogue.

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

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

   Remarque :La liste des données de catalogue de la branche n'est pas automatiquement actualisée une fois la suppression définitive terminée. Vous devez actualiser la page pour afficher la liste mise à jour de la branche.

Synchroniser Merchant Center avec Vertex AI Search pour le commerce

Pour une 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 pour le commerce.

Alors que 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 mises à jour en quelques minutes dans Vertex AI Search pour le commerce. Si vous souhaitez empêcher la synchronisation des modifications apportées à Merchant Center avec Vertex AI Search pour le commerce, vous pouvez dissocier votre compte Merchant Center.

Dissocier votre compte Merchant Center ne supprime aucun produit de Vertex AI Search pour le commerce. Pour supprimer des produits importés, consultez Supprimer des informations produit.

Synchroniser votre compte Merchant Center

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

Console

1. Accédez à la page Données> de la console Search for Retail.
   
   Accéder à la page "Données"
2. Cliquez sur Import (Importer) pour ouvrir le panneau Import Data (Importer des données).
3. Sélectionnez Catalogue de produits.
4. Sélectionnez Merchant Center Sync comme source de données.
5. Sélectionnez votre compte Merchant Center. Si votre compte n'apparaît pas, vérifiez Accès des utilisateurs.
6. Facultatif: Sélectionnez Filtre des flux Merchant Center pour n'importer que les offres des flux sélectionnés.
   
   Si ce n'est pas le cas, les offres de tous les flux sont importées (y compris les futurs flux).
7. Facultatif: Pour importer uniquement les offres ciblant certains pays ou certaines langues, développez Afficher les options avancées, puis sélectionnez les pays de vente de Merchant Center et les langues à filtrer.
8. Sélectionnez la branche dans laquelle vous allez importer votre catalogue.
9. Cliquez sur Import (Importer).

curl

1. Vérifiez que le compte de service de votre environnement local a accès à la fois au compte Merchant Center et à Vertex AI Search pour le commerce. Pour vérifier quels comptes ont accès à votre compte Merchant Center, consultez la section Accès des utilisateurs à Merchant Center.

2. Utilisez la méthode MerchantCenterAccountLink.create pour établir l'association.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
    --data '{
     "merchantCenterAccountId": MERCHANT_CENTER_ID,
     "branchId": "BRANCH_ID",
     "feedFilters": [
       {"primaryFeedId": PRIMARY_FEED_ID_1}
       {"primaryFeedId": PRIMARY_FEED_ID_2}
     ],
     "languageCode": "LANGUAGE_CODE",
     "feedLabel": "FEED_LABEL",
    }' \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
   

   • MERCHANT_CENTER_ID: ID du compte Merchant Center.
   • BRANCH_ID: ID de la branche avec laquelle établir l'association. Accepte les valeurs "0", "1" ou "2".
   • LANGUAGE_CODE (FACULTATIF) : code de langue à deux lettres des produits que vous souhaitez importer. Comme indiqué dans Merchant Center, sous la colonne Language du produit. Si cette règle n'est pas configurée, toutes les langues sont importées.
   • FEED_LABEL: (FACULTATIF) libellé de flux des produits que vous souhaitez importer. Vous pouvez voir le libellé du flux dans Merchant Center au niveau de la colonne Libellé du flux associée au produit. Si cette règle n'est pas configurée, tous les libellés de flux sont importés.
   • FEED_FILTERS (FACULTATIF) : liste des flux principaux à partir desquels les produits seront importés. Si vous ne sélectionnez pas de flux, cela signifie que tous les flux du compte Merchant Center sont partagés. Vous trouverez ces ID dans la ressource "Flux de données" de Content API. Vous pouvez aussi accéder à Merchant Center, sélectionner un flux et obtenir l'ID du flux à partir du paramètre dataSourceId dans l'URL du site. Par exemple, mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID.

Pour afficher le compte Merchant Center associé, accédez à la page Données de la console Search for Retail, puis cliquez sur le bouton Merchant Center en haut à droite. Le panneau Comptes Merchant Center associés s'ouvre. Vous pouvez également ajouter d'autres comptes Merchant Center à partir de ce panneau.

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

Lister vos associations à des comptes Merchant Center

Listez vos associations à des comptes Merchant Center.

Console

1. Accédez à la page Données> de la console Search for Retail.
   
   Accéder à la page "Données"

2. Cliquez sur le bouton Merchant Center en haut à droite de la page pour ouvrir la liste de vos comptes Merchant Center associés.

curl

Utilisez la méthode MerchantCenterAccountLink.list pour répertorier les ressources des liens.

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

Lorsque vous dissociez votre compte Merchant Center, il ne synchronise plus les données du catalogue avec Vertex AI Search pour le commerce. Cette procédure ne supprime aucun produit de Vertex AI Search pour le commerce qui a déjà été importé.

Console

1. Accédez à la page Données> de la console Search for Retail.
   
   Accéder à la page "Données"

2. Cliquez sur le bouton Merchant Center en haut à droite de la page pour ouvrir la liste de vos comptes Merchant Center associés.

3. Cliquez sur Dissocier à côté du compte Merchant Center que vous dissociez, puis confirmez votre choix dans la boîte de dialogue qui s'affiche.

curl

Utilisez la méthode MerchantCenterAccountLink.delete pour supprimer la ressource MerchantCenterAccountLink.

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). Toutefois, vous pouvez 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.

• Toute modification de produit effectuée à l'aide des méthodes d'API est désactivée 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. Les 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 Supprimer des informations produit.

Importer les données du catalogue depuis 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 de manière groupée les données du catalogue depuis Merchant Center en une seule fois depuis BigQuery à l'aide du schéma Merchant Center (recommandations uniquement).

Importation groupée depuis Merchant Center

Vous pouvez importer des données de catalogue depuis Merchant Center à l'aide de la console Search for Retail ou de la méthode products.import. L'importation groupée est une procédure unique qui n'est acceptée que pour 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 afin que Vertex AI Search pour le commerce puisse accéder à l'ensemble de données BigQuery. En savoir plus

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

   Console

   1. Accédez à la page Données> de la console Search for Retail.
      
      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: indiquez l'emplacement d'un bucket Cloud Storage dans 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.

       Modifier la configuration au niveau du produit après avoir importé des données nécessite un effort important.

       Important :Vous ne pouvez pas activer la recherche de projets avec un catalogue de produits qui n'a été ingéré qu'en tant que variantes. Si vous souhaitez utiliser la recherche et ingérer des variantes, indiquez le niveau de produit primary.

   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 sur 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 ni de répertoires d'erreurs. De cette façon, un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur pourra être créé automatiquement. 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 jobs d'importation de préparer des données dans le même répertoire, et potentiellement de les réimporter). 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 bon format à partir de BigQuery, utilisez le schéma Vertex AI Search pour le commerce afin de créer une table BigQuery au format approprié et de charger la table vide avec les données de votre 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 afin que Vertex AI Search pour le commerce puisse accéder à l'ensemble de données BigQuery. En savoir plus

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

   Console

   1. Accédez à la page Données> de la console Search for Retail.
      
      Accéder à la page "Données"
   2. Cliquez sur Import (Importer) pour ouvrir le panneau Import Data (Importer des 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 Retail Product Catalogs Schema (Schéma Retail Product Catalogs). Il s'agit du schéma produit de 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 dans votre projet en tant qu'emplacement temporaire pour vos données.
      
      Si aucune valeur n'est spécifiée, un emplacement par défaut est utilisé. Si cette option est spécifiée, les buckets BigQuery et 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 du produit.
      
      Vous devez sélectionner le niveau du produit si vous importez votre catalogue pour la première fois ou si vous réimportez le catalogue après l'avoir purgé. En savoir plus sur les niveaux de produits La modification des niveaux de produit après l'importation des données demande un effort important.
      
      Important:Vous ne pouvez pas activer la recherche de 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 ni de répertoires d'erreurs. De cette façon, un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur pourra être créé automatiquement. 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 jobs d'importation de préparer des données dans le même répertoire, et potentiellement de les réimporter). 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 les informations de votre catalogue en envoyant une requête POST à la méthode REST Products:import, en fournissant le nom du fichier de données (ici, 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 votre ensemble de données BigQuery se trouve dans un projet différent de celui de votre service Vertex AI Search 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 déjà lancé d'opération d'importation, il est possible que ce compte de service ne figure pas dans la liste. 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, [e-mail]).

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

6. Sous Nouveaux comptes principaux, saisissez l'identifiant du compte de service Vertex AI Search pour le commerce 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 l'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 dispose de l'autorisation de lecture et d'écriture dans le bucket.

   Le compte de service Vertex AI Search pour le commerce 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, [e-mail]) pour ajouter le compte à vos autorisations de bucket.

2. Importez les données de votre catalogue.

   Console

   1. Accédez à la page Données> de la console Search for Retail.
      
      Accéder à la page "Données"
   2. Cliquez sur Import (Importer) pour ouvrir le panneau Import Data (Importer des 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 Retail Product Catalogs Schema (Schéma des catalogues de produits vendus au détail) 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 des produits.
      
      Vous devez sélectionner les niveaux de produits si vous importez votre catalogue pour la première fois ou si vous réimportez le catalogue après l'avoir supprimé définitivement. En savoir plus sur les niveaux de produits La modification des niveaux de produit après l'importation des données demande un effort important.
      
      Important:Vous ne pouvez pas activer la recherche de 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'erreurs 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 les informations de votre catalogue en envoyant une requête POST à la méthode REST Products:import, en fournissant le nom du fichier de données (ici, 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 Consulter 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

curl

Pour importer les informations de votre catalogue de façon intégrée, envoyez une requête POST à la méthode REST Products:import à l'aide de l'objet productInlineSource pour spécifier les données de votre catalogue.

Fournissez un produit complet sur une seule ligne. Chaque produit doit figurer sur sa propre ligne.

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.

1. Créez le fichier JSON de votre produit et appelez-le ./data.json :

   {
   "inputConfig": {
   "productInlineSource": {
     "products": [
       { PRODUCT_1 }
       { PRODUCT_2 }
     ]
   }
   }
   }
   

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_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
   

Java

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 un produit complet sur une seule ligne. Chaque produit doit figurer sur sa propre ligne.

Important :Dans cet exemple, les sauts de ligne ont un objectif de lisibilité. À l'exception des sauts de ligne entre les produits, n'incluez pas de saut de ligne dans vos données JSON.

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 des données historiques 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 anciennes informations produit 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 la disponibilité du produit sur OUT_OF_STOCK pour éviter d'affecter les recommandations.

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

• En appelant la méthode Product.Create
• Importation intégrée des produits arrivés à expiration
• Importer des produits arrivés à expiration depuis BigQuery

Appelez 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

La procédure est identique à celle de l'importation intégrée, si ce n'est que les champs expireTime des produits doivent être définis sur un horodatage passé.

Fournissez un produit complet sur une seule ligne. Chaque produit doit figurer sur sa propre ligne.

Important :Dans cet exemple, les sauts de ligne ont un objectif de lisibilité. À l'exception des sauts de ligne entre les produits, n'incluez pas de saut de ligne dans vos données JSON.

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 procédures décrites pour importer des données de catalogue à partir de BigQuery ou importer des données de catalogue depuis Cloud Storage. Veillez toutefois à définir le champ expireTime sur un code temporel passé.

Maintenir votre catalogue à jour

Pour 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 planifier des importations à l'aide de Google Cloud Scheduler. Vous pouvez également 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.

Remarque : Si un élément n'est plus à jour, définissez son état sur OUT_OF_STOCK plutôt que de le supprimer, afin que les événements utilisateur précédents qui y font référence ne soient pas invalidés.

Pour modifier un seul article, consultez Mettre à jour les informations sur un produit.

Mise à jour groupée

Vous pouvez utiliser la méthode d'importation pour mettre à jour votre catalogue de manière groupée. Pour procéder de la même manière que pour l'importation initiale, suivez les étapes de 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 Données pour le commerce.

   Accéder à la page "Données"

2. Déterminez 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éverrouiller les niveaux de performances de recherche. Pour obtenir un résumé des métriques du catalogue disponibles sur cette page, consultez Métriques de qualité du catalogue.

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

3. Pour créer des alertes en cas de problème lors de l'importation de vos données, suivez les procédures décrites dans la section 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 si nécessaire.

Étapes suivantes

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