Migration vers la version 5 de l'API Product Advertising d'Amazon
« Et merde, encore une mise Ă jour, je vais encore perdre des heures Ă pĂ©ter tout mon code… » Tel Ă©tait mon Ă©tat d'esprit le 22 janvier 2020 quand j'ai reçu le mail d'Amazon m'annonçant le passage Ă la nouvelle version de leur API qui me permet de rĂ©cupĂ©rer le lien affiliĂ© vers leurs produits.
En plus, la deadline pour migrer est super courte : le 9 mars 2020.
Heureusement, la tâche s'est rĂ©vĂ©lĂ©e moins ardue que je le craignais. Et comme pour le moment toutes les ressources disponibles sont dans la langue de Shakespeare, je vais tenter de vous en rĂ©sumer l'essentiel et de vous donner les liens utiles pour ne pas trop galĂ©rer Ă votre tour…
L'API Product Advertising d'Amazon, à quoi ça sert ?
Prenons l'exemple d'un site tel que Promoclub : si vous ne connaissez pas, c'est une plateforme spécialisée dans la musique électronique que j'ai créée afin de permettre aux artistes de faire la promotion de leurs sorties récentes. Et s'ils ont omis de préciser le lien vers Amazon, un appel l'API Product Advertising permet de récupérer le lien automatiquement (avec mon code de tracking afin que je touche une commission si quelqu'un achète le titre) vers la fiche du produit sur le site Amazon.
Plutôt pratique, quand on sait que près d'une trentaine de titres sont proposés tous les jours sur la plateforme.
Quoi de neuf dans la version 5.0 ?
Alors j'avoue que je n'ai pas trop creusĂ© les nouveautĂ©s de la PA-API 5.0, mais Amazon promet une API plus facile Ă intĂ©grer grâce Ă un SDK qui prend en charge tout le process de signature, sĂ©rialisation et dĂ©sĂ©rialisation. On nous fait Ă©galement miroiter des temps de rĂ©ponse plus courts, grâce Ă l'abandon du format XML pour le format JSON. Enfin, cette nouvelle API apporterait une meilleure expĂ©rience utilisateur…
Si vous voulez en savoir plus, vous pouvez consulter le guide complet des nouveautés sur la documentation de l'API.
Allez, c'est parti pour la migration du compte, dont la première étape consiste à générer de nouvelles clés d'accès.
Migrer son compte vers la nouvelle version
Vous allez devoir générer une nouvelle paire de clés. Les anciennes clés continueront à fonctionner avec votre ancien code d'appel, du moins jusqu'au 9 mars.
J'ai cherché partout sur le Club Partenaires Amazon un moyen de générer ces nouvelles clés, pas trouvé. Je suis finalement passée par un lien direct. En fait, c'est dans Outils > Product Advertising API. Descendre jusqu'au bloc « Gérez vos identifiants »
Cliquer sur le bouton « Ajouter identifiants« .
Amazon gĂ©nère une nouvelle paire clĂ© d'accès (celle qui commence par AKIA…) + clĂ© secrète (quelque chose comme « fQjVo8X03xbGVhxJEXJEWgjSMXXp0jIjfxLS6dXj »). Vous pouvez faire un copier-coller de celles-ci, ou mĂŞme les tĂ©lĂ©charger en cliquant sur le bouton « TĂ©lĂ©chargement des identifiants ».
Appel Ă l'API en php
Alors deux solutions : soit je tâtonne pour adapter mon code en avalant des pages entières de doc et j'y passe des journées entières sans résultat garanti, soit (solution moins glorieuse mais plus efficace) j'essaie de voir s'il n'existe pas déjà du code tout fait.
Le scratchpad
Le mieux, c'est d'utiliser ce qu'ils appellent le scratchpad (en français, bloc de papier brouillon). Le scratchpad va non seulement vous donner un exemple de la réponse renvoyée, mais surtout un snippet de code en java et en php ! On aimerait bien que tous les éditeurs d'API fournissent un tel outil (n'est-ce pas Tradedoubler ?)
Il y a en a un par pays oĂą Amazon est implantĂ© (ah, quand est-ce qu'ils se dĂ©cideront Ă fusionner tout ça en un compte unique… soupir). La liste complète des scratchpads est ici. La version du scratchpad pour Amazon France se trouve lĂ .
Dans le menu de gauche, choisissez l'opération qui vous intéresse. Perso, ce dont j'ai besoin, c'est SearchItems.
Il y a deux formulaires Ă remplir :
- Common parameters (l'Amazon du pays voulu, le type de partenariat (Associates), votre tag affilié, les clés que vous avez générées à l'étape précédente)
- SearchItems (les paramètres de la requĂŞte : mots-clĂ©s, Ă©lĂ©ments Ă renvoyer, catĂ©gorie…)
Pour trouver la valeur à mettre dans SearchIndex (la catégorie de produits), il faut se référer à cette liste de valeurs. Il y a eu quelques changements depuis le passage à l'API 5 : par exemple le SearchIndex pour « Téléchargement de musique » qui était autrefois « MP3Downloads » est devenu « DigitalMusic ».
Cliquez sur le bouton Run Request. Le scratchpad vous affiche :
- ce Ă quoi ressemble la requĂŞte que vous envoyez (pas le plus intĂ©ressant pour moi, mais quand mĂŞme, c'est bien de l'avoir…)
- ce que l'API vous retourne (visuellement, au format JSON et au format HTML). Utile pour adapter la partie de votre code dans laquelle vous parsez la réponse reçue. Vous pouvez dire adieu à simplexml_load_string() et bonjour à json_decode()
Moi, par exemple, pour récupérer le lien du 1er résultat de la liste à partir du JSON retourné ($response), je vais utiliser cette fonction :
function retrieve_link_amazon_v5($response) {
$data = json_decode($response, true);
return $data['SearchResult']['Items'][0]['DetailPageURL'];
}
- les snippets de code pour reproduire cela sur votre site, en Java, PHP et cURL. Le plus intéressant !
Le scratchpad propose aussi un système d'historique vous permettant de revenir sur vos essais précédents.
Adapter Ă vos besoins
Il faudra adapter le code : remplacer les astĂ©risques par votre clĂ© privĂ©e, mettre une variable pour les mots-clĂ©s qui sont en dur dans $payload (parce que vous n'allez pas toujours chercher le mĂŞme produit)…
La définition de la classe AwsV4 (AWS Signature Version 4) se trouve en fin de snippet. Je l'ai placée dans un fichier à part que j'ai nommé AwsV4.class.php, que j'appelle ensuite dans mon script via
include("AwsV4.class.php");
Il faut prévoir un système pour catcher l'exception, ou alors le remplacer par autre chose (dans mon cas, un simple echo).
Si vous prĂ©fĂ©rez une approche plus orientĂ©e objet (faut aimer…), vous pouvez regarder ce snippet sur la page de la doc « Without SDK ».
Récupérer plus d'éléments
Et si je veux rapatrier plus d'infos que le simple lien vers le produit ? Il va falloir s'intĂ©resser au champ Resources du 2e formulaire. Il est possible d'en sĂ©lectionner plusieurs Ă la fois. J'ai beaucoup tâtonnĂ©, parce que les libellĂ©s ne sont pas toujours très clairs…
Par exemple, Images.Primary.Small me permet de récupérer la miniature de l'image du produit, et ItemInfo.ByLineInfo le nom de l'artiste interprétant la chanson (ainsi que la maison de disque)
Cliquer à nouveau sur « Run request ». La réponse s'est enrichie de quelques blocs. La variable $payload dans le snippet de code aussi.
Après, il ne reste plus qu'à les récupérer :
$data = json_decode($response, true);
$item = $data['SearchResult']['Items'][0];
$link = $item['DetailPageURL'];
$image = $item['Images']['Primary']['Small'];
$artist= $item['ItemInfo']['ByLineInfo']['Contributors']['Name'];
$label= $item['ItemInfo']['ByLineInfo']['Manufacturer']['DisplayValue'];
$title= $item['ItemInfo']['Title'];