APIs externas

O Google Apps Script pode interagir com APIs de toda a Web. Use este guia para trabalhar com diferentes tipos de APIs nos seus scripts.

Acessar APIs públicas

Use 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 exige 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 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 destes motivos:

  • Melhor desempenho com as APIs do 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.

Conectar aos serviços do Google Cloud

É possível usar o ScriptApp.getIdentityToken() método para receber um token de identidade do OpenID Connect (um JSON Web Token ou JWT) para o usuário efetivo. Você pode usar esse token para autenticar com serviços do Google Cloud, como o Cloud Run, que estão configurados para aceitá-lo.

Para mais informações, consulte Conectar aos serviços do Google Cloud.

Trabalhar com JSON

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

Quando uma API retorna uma resposta JSON bruta, acesse a resposta da string JSON usando o método HTTPResponse.getContentText. Depois de recuperar a string, use JSON.parse() para analisá-la em um objeto JavaScript.

// 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 converter um objeto JavaScript em uma string JSON para um payload de 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, acesse 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, use os XmlService métodos para construir o XML a ser enviado.

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.