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 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 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

Use o método ScriptApp.getIdentityToken() para receber um token de identidade OpenID Connect (um JSON Web Token ou JWT) para o usuário efetivo. É possível 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-se aos serviços do Google Cloud.

Trabalhar com JSON

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

Quando uma API retorna uma resposta JSON bruta, acesse a resposta de 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 uma carga útil 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 métodos XmlService 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.