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 »

Gérer les 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 ».

Nouveaux 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…)

 

Le scratchpad

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…)

Détail de la requête envoyée

 

  • 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()

Réponse renvoyée au format JSON

 

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 !

Snippet php

 

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)

Déroulant resources

 

Cliquer à nouveau sur « Run request ». La réponse s'est enrichie de quelques blocs. La variable $payload dans le snippet de code aussi.

Réponse après choix de resources

 

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'];

 

Karine SANCHE

Partager cet article