Importer les informations du catalogue

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Cette page explique comment importer les informations de votre catalogue dans l'API Retail et les maintenir à jour.

Les procédures d'importation présentées sur cette page s'appliquent à Recommendations AI et à Retail Search. Une fois que vous avez importé des données dans l'API Retail, les deux services peuvent utiliser ces données. 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 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 les données de catalogue de façon 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

L'API Retail nécessite des données de haute qualité pour générer des résultats de haute qualité. Si vos données ne contiennent pas de champs ou comportent 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 des versions principales et des variantes. Avant d'importer des données, consultez Niveaux de produits.

    Modifiez la configuration au niveau du produit après avoir importé des données.

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

    Par exemple, si le groupe de codes SKU principal est "V-shirt chemise", le modèle de recommandation renvoie une chemise à col en V et, peut-être, une chemise à col rond et une chemise à col rasé. Toutefois, si les variantes ne sont pas utilisées et que chaque code SKU est une valeur principale, chaque combinaison 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 rond marron, taille L" jusqu'à "chemise blanche à col en V", taille M".

  • 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'espaces réservés.

  • 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 Google Cloud Console pour obtenir des métriques sur les revenus. L'API Retail n'accepte pas 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 automatiques récurrentes lorsque vous importez votre catalogue à l'aide de la console Google Cloud. 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 à l'API Retail. Planifiez des importations régulières de catalogue (idéalement, tous les jours) pour vous assurer que votre catalogue reste bien à jour. Consultez la section Maintenir votre catalogue à jour.

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 de catalogue via Merchant Center en associant le compte à l'API Retail. Une fois l'association effectuée, les mises à jour des données de catalogue dans Merchant Center sont synchronisées avec l'API Retail en temps réel.
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 les données d'une table BigQuery précédemment chargée qui utilise le schéma Retail ou le schéma Merchant Center. Cette opération 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 Retail, qui contient plus d'attributs produit que d'autres options d'importation (cela inclut 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 l'étape supplémentaire de la création d'une table BigQuery mappée sur le schéma Retail.
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 présente moins d'attributs de catalogue de produits que le schéma Retail, mais 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 les associer à un compte marchand.

Si vous diffusez des prédictions en direct ou du trafic de recherche et que vous prévoyez de supprimer définitivement votre branche par défaut, pensez à spécifier une autre branche par défaut avant de supprimer définitivement la branche. Étant donné que la branche par défaut diffusera des résultats vides après la suppression définitive, la suppression définitive d'une branche par défaut active peut entraîner une panne.

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

  1. Accédez à la page "Données de vente" de la console Google Cloud.

    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 situé à côté du champ Nom de la branche, sélectionnez Purger la branche.

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

  4. Saisissez la branche et cliquez sur Confirm (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 catalogue. Une fois l'opération de suppression définitive terminée, l'état de la suppression définitive est affiché dans la liste Catalogue des produits de la fenêtre État de l'activité.

Synchroniser Merchant Center avec l'API Retail

Pour assurer la synchronisation continue entre Merchant Center et l'API Retail, vous pouvez associer votre compte Merchant Center à l'API Retail. Une fois l'association effectuée, les informations de catalogue de votre compte Merchant Center sont immédiatement importées dans l'API Retail.

Lorsque l'API Retail est associée au compte Merchant Center, les modifications apportées à vos données produit dans le compte Merchant Center sont automatiquement propagées en quelques minutes. Si vous souhaitez empêcher la synchronisation des modifications Merchant Center avec l'API Retail, vous pouvez dissocier votre compte Merchant Center.

La dissociation de votre compte Merchant Center ne supprime pas de produits dans l'API Retail. Pour supprimer des produits importés, consultez Supprimer des informations sur des produits.

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

Console

  1. Accédez à la page "Données de vente" de la console Google Cloud.

    Accéder à la page "Données"
  2. Cliquez sur Importer pour ouvrir le panneau 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 vous ne voyez pas votre compte, vérifiez les droits d'accès des utilisateurs.
  6. (Facultatif) Sélectionnez Filtre de flux Merchant Center pour n'importer que les offres des flux sélectionnés.

    S'il n'est pas spécifié, les offres de tous les flux sont importées (y compris les flux futurs).
  7. Facultatif: Pour importer uniquement des offres ciblant certains pays ou certaines langues, développez Afficher les options avancées, puis sélectionnez les pays de vente et les langues à filtrer dans Merchant Center.
  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 au compte Merchant Center et à l'API Retail. 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 Catalog.patch pour établir l'association.

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
        "merchantCenterLinkingConfig": {
          "links": [{
             merchantCenterAccountId: MERCHANT_CENTER_ID,
             destinations: ["DESTINATION_1", "DESTINATION_2"],
             branchId: "BRANCH_ID",
             languageCode: "LANGUAGE_CODE",
             regionCode: "REGION_CODE",
             feeds: [
              {primaryFeedId: PRIMARY_FEED_ID_1},
              {primaryFeedId: PRIMARY_FEED_ID_2}
            ]
          }]
        }
     }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog?updateMask=merchantCenterLinkingConfig"
    
    • MERCHANT_CENTER_ID: ID du compte Merchant Center.
    • BRANCH_ID: ID de la branche avec laquelle établir le lien. Accepte les valeurs "0", "1" ou "2".
    • DESTINATION : (FACULTATIF) (OBSOLÈTE en faveur des flux) Destination Merchant Center. Vous pouvez utiliser n'importe quelle combinaison de valeurs acceptées répertoriées dans la documentation sur les destinations de Merchant Center.
    • 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.
    • REGION_CODE (FACULTATIF) : code régional à deux lettres des produits que vous souhaitez importer. Comme indiqué dans Merchant Center sous la colonne Country Of Sale du produit. Si cette règle n'est pas configurée, toutes les régions sont importées.
    • FEEDS (FACULTATIF) : liste des flux principaux à partir desquels les produits seront importés. Si vous ne sélectionnez pas de flux, tous les flux de votre compte Merchant Center seront partagés. Vous pouvez les trouver dans la ressource de flux de données de Content API ou en accédant à Merchant Center, en sélectionnant un flux et en obtenant l'ID de flux à partir du paramètre dataSourceId de 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 Google Cloud et cliquez sur le bouton Merchant Center en haut à droite. Le panneau Comptes Merchant Center associés s'affiche. Vous pouvez également ajouter des comptes Merchant Center supplémentaires à partir de ce panneau.

Consultez Afficher des informations agrégées sur votre catalogue pour savoir comment afficher les produits importés dans l'API Retail.

La dissociation de votre compte Merchant Center empêche la synchronisation des données de catalogue de ce compte par l'API Retail. Cette procédure ne supprime pas les produits qui ont déjà été importés par l'API Retail.

Console

  1. Accédez à la page "Données de vente" de la console Google Cloud.

    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 Catalog.patch pour supprimer la configuration d'association de la ressource Catalog.

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

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) ou un sous-compte d'un MC existant.

  • 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 de l'API Retail 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 l'API Retail.

  • 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 des données de 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 des données de catalogue de Merchant Center de manière groupée à partir de BigQuery à l'aide du schéma Merchant Center (Recommendations AI uniquement).

Importation groupée depuis Merchant Center

Vous pouvez importer des données de catalogue depuis Merchant Center à l'aide de la console Retail Google Cloud ou de la méthode products.import. L'importation groupée est une procédure ponctuelle, qui n'est compatible qu'avec Recommendations AI.

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 l'API Retail puisse y accéder. En savoir plus

  3. Importez vos données de catalogue depuis BigQuery dans l'API Retail.

    Console

    1. Accédez à la page "Données de vente" de la console Google Cloud.

      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 le schéma de données Merchant Center.

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

    8. Facultatif: Saisissez l'emplacement d'un bucket Cloud Storage dans votre projet en tant qu'emplacement temporaire de 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.

      Modifiez la configuration au niveau du produit après avoir importé des données.

    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 permettre à l'API Retail de 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 permettre à l'API Retail de 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 les répertoires de préproduction ou d'erreur afin que l'API Retail puisse créer automatiquement un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur. Ils seront créés dans la même région que l'ensemble de données BigQuery et seront 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 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 l'API Retail.

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


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 l'API Retail puisse y accéder. En savoir plus

  2. Importez vos données de catalogue dans l'API Retail.

    Console

    1. Accédez à la page "Données de vente" de la console Google Cloud.

      Accéder à la page "Données"
    2. Cliquez sur Importer pour ouvrir le panneau 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. Choisissez Retail Product Catalogs Schema. Il s'agit du schéma de l'API Retail.
    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 comme emplacement temporaire pour vos données.

      Si aucune valeur n'est spécifiée, une adresse par défaut est utilisée. Si spécifié, le bucket BigQuery et Cloud Storage doivent se trouver dans la même région.
    9. Si vous n'avez pas activé Retail Search 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 que vous le réimportez après sa suppression. En savoir plus sur les niveaux de produit La modification des niveaux de produit après l'importation de données demande un effort important.

      Important:Vous ne pouvez pas activer Retail Search 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 permettre à l'API Retail de 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 permettre à l'API Retail de 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 Retail.

      Nous vous recommandons de ne pas spécifier les répertoires de préproduction ou d'erreur afin que l'API Retail puisse créer automatiquement un bucket Cloud Storage avec de nouveaux répertoires de préproduction et d'erreur. Ils seront créés dans la même région que l'ensemble de données BigQuery et seront 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 dans l'API Retail 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 Retail, procédez comme suit.

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

    Ouvrir la page IAM

  2. Sélectionnez votre projet Retail.

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

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

  4. Copiez l'identifiant du compte de service qui ressemble à une adresse e-mail (par exemple, service-525@gcp-sa-retail.iam.gserviceaccount.com).

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

  6. Dans le champ Nouveaux comptes principaux, saisissez l'identifiant du compte de service 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 l'API Retail.

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 sur l'importation de fichiers dans Cloud Storage, consultez la page Importer des objets.

  1. Assurez-vous que le compte de service Retail est autorisé à lire et écrire dans le bucket.

    Le compte de service 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 vos données de catalogue dans l'API Retail.

    Console

    1. Accédez à la page "Données de vente" de la console Google Cloud.

      Accéder à la page "Données"
    2. Cliquez sur Importer pour ouvrir le panneau 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. Choisissez le schéma Retail Product Catalogs.
    6. Saisissez l'emplacement Cloud Storage de vos données.
    7. Si vous n'avez pas activé Retail Search, 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 demande un effort important.

      Important : Vous ne pouvez pas activer Retail Search 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, l'API Retail le crée. Le bucket doit déjà exister.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }
      
    3. Importez vos informations de catalogue dans l'API Retail 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 Google Cloud Console. Pour en savoir plus, consultez 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 les données de catalogue de façon intégrée

curl

Pour importer des informations de votre catalogue dans l'API Retail de manière 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.

Indiquez un produit entier sur une seule ligne. Chaque produit doit figurer sur une ligne distincte.

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.

Indiquez un produit entier sur une seule ligne. Chaque produit doit figurer 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

L'API Retail 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. L'API Retail peut utiliser les informations sur les anciens produits 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 Recommendations AI.

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

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, à la différence près que les champs expireTime des produits doivent être définis sur un horodatage passé.

Indiquez un produit entier sur une seule ligne. Chaque produit doit figurer 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

Utilisez les mêmes procédures que celles documentées pour importer des données de catalogue à partir de BigQuery ou importer des données de catalogue à partir de Cloud Storage. Toutefois, veillez à définir le champ expireTime sur un horodatage antérieur.

Maintenez votre catalogue à jour

L'API Retail repose sur la disponibilité des informations produit actuelles pour vous fournir les meilleurs résultats. Nous vous recommandons d'importer votre catalogue quotidiennement pour vous assurer qu'il reste bien à jour. Vous pouvez utiliser Google Cloud Scheduler pour planifier des 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 article, consultez Mettre à jour les informations sur les produits.

Mise à jour groupée

Vous pouvez utiliser la méthode d'importation pour mettre à jour votre catalogue de manière groupée. Pour ce faire, suivez la même procédure que pour l'importation initiale : suivez les étapes de la section Importer des données de catalogue.

Surveiller l'état d'importation

Pour vous assurer qu'il n'y a pas d'erreur pour vos données importées, vous pouvez vérifier les métriques de chargement des données de votre catalogue sur la page Données Retail. La page "Données Retail" affiche également des métriques de qualité concernant les données produit de votre catalogue.

Pour obtenir des résultats de haute qualité, il est important de maintenir votre catalogue à jour. Vous devez surveiller les taux d'erreur d'importation et prendre des mesures, le cas échéant. Pour en savoir plus, consultez Configurer des alertes.

Étapes suivantes