APIs externas

O Google Apps Script pode interagir com APIs de toda a Web. Neste guia, mostramos como trabalhar com diferentes tipos de APIs nos seus scripts.

Conectar-se a APIs públicas

É possível usar o serviço UrlFetch para fazer solicitações de API diretamente.

O exemplo a seguir usa a API GitHub para pesquisar repositórios com 100 ou mais estrelas que mencionam "Apps Script". Essa solicitação de API não requer autorização ou uma chave de 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);

Fazer solicitações para serviços com o OAuth

As APIs que atuam em nome de um usuário geralmente exigem autorização e costumam usar o protocolo OAuth. O Apps Script não oferece suporte integrado ao protocolo, mas existem bibliotecas de código aberto que podem ser usadas para executar o fluxo do OAuth e enviar as credenciais com suas solicitações:

Trabalhar com JSON

Trabalhar com objetos JSON é semelhante ao XML, exceto que a análise ou codificação de um objeto JSON é muito mais fácil.

Se a API solicitada retornar uma resposta JSON bruta para uma solicitação, a resposta da string JSON poderá ser acessada usando o método HTTPResponse.getContentText(). Depois que essa string for recuperada, basta chamar JSON.parse() na string para receber uma representação de objeto nativo.

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

Da mesma forma, para fazer uma representação de string de um objeto JavaScript e fazer uma solicitação, use 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.

Analisar XML

Se uma API externa retornar uma resposta XML bruta para uma solicitação, você poderá acessar a resposta XML usando o método HTTPResponse.getContentText().

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

Ao fazer solicitações XML para uma API, construa o XML a ser enviado usando os métodos 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.