Catégories
Apps Scripts formations

Utilisez l’API Itunes avec Google Sheet

formation Apps Script récupérer les infos Itunes Music via l’API JSON en Javascript

Tutoriel API pour les débutants:
qu’est-ce que Apps Script?

Dans ce tutoriel d’API pour les débutants, nous utiliserons Google Apps Script pour nous connecter à des API externes.

Google Apps Script est un langage de script basé sur Javascript hébergé et exécuté sur les serveurs Google, qui étend les fonctionnalités de Google Apps.

Nous allons commencer par quelque chose de très simple dans ce tutoriel , afin que vous puissiez  vous concentrez uniquement sur les données et ne vous perdez pas dans les lignes et les lignes de code.

Construisons nous-mêmes une application de découverte musicale dans Google Sheets.

Cette application récupèrera le nom d’un artiste depuis la feuille Google Sheet, on envoie une requête à l’API iTunes qui permet de récupérer des informations sur cet artiste et les nous afficher les données correspondantes.
Il affiche ensuite les albums, les titres des chansons, les illustrations et ajoute même un lien pour écouter un extrait musicale :

Vous allez voir que ce n’est pas aussi difficile qu’il y paraît.

Introduction à l’API iTunes et JSON :
Si vous avez suivi ma dernière vidéo (lien youtube), que je vous invite à regarder, je vous expliquais ce qu’était le format JSON et à quoi il servait.
Le JSON ( JavaScript Object Notation ) est un format de données textuelles dérivé de la notation des objets du langage JavaScript. Il permet de représenter de l’information structurée par pair de valeurs.
ex: Nos requêtes à l’Api vont nous renvoyer, tous les albums de l’artiste rechercher au format JSON, ce qui va nous permettre de trier et d’afficher ces données sur notre Sheet.

[{ "id": 1, "first_name": "Alejoa", "last_name": "Juszkiewicz", "email": "ajuszkiewicz0@bizjournals.com", "gender": "Male", "ip_address": "252.241.27.80" },
{ "id": 2, "first_name": "Aristotle", "last_name": "Cawsey", "email": "acawsey1@patch.com", "gender": "Male", "ip_address": "228.119.38.179" }]

START 

Commencez avec une  feuille Google Sheet vierge, nommez-la : 
“ iTunes Search” et ouvrez l’éditeur de Google Apps Script .

Nommez votre Script  “Itunes” et collez-le code suivant pour commencer :

function calliTunes () {
// Appel de L'API Itunes
var response = UrlFetchApp.fetch ("https://itunes.apple.com/search?term=coldplay&limit=50");
Logger.log (response.getContentText ());}

Exécutez le programme et acceptez les autorisations requises. Vous obtiendrez un résultat comme celui-ci:

iTunes API output

Youpppi !!!  , il y a beaucoup plus de données renvoyées cette fois, nous allons donc devoir les passer au crible pour extraire les éléments que nous voulons.

Analyse des données iTunes

Alors essayez ceci. Mettez à jour votre code pour analyser les données et extraire certaines informations:

// Appel de l'API iTunes 
// et récuperation des infos en JSON
function calliTunes() {
var response = UrlFetchApp.fetch("https://itunes.apple.com/search?term=coldplay&limit=50");
// Parsing des données pour affichage
var json = response.getContentText();
var data = JSON.parse(json);
Logger.log(data);
Logger.log(data["results"]);
Logger.log(data["results"][0]);
Logger.log(data["results"][0]["artistName"]);
Logger.log(data["results"][0]["collectionName"]);
Logger.log(data["results"][0]["artworkUrl60"]);
Logger.log(data["results"][0]["previewUrl"]);}

Ligne 4: Nous envoyons une demande à l’API iTunes pour rechercher des données du groupe “Coldplay”.
L’API répond avec ces données et nous l’attribuons à une variable appelée “response”, afin que nous puissions utiliser ce nom pour y faire référence.

Lignes 6 et 7: Nous récupérons le texte contextuel des données de réponse, puis analysons la réponse de chaîne JSON pour obtenir la représentation d’objet native.
Cela nous permet d’extraire différents éléments de données.

Ci dessous la visualisation de l’objet de données retourné (ligne 10) dans le debugger d’Apps Scripts ( Ctrl + Entré) pour afficher :

Nota : Vous pouvez voir que c’est un objet JSON avec l’accolade en début {

iTunes api data packet

Ligne 9: nous extrayons les «résultats», qui sont les données qui contiennent les informations sur l’artiste et la chanson, en utilisant:

data ["results"]

Ligne 10: Il y a plusieurs albums retournés pour cet artiste, nous prenons donc le premier en utilisant la référence [0] puisque l’index commence d’un tableau ou Array commence toujours à 0:

data ["results"] [0]

Ceci montre toutes les informations disponibles depuis l’API iTunes pour cet artiste et cet album en particulier:

Lignes 11 – 14: Nous pouvons extraire les détails spécifiques que nous voulons en nous référant à leurs noms de colonnes JSON:

par exemple  :

data ["results"] [0] ["collectionName"]

En commentant les lignes 8, 9 et 10 nous aurons la sortie suivante:

iTunes api details

Utilisons notre API pour mettre tout cela dans une application

Nous voulons créer l’application maintenant comme promis dans cet article, nous devons donc suivre les étapes suivantes de notre
cahier des charges:

  1. Configurer la feuille Google
  2. Récupérer le nom de l’artiste à partir de la feuille Google avec Google Apps Script
  3. Demander des données à iTunes pour cet artiste avec Google Apps Script
  4. Analyser la réponse pour extraire l’objet de données pertinent avec Google Apps Script
  5. Extraire les détails spécifiques que nous voulons (nom de l’album, titre de la chanson, illustration de l’album, URL de d’écoute ).
  6. Effacer tout précédent résultats dans la feuille Google avant d’afficher les nouveaux résultats
  7. Afficher les nouveaux résultats dans notre feuille Google
  8. Ajoutez un menu personnalisé pour exécuter le programme à partir de la feuille Google, pas de l’éditeur de script

C’est toujours une bonne idée de visualiser chaque étapes de vos fonctionnalitées avant d’écrire des lignes de code.

De cette façon, vous pouvez réfléchir à l’ensemble de l’application et à ce qu’elle va faire, ce qui vous permet de faire des choix efficaces avec la façon dont vous configurez votre code.

A partir de notre fichier Google Sheet.
Vous pouvez vous inspirer de ma capture d’écran ci dessous:

A noter que l’emplacement de la cellule où on tapera notre recherche, soit le nom de l’artiste se trouve ( ligne 11, 2e colonne) car nous y feront référence dans notre code.
A adapter selon votre document.

Code iTunes API

Toujours dans Google Apps Script …

Coller y le script complet ci dessous de notre Application dans votre fichier créer plus haut pour nos tests.

Enregistrer et lancez la function onOpen() puis validez les autorisations si on vous le demande.
Vous avez désormais un nouveau menu dans votre feuille Sheet, pour lancer une recherche…

api itunes en javascript avec google sheet

Mais étudions en détail notre script ci dessous:

// --------------------------------------------------------------------------------------------------
//
// iTunes  Application in Google Sheets
//
// --------------------------------------------------------------------------------------------------
 
// Menu déroulant
function onOpen() {
  var ui = SpreadsheetApp.getUi();
  ui.createMenu('iTunes Menu')
      .addItem('Rechercher un Artiste','displayArtistData')
      .addToUi();
}
 
// function d'appel de l'API ITUNES
function calliTunesAPI(artist) {
  
  // Appelde l'API
  var response = UrlFetchApp.fetch("https://itunes.apple.com/search?term=" + artist + "&limit=200");
  
  // Parsing du retour JSON 
  var json = response.getContentText();
  return JSON.parse(json);
  
}
 
// Function principale de recherche via notre Google Sheet
function displayArtistData() {
  
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var sheet = ss.getSheetByName("itunes");
  // modifier ci dessous ci votre champ de recherche est différent.
  var artist = sheet.getRange(11,2).getValue();
  
  var tracks = calliTunesAPI(artist);
  
  var results = tracks["results"];
  
  var output = []
  
  results.forEach(function(elem,i) {
    var image = '=image("' + elem["artworkUrl60"] + '";4;90;90)';
    var hyperlink = '=hyperlink("' + elem["previewUrl"] + '";"Ecouter")';
    output.push([elem["artistName"],elem["collectionName"],elem["trackName"],image,hyperlink]);
    sheet.setRowHeight(i+15,65);
  });
  
  // Trie par albums
  var sortedOutput = output.sort( function(a,b) {
    
    var albumA = (a[1]) ? a[1] : 'Not known';
    var albumB = (b[1]) ? b[1] : 'Not known';
    
    if (albumA < albumB) {
      return -1;
    }
    else if (albumA > albumB) {
      return 1;
    }
    // Si Nom identiques
    return 0;
  });
  
  // Ajouter d'un index à notre tableau 
  sortedOutput.forEach(function(elem,i) {
    elem.unshift(i + 1);
  });
  
  var len = sortedOutput.length;
  
  // Nettoyage de la Sheet
  sheet.getRange(15,1,500,6).clearContent();
  
  // Collage des valeurs trouvées
  sheet.getRange(15,1,len,6).setValues(sortedOutput);
  
  // formatage des données
  sheet.getRange(15,1,500,6).setVerticalAlignment("middle");
  sheet.getRange(15,5,500,1).setHorizontalAlignment("center");
  sheet.getRange(15,2,len,3).setWrap(true);
  
}

Comment cela fonctionne:

Les lignes 16 à 25 : décrivent une fonction qui prend un nom d’artiste, appelle l’API avec ce nom d’artiste, puis renvoie les résultats de la recherche à partir de l’API.
J’ai encapsulé cela comme une fonction distincte afin que je puisse potentiellement la réutiliser ailleurs dans mon programme.

La function principale commence à la ligne 28.

À la ligne 34, je récupère le nom de l’artiste qui a été saisi sur la feuille Google Sheet.
la ligne 36, et nous appelons notre fonction principale et nous lui passons en paramètre la variable contenant le nom de l’Artiste.

Aux lignes 42 à 47, je prends les résultats renvoyés par l’API, je fait une boucle et j’extrait uniquement les données voulu comme :
(nom de l’artiste, nom de l’album, titre de la chanson, illustration de l’album et l’extrait ).
J’enregistre tout cela dans un nouveau tableau appelé « Output » ( sortie ).

Ensuite, je trie et ajoute un index au tableau, bien que ces deux étapes ne soient pas obligatoires.

À la ligne 68, j’efface tout contenu précédent de ma feuille.

Ensuite, à la ligne 71, je colle les nouvelles données, à partir de la ligne 15 de ma Sheet.

Enfin, les lignes 74 à 76 formate les données nouvellement collées, de sorte que les images aient de l’espace pour s’afficher correctement.

En début ligne 8, nous ajouterons une fonction onOpen () à partir de l’éditeur de script pour ajouter le menu personnalisé à votre feuille Google Sheet. Ensuite, vous pourrez exécuter votre script ITunes à partir de celle ci.

vous pouvez maintenant exécuter le programme pour rechercher votre artiste préféré ! et en écouter les extraits.

Plus de détails sur l’API iTunes:

Documentation pour rechercher dans l’iTunes Store.

Documentation montrant le paquet JSON des résultats de la recherche.

/

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *