API externes

Google Apps Script peut interagir avec des API provenant du monde entier. Ce guide explique comment utiliser différents types d'API dans vos scripts.

Se connecter à des API publiques

Vous pouvez utiliser le service UrlFetch pour envoyer des requêtes d'API directement.

L'exemple suivant utilise l'API GitHub pour rechercher les dépôts comportant au moins 100 étoiles et mentionnant "Apps Script". Cette requête d'API ne nécessite pas d'autorisation ni de clé API.

var query = '"Apps Script" stars:">=100"';
var url = 'https://api.github.com/search/repositories'
  + '?sort=stars'
  + '&q=' + encodeURIComponent(query);

var response = UrlFetchApp.fetch(url, {'muteHttpExceptions': true});
Logger.log(response);

Envoyer des requêtes à des services avec OAuth

Les API qui agissent au nom d'un utilisateur nécessitent généralement une autorisation, souvent à l'aide du protocole OAuth. Apps Script n'est pas compatible avec le protocole, mais il existe des bibliothèques Open Source que vous pouvez utiliser pour effectuer le flux OAuth et envoyer les identifiants avec vos requêtes :

• OAuth1 pour Apps Script : compatible avec OAuth 1.0 et 1.0a.
• OAuth2 pour Apps Script : compatible avec OAuth2.

Utiliser JSON

L'utilisation d'objets JSON est semblable à celle d'objets XML, sauf que l'analyse ou l'encodage d'un objet JSON est beaucoup plus facile.

Si l'API demandée renvoie une réponse JSON brute pour une requête, la réponse de chaîne JSON est accessible à l'aide de la méthode HTTPResponse.getContentText(). Une fois cette chaîne récupérée, il vous suffit d'appeler JSON.parse() sur la chaîne pour obtenir une représentation d'objet natif.

// Make request to API and get response before this point.
var json = response.getContentText();
var data = JSON.parse(json);
Logger.log(data.title);

De même, pour créer une représentation sous forme de chaîne d'un objet JavaScript afin d'effectuer une requête, utilisez JSON.stringify().

var data = {
  'entry': {
    'group': {
      'title': 'Dog Skateboarding',
      'description': 'My dog gets some serious air'
    },
    'keywords': 'dog, skateboard'
  }
}
var payload = JSON.stringify(data);
// Make request to API with payload after this point.

Analyser un flux XML

Si une API externe renvoie une réponse XML brute pour une requête, vous pouvez accéder à la réponse XML à l'aide de la méthode HTTPResponse.getContentText().

// Make request to API and get response before this point.
var xml = response.getContentText();
var doc = XmlService.parse(xml);

Lorsque vous envoyez des requêtes XML à une API, créez le code XML à envoyer à l'aide des méthodes XmlService.

var root = XmlService.createElement('entry')
    .setAttribute('keywords', 'dog, skateboard');
var group = XmlService.createElement('group')
    .setAttribute('title', 'Dog Skateboarding');
    .setAttribute('description', 'My dog gets some serious air');
root.addContent(group);
var document = XmlService.createDocument(root);
var payload = XmlService.getPrettyFormat().format(document);
// Make request to API with payload after this point.