APIs externas

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

Acessar APIs públicas

Você pode usar o serviço UrlFetch para fazer solicitações de API diretamente.

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

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

Autenticar usando uma conta de serviço

Para chamar uma API do Apps Script, você pode usar a autenticação da conta de serviço por qualquer um dos seguintes motivos:

  • Melhor desempenho com as APIs do Google Cloud
  • Automações e tarefas de longa duração
  • Segurança aprimorada (privilégio mínimo)
  • Gerenciamento de acesso centralizado

Para usar uma conta de serviço no Apps Script, consulte Autenticar como um projeto do Apps Script usando contas de serviço.

Trabalhar com JSON

Trabalhar com objetos JSON é semelhante a trabalhar com XML, exceto que analisar ou codificar um objeto JSON é muito mais fácil.

Se a API solicitada retornar uma resposta JSON bruta para uma solicitação, a resposta de string JSON poderá ser acessada usando o método HTTPResponse.getContentText(). Depois que essa string for recuperada, basta chamar JSON.parse() nela 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, crie 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.