API externes

Google Apps Script peut interagir avec des API provenant du monde entier. Utilisez ce guide pour travailler avec différents types d'API dans vos scripts.

Se connecter à des API publiques

Utilisez le service UrlFetch pour envoyer directement des requêtes d'API.

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 :

S'authentifier avec un compte de service

Pour appeler une API depuis Apps Script, vous pouvez choisir d'utiliser l'authentification par compte de service pour l'une des raisons suivantes :

  • Améliorer les performances avec les API Google Cloud
  • Automatisations et tâches de longue durée
  • Sécurité renforcée (moindre privilège)
  • Gestion centralisée des accès

Pour utiliser un compte de service dans Apps Script, consultez S'authentifier en tant que projet Apps Script à l'aide de comptes de service.

Se connecter aux services Google Cloud

Vous pouvez utiliser la méthode ScriptApp.getIdentityToken() pour obtenir un jeton d'identité OpenID Connect (un jeton Web JSON ou JWT) pour l'utilisateur effectif. Vous pouvez utiliser ce jeton pour vous authentifier auprès des services Google Cloud, tels que Cloud Run, qui sont configurés pour l'accepter.

Pour en savoir plus, consultez Se connecter aux services Google Cloud.

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.

Lorsqu'une API renvoie une réponse JSON brute, accédez à la réponse de chaîne JSON à l'aide de la méthode HTTPResponse.getContentText. Une fois la chaîne récupérée, utilisez JSON.parse() pour l'analyser en un objet JavaScript.

// 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 convertir un objet JavaScript en chaîne JSON pour une charge utile de 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, accédez à 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, utilisez les méthodes XmlService pour créer le code XML à envoyer.

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.