Vous pouvez importer des données produit dans Merchant Center à l'aide de flux basés sur des fichiers, de Merchant API ou d'une combinaison des deux :
- Flux de produits basés sur des fichiers : importez des fichiers CSV, TSV ou XML à l'aide du SFTP, de Google Cloud Storage, de Google Sheets ou de récupérations planifiées.
- Merchant API : envoyez des requêtes programmatiques directement depuis votre backend pour effectuer des mises à jour incrémentielles lorsque les données produit changent, ainsi que des synchronisations complètes et périodiques du catalogue.
Ce guide compare les deux approches, explique quand utiliser l'une plutôt que l'autre (ou les deux ensemble) et fournit un guide de migration par étapes si vous décidez de migrer une partie ou la totalité de vos produits des flux de fichiers vers l'API.
Choisir votre approche de source de données
Évaluez la volatilité de votre catalogue, l'architecture de votre backend et vos workflows opérationnels pour décider si vous devez utiliser l'API Merchant, des flux de fichiers ou une configuration hybride.
Quand utiliser Merchant API ?
Utilisez une source de données principale d'API si :
- Intégration programmatique directe : vous préférez appeler une API directement depuis votre backend plutôt que de générer des fichiers et de gérer des pipelines de transfert de fichiers (comme SFTP ou Google Cloud Storage).
- Forte volatilité des prix et des stocks : les prix ou les niveaux de stock de vos produits changent fréquemment au cours de la journée.
- Mises à jour immédiates en cas de modification des données : vous souhaitez envoyer les modifications de produits à Google dès qu'elles se produisent dans votre backend, plutôt que d'attendre la prochaine génération et importation de fichiers planifiées.
- Mises à jour incrémentielles du catalogue : vous souhaitez insérer, mettre à jour ou supprimer des produits individuels à mesure qu'ils changent, sans avoir à réimporter l'intégralité de votre catalogue à chaque fois.
- Mises à jour partielles d'attributs : vous souhaitez mettre à jour des champs spécifiques d'un produit (par exemple,
priceouavailabilityà l'aide deproductInputs.patch) sans renvoyer l'intégralité de la charge utile du produit.
Quand utiliser des flux de fichiers ?
Utilisez une source de données principale basée sur un fichier si :
- Catalogue statique : vos données produit changent rarement (par exemple, une fois par jour ou moins).
- Backend d'instantané uniquement sans suivi des deltas : votre backend n'exporte que des instantanés complets du catalogue et ne peut pas suivre les modifications au niveau des articles ni les suppressions explicites de produits.
- Workflows basés sur des feuilles de calcul : les équipes non techniques sélectionnent ou remplacent les données produit directement dans Google Sheets ou des fichiers CSV.
- Opérations nécessitant peu de maintenance : vous préférez une exportation de fichiers planifiée, où Merchant Center gère la récupération et le traitement des instantanés, plutôt que d'utiliser une intégration d'API avec un rythme de requêtes, une gestion des nouvelles tentatives et des synchronisations périodiques du catalogue complet.
Quand utiliser les deux ?
Vous pouvez combiner des flux de fichiers et l'API Merchant dans le même compte Merchant Center dans les cas suivants :
- Catalogues de produits partitionnés : vous utilisez la Merchant API pour les produits qui changent rapidement (comme les ventes flash ou les stocks à rotation rapide) et les flux de fichiers pour les segments de catalogue statiques ou les gammes de produits distinctes. Assurez-vous que chaque produit n'est importé que par une seule source de données principale (voir Utilisation parallèle et propriété de la source de données principale).
- Source de données principale de l'API avec des flux supplémentaires basés sur des fichiers : vous gérez les données produit principales via une source de données principale de l'API, tandis que les équipes non techniques ou les partenaires tiers fournissent des attributs supplémentaires via des flux supplémentaires basés sur des fichiers (comme des fichiers Google Sheets ou CSV) associés à des règles d'attributs, ou l'inverse.
- Migration partielle ou progressive : vous migrez des marchés, des catégories ou des sous-comptes spécifiques vers l'API, tout en conservant le reste de votre catalogue dans des flux de fichiers.
Si vous décidez de transférer tout ou partie de vos produits des flux de fichiers vers l'API Merchant, suivez le guide de migration par étapes.
Principales différences architecturales
Les flux de fichiers et l'API Merchant basée sur le push diffèrent dans la manière dont Google traite et gère les données produit :
| Concept | Flux de fichiers | API Merchant |
|---|---|---|
| Modèle d'intégration | Fichier d'exportation hors connexion : vous exportez votre catalogue dans un fichier et le transférez à l'aide de SFTP, de Google Cloud Storage, de Google Sheets ou de récupérations planifiées. | Intégration programmatique directe : votre backend envoie des requêtes directement au point de terminaison de l'API. |
| Précision de la mutation | Traitement groupé : la modification d'un élément nécessite généralement de retraiter l'intégralité du fichier. | Transactions précises : vous pouvez insérer, corriger ou supprimer uniquement les produits qui ont été modifiés. |
| Délai de synchronisation | Synchronisation par lot : les modifications sont mises en attente dans votre backend jusqu'au prochain cycle d'exportation et de transfert de fichiers planifié. | Appels immédiats ou programmés : vous pouvez envoyer les modifications incrémentielles immédiatement lorsqu'elles se produisent, en plus des synchronisations complètes périodiques. |
| Comportement de suppression | Implicite (instantané) : chaque fichier est un instantané complet. Supprimer une ligne de votre fichier principal supprime le produit. | Explicite : il n'existe pas de concept d'instantané. Appelez productInputs.delete pour supprimer un produit arrêté. |
| Représentation des ressources | État unique : les lignes de votre fichier représentent l'entrée brute. | Séparation des données brutes et traitées : l'API divise les données en ProductInput (votre entrée brute) et Product (l'état traité final). |
| Règles d'attribut (flux) | Appliqué aux colonnes du fichier brut dans l'interface utilisateur de Merchant Center. | Compatible avec l'interface utilisateur de Merchant Center. Obligatoire lors de la fusion de données d'API avec des fichiers supplémentaires tiers. Facultatif pour les transformations à source unique si elles sont gérées dans votre backend. |
Utilisation parallèle et propriété de la source de données principale ("la dernière mise à jour l'emporte")
Bien que vous puissiez utiliser à la fois des flux de fichiers et l'API dans le même compte Merchant Center, nous vous recommandons vivement de n'utiliser qu'une seule méthode pour insérer un produit donné.
Merchant Center fonctionne selon le modèle "la dernière mise à jour l'emporte". La source de données principale (API ou flux de fichiers) qui a envoyé l'insertion de produit la plus récente devient le propriétaire principal des données de ce produit :
- Lorsque la source de données du fichier est propriétaire du produit : si vous omettez le produit lors d'une importation ultérieure du fichier, cela déclenche une suppression implicite, ce qui supprime le produit de Merchant Center.
- Lorsque la source de données de l'API est propriétaire du produit : omettre le produit d'une importation de fichier n'a aucun effet, car le flux de fichiers n'est plus propriétaire du produit.
Vous devez appeler
accounts.productInputs.deletepour le supprimer. - Risque de réappropriation accidentelle : si un flux de fichiers mis à jour s'exécute après un push d'API et contient le produit, la source de données du fichier redevient propriétaire. Les omissions ultérieures dans le fichier entraîneront la suppression inattendue du produit.
Pour éviter les suppressions inattendues ou la perte des mises à jour de l'API, n'effectuez pas de mises à jour simultanées sur les mêmes produits à l'aide de l'API et des sources de données principales de fichiers.
Points clés concernant l'API
Avant de commencer l'implémentation, vous devez comprendre les comportements critiques suivants de l'API Merchant :
Sources de données flexibles (sans langue ni libellé)
Contrairement aux flux de fichiers, qui nécessitent de définir à l'avance un libellé de flux cible et une langue spécifiques, Merchant API vous permet de créer des sources de données principales sans spécifier de feedLabel ni de contentLanguage.
- Importations flexibles : vous pouvez importer des produits avec n'importe quelle combinaison de langue ou de libellé de flux dans une seule source de données.
- Gestion simplifiée : vous n'avez pas besoin de créer ni de gérer des sources de données distinctes pour chaque marché cible. Remarque : Pour en savoir plus sur le choix d'une stratégie de source de données, consultez Choisir une stratégie de source de données.
Stratégie de synchronisation et quotas
Contrairement à un flux de fichiers dans lequel vous importez l'intégralité de votre catalogue en une seule fois, concevez votre intégration de l'API Merchant autour des actualisations incrémentielles et des synchronisations complètes régulières :
- Combinez les mises à jour incrémentielles avec des synchronisations complètes périodiques : envoyez des requêtes
productInputs.insertouproductInputs.patchà mesure que les attributs de produit changent dans votre backend. Étant donné que le fait de s'appuyer uniquement sur des mises à jour incrémentielles peut entraîner une désynchronisation de vos données au fil du temps, exécutez également des synchronisations complètes périodiques pour rapprocher votre catalogue de votre source de vérité (ce qui actualise également l'expiration des produits au bout de 30 jours). La fréquence d'exécution d'une synchronisation complète dépend de la taille de votre catalogue et du quota d'API disponible. - Échelonnez les requêtes pour respecter les quotas d'API : n'appelez pas l'API pour tous vos produits en même temps. Bien que les modifications incrémentielles puissent être envoyées au fur et à mesure qu'elles se produisent, répartissez les requêtes de synchronisation complète de manière uniforme tout au long de la journée pour respecter vos quotas d'appels de méthode par minute et par jour. Pour en savoir plus, consultez Quotas et limites et Mettre à jour fréquemment vos produits.
Tester votre intégration
Validez votre logique d'intégration dans un environnement sécurisé avant de passer en production.
Utilisez des comptes de test
Avant d'apporter des modifications en production, nous vous recommandons d'exécuter les étapes initiales de la migration dans un compte de test sandbox :
- Créez un compte de test : configurez un compte de test isolé pour faire des essais en toute sécurité sans affecter les annonces ou les fiches gratuites actives.
- Créer une source de données d'API : entraînez-vous à créer votre source de données d'API principale.
- Tester les règles d'attribut : vérifiez les transformations de données et les jointures de flux supplémentaires.
- Valider les charges utiles et les clés de produit : transmettez des exemples de produits pour vérifier la casse, l'encodage et la gestion des erreurs des SKU.
Pour en savoir plus, consultez Étape 1 : Créez des comptes de test et le guide Comptes de test.
Valider l'alignement des clés de produit
Assurez-vous que la clé de produit de votre charge utile programmatique correspond exactement aux SKU de votre flux de fichiers. Google identifie les produits en combinant les éléments suivants :
offerId(appeléiddans les flux de fichiers, sensible à la casse)contentLanguage(par exemple,en)feedLabel(par exemple,US)
Caractères spéciaux et encodage
Si vos identifiants de produit contiennent des caractères tels que /, % ou ~, utilisez le format encodé (encodage base64url sans marge intérieure) dans vos appels d'API. Pour en savoir plus, consultez ProductInput.name.
Contrôle de simultanéité
Dans une intégration en temps réel, les mises à jour peuvent arriver dans le désordre en raison de la latence du réseau. Pour éviter que les anciennes mises à jour n'écrasent les données plus récentes, utilisez le champ versionNumber dans la ressource ProductInput.
Playbook de migration étape par étape
Si vous décidez de transférer certains de vos produits (ou tous) de flux de fichiers vers l'API Merchant, suivez ce playbook pour effectuer la transition sans perdre d'impressions ni d'historique de diffusion.
1. Répéter la migration dans un compte de test
Avant d'apporter des modifications en production, créez un compte de test en bac à sable à l'aide de la méthode accounts.createTestAccount (consultez le guide Comptes de test). Les comptes de test fournissent un environnement isolé dans lequel les offres sont approuvées par défaut, la validation du domaine n'est pas requise et les données ne sont jamais diffusées publiquement.
Utilisez votre compte de test pour reproduire votre configuration de production et répéter la migration de bout en bout :
- Reproduisez la configuration de votre flux de fichiers : créez une source de données principale de fichier (et toutes les sources de données supplémentaires) dans le compte de test, puis importez un échantillon de votre fichier de flux de production.
- Créer une source de données API de test et des règles : créez une source de données API principale et configurez les règles d'attributs ou les jointures de flux supplémentaires requises.
- Testez la prise de propriété et l'alignement des clés : envoyez des requêtes
productInputs.insertpour les exemples de produits et vérifiez que la source de données de l'API prend la propriété des articles existants sans créer de produits en double. - Vérifier les mises à jour et les suppressions : testez les mises à jour partielles avec
productInputs.patchet les suppressions avecproductInputs.delete, puis inspectez les ressources obtenues avecproducts.get.
2. Créer des sources de données d'API de production
Avant de transférer des données, créez une source de données principale de type API dans votre compte.
Créer votre source de données principale d'API
Pour créer une source de données qui accepte les requêtes push d'API, envoyez une requête POST au point de terminaison dataSources. Pour en savoir plus, consultez Créer une source de données produit principale.
3. Règles de transition des attributs personnalisés
Les règles d'attributs personnalisées sont liées à des sources de données spécifiques et ne sont pas automatiquement transférées de votre source de données de fichier vers votre nouvelle source de données de l'API.
La transition de vos règles d'attribut dépend de leur objectif :
- Fusion de plusieurs sources et flux supplémentaires tiers : si vous combinez des données d'API principales avec des sources de données supplémentaires externes (comme des fichiers de fournisseurs tiers, des feuilles de calcul d'inventaire ou des flux de promotions), vous devez recréer les règles d'attributs dans l'interface utilisateur de Merchant Center et les associer à la nouvelle source de données de l'API. Le prétraitement côté client ne peut pas remplacer les règles qui joignent des données provenant de plusieurs sources indépendantes.
- Transformations de données à source unique : pour le nettoyage, les valeurs par défaut ou la mise en forme de chaînes à source unique sur les données de votre catalogue principal, choisissez entre :
- Transformations de backend (recommandé) : appliquez des transformations dans votre propre système avant d'appeler l'API. Cela vous offre un meilleur contrôle programmatique, des tests plus faciles et un débogage simplifié.
- Règles d'attribut Merchant Center : recréez les règles de transformation pour votre nouvelle source de données API dans l'interface utilisateur de Merchant Center si vous souhaitez que Merchant Center continue de les gérer automatiquement.
4. Activer l'intégration de l'API
Activez l'intégration de votre API de production pour commencer à insérer, mettre à jour et supprimer des produits dans votre nouvelle source de données principale de l'API :
Insérer et mettre à jour des produits (reprise de propriété) : envoyez des requêtes
productInputs.insertetproductInputs.patchdepuis votre intégration. Lorsque vous insérez un produit à l'aide de l'API avec la même clé (offerId,contentLanguage,feedLabel) qu'un produit existant dans un flux de fichiers, la source de données de l'API devient propriétaire de ce produit et conserve son historique de diffusion. Pour en savoir plus, consultez Insérer un produit et Ajouter et gérer des produits.Supprimer les produits qui ne sont plus disponibles : configurez votre intégration pour appeler explicitement
productInputs.deletechaque fois qu'un produit est supprimé de votre catalogue.Déployez progressivement : pour les catalogues volumineux, activez votre intégration un sous-compte Merchant Center ou une source de données à la fois.
Configurer la simultanéité : si vous envoyez de nombreuses requêtes, configurez votre client pour qu'il gère les requêtes simultanées et plusieurs connexions. Consultez le guide Refactoriser le code pour les requêtes simultanées.
5. Suspendre les mises à jour de la source de données du fichier
Une fois l'intégration de l'API active, arrêtez les mises à jour de fichiers avant la prochaine exécution planifiée afin que la source de données du fichier n'écrase pas les mises à jour de l'API :
- Arrêtez d'importer de nouveaux fichiers dans votre emplacement SFTP/FTP, Google Cloud Storage ou Google Sheets.
- Dans l'interface utilisateur de Merchant Center, accédez à votre source de données de fichier et mettez en veille sa récupération planifiée.
- Les produits existants appartenant à la source de données de fichier restent actifs pendant 30 jours maximum, jusqu'à ce que votre intégration d'API les insère.
6. Attendre la fin de la migration et vérifier
Attendez que tous les produits actifs soient migrés de la source de données de fichier vers la source de données d'API. Les mises à jour incrémentielles migrent les produits au fur et à mesure de leur modification. Toutefois, l'exécution d'une synchronisation complète du catalogue via votre intégration standard accélère la migration de l'intégralité de votre catalogue (voir Stratégie de synchronisation et quotas).
Pendant cette phase :
- Dans l'interface utilisateur de Merchant Center, surveillez le nombre d'articles. Attendez que le nombre de sources de données de fichiers diminue jusqu'à
0et que le nombre de sources de données d'API corresponde à votre catalogue actif. - Utilisez
products.getpour vérifier que les attributs et les règles d'attributs personnalisés fusionnent comme prévu. - Surveillez l'outil Diagnostic de l'API dans l'UI Merchant Center pour suivre les taux d'erreur et les performances de l'API.
7. Mettre hors service la source de données de fichier
Une fois la transition terminée et le nombre d'éléments du flux de fichiers égal à 0 :
- Vérifiez que les mises à jour sont reflétées en temps réel.
- Supprimez l'ancienne source de données de fichier dans l'interface utilisateur de Merchant Center pour éviter que des mises à jour accidentelles basées sur des fichiers n'écrasent vos données d'API.