Bonnes pratiques concernant l'API CSS

Ce document décrit certaines des bonnes pratiques à suivre pour utiliser l'API CSS. Les conseils fournis sur cette page ne sont pas obligatoires pour utiliser l'API, mais peuvent vous aider à mieux comprendre certaines utilisations prévues.

Configurer votre environnement

Pour configurer votre environnement de développement, suivez les étapes décrites dans la documentation du guide de démarrage rapide.

• Générer un fichier JSON d'utilisateur et d'autorisations dans la console Google Cloud
• Activer l'API CSS dans la console Google Cloud
• Ajoutez cet utilisateur avec des droits d'administrateur à votre compte CSS (groupe CSS ou domaine CSS).
• Vérifiez que vous utilisez le bon champ d'application OAuth : https://www.googleapis.com/auth/content

Les bibliothèques clientes sont désormais disponibles dans les dépôts standards pour la plupart des langages de programmation. Vous trouverez la liste de ces bibliothèques sur notre page Bibliothèques clientes.

Utiliser les bons ID

Utilisez les bons ID avec les bons points de terminaison d'API :

• API CSS (css.googleapis.com) : utilisez l'ID de domaine CSS lorsque vous interagissez avec les produits CSS (par exemple, accounts/{cssDomainId}/cssProductInputs:insert).
• API Merchant (merchantapi.googleapis.com) : utilisez l'API Merchant pour les produits standards des marchands.

Si vous les confondez, des erreurs se produiront. Pour en savoir plus, consultez la présentation de l'API CSS.

Bonnes méthodes pour commencer

Nous vous recommandons d'effectuer des tests à l'aide des méthodes suivantes :

ListChildAccounts

ListChildAccounts est un appel en lecture seule qui liste tous vos domaines CSS (s'il est appelé pour un groupe CSS) ou vos marchands (s'il est appelé pour un domaine CSS). Il s'agit donc d'une bonne méthode pour vérifier que tout est correctement configuré.

Insérer/Lister/Mettre à jour/Supprimer un produit

Une fois que vous savez que l'API fonctionne, essayez d'ajouter un produit. Assurez-vous d'utiliser un raw_provided_id dont vous vous souviendrez.

• Insérez un produit de test à l'aide de InsertCssProductInput. Nous avons des exemples de code pour vous aider à identifier les attributs à envoyer.
• Répertoriez tous vos produits à l'aide de ListCssProducts. Un petit délai de traitement est nécessaire avant qu'un produit ne s'affiche après son insertion. Si vous ne le voyez pas, réessayez après quelques secondes.
• Mettez à jour un seul produit à l'aide de UpdateCssProductInput en utilisant votre cssproductinput.name. Vous ne devez envoyer que les attributs à mettre à jour. Consultez l'exemple de code.
• Supprimez le produit de test à l'aide de DeleteCssProductInput. Vous devrez utiliser raw_provided_id.

Utiliser Async pour améliorer les performances

L'API CSS est conçue pour les appels parallèles. Vous constaterez que les performances des opérations individuelles peuvent être lentes, mais qu'elles sont beaucoup plus rapides lorsque la même opération est appelée plusieurs fois en parallèle. La meilleure façon d'utiliser cette fonctionnalité est d'utiliser la fonctionnalité asynchrone de votre langage de programmation.

Voici quelques exemples dans différents langages de programmation :

• Pour Java, utilisez insertCssProductInputCallable().futureCall().
• Pour Python, utilisez CssProductInputsServiceAsyncClient.
• Pour C#, utilisez InsertCssProductInputAsync.

Recherchez et utilisez la fonctionnalité Async de votre langage de programmation pour insérer plusieurs produits en même temps. Vous n'avez pas à vous soucier de la surcharge de nos systèmes, car c'est à cela que servent les limites de quota.

Pour en savoir plus, consultez notre page sur les performances.

Valider vos charges utiles

Pour éviter les erreurs courantes, vérifiez que vos charges utiles JSON sont correctement mises en forme :

• Consultez la documentation officielle : reportez-vous toujours à la dernière documentation de référence de l'API CSS pour connaître les définitions des champs, les énumérations, les types de données et la structure de la charge utile.
• Examiner les exemples de charges utiles : comparez vos charges utiles avec les exemples de code fournis pour identifier les différences.
• Types de données : assurez-vous d'utiliser les types de données appropriés (par exemple, chaînes, objets, tableaux) comme indiqué dans la documentation.
• Testez de manière incrémentielle : commencez par des charges utiles valides minimales pour confirmer la connectivité de base, puis ajoutez progressivement d'autres attributs.

Mettre à jour un produit

Une fois un produit importé, il reste dans notre système jusqu'à ce qu'il soit mis à jour, supprimé ou expiré.

• Vous pouvez mettre à jour le produit complet en renvoyant la requête InsertCssProductInput, en utilisant le même raw_provided_id que celui utilisé initialement. Pour le moment, vous devrez envoyer l'intégralité des données produit, même si seuls certains attributs (peut-être uniquement le prix ou la disponibilité) ont changé.
• Vous pouvez mettre à jour des parties d'un produit à l'aide de la méthode PATCH UpdateCssProductInput, en spécifiant le nom du produit et un corps JSON contenant les données que vous souhaitez mettre à jour pour le produit. Contrairement à InsertCssProductInput, où vous devez indiquer tous les champs obligatoires, vous ne devez spécifier que les champs à modifier pour UpdateCssProductInput.
• Vous pouvez supprimer un produit en appelant DeleteCssProductInput avec le même raw_provided_id.
• Les produits expirent automatiquement environ un mois après la dernière mise à jour.

Mode de fonctionnement continu

Un mode de fonctionnement continu peut ressembler à ce qui suit :

• Utilisez vos propres ID internes comme raw_provided_id.
• Réimportez tous les produits régulièrement, par exemple toutes les semaines. Vous vous assurez ainsi que les produits actifs n'expirent pas.
• Mettez à jour les produits individuels dès que vous recevez les données modifiées de vos marchands.
  • Si vous ne pouvez pas réagir immédiatement aux modifications, recherchez fréquemment (peut-être toutes les heures) tous les produits modifiés et réimportez uniquement ceux-ci.
  • Pour les produits qui ne sont plus disponibles, vous pouvez utiliser l'appel de suppression ou définir le nombre d'offres disponibles sur 0.
  • N'envoyez pas fréquemment des produits inchangés. Ces appels seraient comptabilisés dans votre quota d'API. Une actualisation hebdomadaire est suffisante.

Sélection de l'offre principale

L'offre principale ne doit pas nécessairement être l'offre la plus intéressante ou la moins chère sur votre site, mais elle doit être mise en avant. Vous pouvez l'utiliser dans les cas où votre offre principale change rapidement. Vous pouvez alors sélectionner une autre offre plus stable.

Vérifier à nouveau ce document de temps en temps

Nous avons reçu des commentaires sur la façon d'améliorer cette API et nous nous efforçons de rendre certaines de ces améliorations disponibles. Nous mettrons à jour cette page lorsque de nouvelles fonctionnalités seront disponibles pour simplifier l'utilisation de l'API CSS.