Gestion de vos produits
L’API de contenu est une API RESTful qui utilise la ressource Products pour gérer les offres de produits dans votre magasin MMC (Microsoft Merchant Center).
Voici l’URI de base que vous utilisez pour appeler l’API de contenu.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/
Chaque requête HTTP doit inclure le jeton d’accès OAuth de l’utilisateur et votre jeton de développeur. Pour spécifier le jeton d’accès de l’utilisateur, définissez l’en-tête AuthenticationToken . Pour spécifier votre jeton de développeur, définissez l’en-tête DeveloperToken .
Si vous gérez des catalogues pour le compte d’autres clients, vous devez définir :
- En-tête CustomerId de l’ID client du client dont vous gérez le magasin.
- En-tête CustomerAccountId de l’ID de compte de l’un des comptes du client que vous gérez (peu importe le compte géré).
Par défaut, l’API de contenu utilise des objets JSON pour représenter l’offre de produit. Pour utiliser du code XML, définissez le paramètre de requête alt sur XML.
Pour plus d’informations sur l’utilisation de la ressource Products, consultez les sections suivantes.
- Obtention d’une offre de produit à partir du magasin
- Obtention d’une liste d’offres de produits à partir du magasin
- Suppression d’une offre du magasin
- Ajout et mise à jour d’une offre de produit
- Utilisation du traitement par lots
Obtention d’une offre de produit à partir du magasin
Pour obtenir une offre de produit spécifique à partir du magasin, ajoutez le modèle suivant à l’URI de base.
{mmcMerchantId}/products/{productUniqueId}
Définissez {mmcMerchantId} sur votre ID de magasin MMC et sur {productUniqueId}l’ID de produit complet (par exemple, Online :en :US :Sku123), et non sur offerId du produit. Étant donné que l’ID de produit respecte la casse, utilisez l’ID que l’API vous a retourné lorsque vous avez ajouté le produit.
Envoyez une requête HTTP GET à l’URL obtenue. Si le produit a été trouvé, la réponse contient un objet Product qui contient l’offre.
Si vous avez inséré un produit avec le même ID dans plusieurs catalogues, le service ne retourne qu’un seul d’entre eux : quel produit et à partir de quel catalogue est indéterminé. Pour cette raison, vous ne devez pas insérer un produit avec le même ID de produit dans plusieurs catalogues.
Pour obtenir un exemple de code qui montre comment obtenir une offre de produit, consultez Exemple de code de gestion des produits.
Obtention d’une liste d’offres de produits à partir du magasin
Pour obtenir la liste des offres de produits qui se trouvent dans le magasin, ajoutez le modèle suivant à l’URI de base.
{mmcMerchantId}/products
Définissez sur {mmcMerchantId} votre ID de magasin MMC.
Pour parcourir la liste des offres, utilisez les paramètres de requête max-results et start-token . Dans votre premier appel, définissez max-results sur le nombre maximal d’offres que vous souhaitez que le service retourne. Le nombre maximal d’offres que le service peut retourner est de 250. La valeur par défaut est 25. Envoyez une requête HTTP GET à l’URL obtenue. L’exemple suivant illustre la demande.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250
Si le magasin contient des offres, la réponse contient un objet Product qui contient jusqu’au nombre d’offres demandé.
Si d’autres offres sont disponibles, la réponse inclut le nextPageToken champ (voir Produits). Le nextPageToken champ contient la valeur de jeton que vous utilisez pour définir le start-token paramètre sur dans votre demande de liste suivante. L’exemple suivant montre comment utiliser le jeton .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...
Pour obtenir un exemple de code qui montre comment obtenir une liste d’offres de produits, consultez Exemple de code de gestion des produits.
Suppression d’une offre du magasin
Pour supprimer une offre de produit spécifique du magasin, ajoutez le modèle suivant à l’URI de base.
{mmcMerchantId}/products/{productUniqueId}
Définissez {mmcMerchantId} sur votre ID de magasin MMC et sur {productUniqueId}l’ID de produit complet (par exemple, Online :en :US :Sku123), et non sur offerId du produit. Étant donné que l’ID de produit respecte la casse, utilisez l’ID que l’API vous a retourné lorsque vous avez ajouté le produit.
Envoyez une requête HTTP DELETE à l’URL obtenue. Si le produit a été trouvé, il est supprimé.
Si vous avez inséré un produit avec le même ID de produit dans plusieurs catalogues, le service les supprime tous. Vous ne devez pas insérer un produit avec le même ID de produit dans plusieurs catalogues.
Pour obtenir un exemple de code qui montre comment supprimer une offre de produit, consultez Exemple de code de gestion des produits.
Ajout et mise à jour d’une offre de produit
L’ajout ou la mise à jour d’une offre est une opération d’insertion. Étant donné qu’une mise à jour est une opération d’insertion, vous devez inclure tous les champs de l’offre dans la demande . vous ne pouvez pas mettre à jour un seul champ.
Pour insérer une offre de produit, ajoutez le modèle suivant à l’URI de base.
{mmcMerchantId}/products
Définissez sur {mmcMerchantId} votre ID de magasin MMC.
L’envoi d’une requête HTTP POST à l’URL résultante écrit l’offre dans le catalogue du magasin par défaut. Pour écrire l’offre dans un catalogue spécifique, incluez le paramètre de requête bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456
Si le produit a été inséré, la réponse contient un objet Product . L’objet Product inclut l’ID de produit, que vous utilisez pour obtenir et supprimer l’offre.
Une offre doit inclure les champs suivants :
L’API utilise , channelcontentLanguage, targetCountryet offerId pour générer l’ID de produit. Étant donné que ces champs sont utilisés pour générer l’ID, vous ne pouvez pas les mettre à jour. L’ID de produit respecte la casse ; l’ID utilise la même casse que celle utilisée pour spécifier channel, contentLanguage, targetCountryet offerId.
Attention
Veillez à utiliser la même casse pour channel, , contentLanguagetargetCountryet , car offerId vous pouvez effectivement ajouter le même produit plusieurs fois si la casse est différente.
Les champs suivants sont également requis si le fabricant a affecté des valeurs.
Vous devez spécifier les valeurs si elles sont connues. Si vous ne les spécifiez pas, vous devez définir le champ identificateurExists sur false. The default is true.
Si le produit est connu pour avoir ces identificateurs et que vous ne les spécifiez pas, MMC accepte le produit pour le moment, mais l’objet Product dans la réponse inclut le warnings champ . Vous devez toujours case activée si le warnings champ existe et résoudre tous les problèmes identifiés.
Outre les champs obligatoires, vous devez également spécifier la date et l’heure d’expiration de l’offre (voir expirationDate). Par défaut, l’offre expire 30 jours à compter de la date et de l’heure d’écriture dans le magasin ou le catalogue. Vous devez suivre les produits qui approchent de l’expiration et avant qu’ils expirent, mettez à jour leur date d’expiration ou mettez simplement à jour le produit (vous n’avez pas besoin de mettre à jour les champs du produit), ce qui prolonge automatiquement la date d’expiration de 30 jours. Si vous définissez explicitement la date d’expiration, vous devez définir vous-même une nouvelle date d’expiration. La mise à jour du produit n’étend pas automatiquement la date d’expiration de 30 jours dans ce cas.
Tous les autres champs sont considérés comme facultatifs ; Toutefois, vous devez spécifier autant que nécessaire pour décrire précisément le produit.
Remarque
L’objet Product doit inclure uniquement les champs qui sont définis sur des valeurs. N’incluez pas de champs null dans l’objet Product . Par exemple, n’incluez "adult":nullpas .
Microsoft n’utilise pas tous les Product champs. Pour obtenir la liste des champs que l’API accepte mais n’utilise pas, consultez Quels attributs Google puis-je utiliser ? Tous les autres champs utilisés par Microsoft sont utilisés pour filtrer les produits lors de la diffusion d’annonces de produits.
Si vous spécifiez un champ inconnu de l’API de contenu, le service ignore le champ.
Lorsque vous insérez une offre, le service effectue des validations de base sur l’offre et retourne les erreurs et les avertissements appropriés. Si une erreur se produit, la réponse contient un ErrorResponse objet . Si des avertissements se produisent, la réponse contient un Product objet et le warnings champ répertorie les avertissements.
Si l’offre réussit les validations de base, elle subit des validations et des révisions hors connexion, telles que des révisions éditoriales, qui peuvent prendre jusqu’à 36 heures. L’offre ne sera pas proposée tant que toutes les validations et révisions ne seront pas terminées. Pour déterminer la status d’une offre, utilisez la ressource État.
Notez que l’API ne fournit pas de contrôles d’accès concurrentiel tels que les ETags. Si deux applications essaient d’ajouter ou de mettre à jour le même produit, la dernière est gagnant.
Une offre affichée dans une annonce de produit inclut le prix, le titre, le nom du magasin (ou sellerName si spécifié), un lien vers la page web qui contient plus d’informations sur le produit et une image du produit.
Pour les vêtements disponibles dans plusieurs couleurs, motifs ou matériaux, créez un produit pour chaque variante et utilisez le champ itemGroupId pour regrouper toutes les variantes de produit.
Pour obtenir un exemple de code qui montre comment insérer une offre de produit, consultez Exemple de code de gestion des produits.
Utilisation du traitement par lots
Si vous traitez plusieurs offres de produits, vous devez envisager d’utiliser la fonctionnalité de traitement par lots de l’API. Cette fonctionnalité vous permet de traiter plusieurs insertions, obtient et supprimes dans une seule requête. Le traitement de plusieurs offres dans la même demande est plus efficace que l’envoi d’une demande distincte pour chaque offre. Le coût du traitement d’une demande unique est réparti sur les milliers d’offres de la demande par lots au lieu d’entraîner ce coût pour chaque demande individuelle.
N’insérez pas, n’obtenez pas ou ne supprimez pas le même produit dans la même demande.
Pour envoyer une demande de traitement par lots, ajoutez le modèle suivant à l’URI de base.
{mmcMerchantId}/products/batch
Définissez sur {mmcMerchantId} votre ID de magasin MMC.
L’envoi d’une requête HTTP POST à l’URL résultante applique les opérations d’insertion au catalogue de magasin par défaut. Pour appliquer les offres à un catalogue spécifique, incluez le paramètre de requête bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456
Le corps de post est un objet Batch qui contient un tableau d’objets Item . Pour toutes les opérations, définissez les batchIdchamps , merchantId et method . le batchId est un ID défini par l’utilisateur que vous utilisez pour identifier l’élément de lot dans la réponse ; le merchantId est votre ID de magasin ; et le method est l’opération à effectuer (par exemple, insérer, supprimer ou obtenir).
Si method est insert, définissez le product champ sur un objet Product qui contient l’offre à ajouter ou à mettre à jour. Sinon, si method est une obtention ou une suppression, définissez productId sur l’ID complet de l’offre que vous souhaitez obtenir ou supprimer.
La taille du corps d’une demande de traitement par lots ne peut pas dépasser 4 Mo. Si le corps dépasse 4 Mo, la réponse retourne le code http status 413. Selon la taille de chaque offre (le nombre de champs que vous spécifiez), vous pouvez envoyer entre 2 000 et 6 000 offres. Si vous compressez le corps, vous pouvez envoyer le nombre maximal d’offres, qui est de 12 000 (selon leur taille).
Pour compresser le corps, utilisez la compression GZip uniquement et définissez l’en-tête Content-Encoding de la requête sur gzip.
Le service traite chaque élément du lot. La réponse contient un Batch objet qui contient chacun Item des éléments figurant dans la requête. Notez qu’il n’existe aucune garantie que l’ordre des éléments dans la réponse soit identique à celui des éléments de la demande.
Pour les opérations d’insertion, l’élément inclut uniquement les batchId champs et product . Le product champ contient la même offre que celle que vous avez envoyée dans la demande, mais inclut également l’ID de produit complet. Si une erreur ou un avertissement se produit, l’élément inclut les batchIdchamps , methodet error . Le error champ contient les raisons pour lesquelles l’insertion a échoué ou des avertissements concernant les problèmes liés à l’offre que vous devez corriger.
Pour les opérations d’obtention, l’élément inclut les batchId champs et product . Le product champ contient l’offre que vous avez demandée. Si le produit est introuvable, l’objet n’inclut pas le product champ .
Pour les opérations de suppression, l’élément inclut uniquement le batchId champ ; rien n’indique si l’offre existe et a été supprimée.
Pour obtenir un exemple de code qui montre comment utiliser le traitement par lots, consultez Création d’une demande de traitement par lots.