Serviços avançados do Google

Os serviços avançados no Google Apps Script permitem que você se conecte a determinadas APIs públicas do Google com menos configuração do que o uso das interfaces HTTP. Os serviços avançados são wrappers simples dessas APIs do Google. Eles funcionam de maneira muito parecida com os serviços integrados do Apps Script. Por exemplo, eles oferecem preenchimento automático, e o Apps Script processa o fluxo de autorização automaticamente. Ative um serviço avançado antes de usá-lo em um script.

Ativar serviços avançados

Para usar um serviço avançado do Google, siga estas instruções:

Etapa 1: ativar o serviço avançado

Ative um serviço avançado usando o editor de script do Apps Script ou editando o manifesto.

Método A: usar o editor

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Editor .
  3. À esquerda, ao lado de Serviços, clique em Adicionar um serviço .
  4. Selecione um serviço avançado do Google e clique em Adicionar.

Método B: usar o manifesto

Ative os serviços avançados editando o manifest file. Por exemplo, para ativar o serviço avançado do Google Drive, adicione o campo enabledAdvancedServices ao objeto dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

Depois de ativar um serviço avançado, ele fica disponível no preenchimento automático.

Etapa 2: ativar a API Google Cloud (somente projetos padrão do Google Cloud)

Se você estiver usando um projeto padrão do Google Cloud (criado automaticamente pelo Apps Script), pule esta etapa. A API é ativada automaticamente quando você adiciona o serviço na etapa 1.

Se você estiver usando um projeto na nuvem padrão Google Cloud, ative manualmente a API correspondente ao serviço avançado. Para ativar a API manualmente:

  1. Abra o projeto na nuvem associado ao script no ** console do Google Cloud**

  2. Na parte de cima do console do Google Cloud, clique na barra de pesquisa e digite parte do nome da API (por exemplo, "Agenda"). Em seguida, clique no nome quando ele aparecer.

  3. Clique em Ativar API.

  4. Feche o console do Google Cloud e volte ao editor de scripts.

Como as assinaturas de método são determinadas

Os serviços avançados geralmente usam os mesmos objetos, nomes de métodos e parâmetros das APIs públicas correspondentes, embora as assinaturas de método sejam traduzidas para uso no Apps Script. A função de preenchimento automático do editor de scripts geralmente fornece informações suficientes para começar. As regras a seguir explicam como o Apps Script gera uma assinatura de método de uma API pública do Google.

As solicitações para APIs do Google podem aceitar vários tipos diferentes de dados, incluindo parâmetros de caminho, parâmetros de consulta, um corpo de solicitação ou um anexo de upload de mídia. Alguns serviços avançados também podem aceitar cabeçalhos de solicitação HTTP específicos (por exemplo, o serviço avançado da Agenda).

A assinatura de método correspondente no Apps Script tem os seguintes argumentos:

  1. O corpo da solicitação (geralmente um recurso), como um objeto JavaScript.
  2. Parâmetros de caminho ou obrigatórios, como argumentos individuais. Se o método exigir vários parâmetros de caminho, eles vão aparecer na ordem em que são listados no URL do endpoint da API.
  3. O anexo de upload de mídia, como um Blob argumento.
  4. Parâmetros opcionais (normalmente parâmetros de consulta), como um objeto JavaScript que mapeia nomes de parâmetros para valores.
  5. Cabeçalhos de solicitação HTTP, como um objeto JavaScript que mapeia nomes de cabeçalhos para valores de cabeçalhos.

Se o método não tiver itens em uma determinada categoria, essa parte da assinatura será omitida.

Conheça estas exceções:

  • Para métodos que aceitam um upload de mídia, o parâmetro uploadType é definido automaticamente.
  • Os métodos chamados delete na API do Google são chamados remove no Apps Script, já que delete é uma palavra reservada em JavaScript.
  • Se um serviço avançado estiver configurado para aceitar cabeçalhos de solicitação HTTP e você definir um objeto JavaScript de cabeçalhos de solicitação, também será necessário definir o objeto JavaScript de parâmetros opcionais (para um objeto vazio se você não estiver usando parâmetros opcionais).

Exemplo: Calendar.Events.insert

Para criar um evento da Agenda:

A documentação da API Google Agenda mostra a estrutura de solicitação HTTP correspondente:

  • Verbo HTTP: POST
  • URL da solicitação: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

  • Corpo da solicitação: um recurso de evento.

  • Parâmetros de consulta: sendUpdates, supportsAttachments, etc.

No Apps Script, a assinatura do método é determinada pela reordenação dessas entradas:

  1. Corpo: o recurso de evento (objeto JavaScript).
  2. Caminho: o calendarId (string).
  3. Parâmetros opcionais: os parâmetros de consulta (objeto JavaScript).

A chamada de método resultante é assim:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Serviços avançados ou HTTP?

Cada serviço avançado do Google está associado a uma API pública do Google. No Apps Script, acesse essas APIs usando serviços avançados ou fazendo as solicitações de API diretamente usando UrlFetch.

Se você usar o método de serviço avançado, o Apps Script vai processar o fluxo de autorização e oferecer suporte ao preenchimento automático. Ative o serviço avançado antes de usá-lo.

Se você usar o método UrlFetch para acessar a API diretamente, vai tratar a API do Google como uma API externa. Com esse método, use todos os aspectos da API. No entanto, você precisa processar a autorização da API.

A tabela a seguir compara os dois métodos:

Recurso Serviço avançado UrlFetch (HTTP)
Autorização Processada automaticamente Processamento manual necessário
Preenchimento automático Disponível Indisponível
Escopo de funcionalidade Pode ser um subconjunto da API Acesso total a todos os recursos da API
Complexidade Mais fácil Mais complexo (requer a criação de cabeçalhos e a análise de respostas)

Comparação de código

Os exemplos de código mostram a diferença de complexidade entre a criação de um evento da Agenda usando o serviço avançado e o uso de UrlFetchApp.

Serviço avançado:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Para o método UrlFetchApp, especifique manualmente os escopos OAuth necessários no arquivo de manifesto do script.

Use um serviço avançado sempre que possível e use o método UrlFetch somente quando o serviço avançado não estiver disponível ou não fornecer a funcionalidade necessária.

Suporte para serviços avançados

Como os serviços avançados são wrappers simples das APIs do Google, qualquer problema encontrado ao usá-los geralmente é um problema com a API subjacente, não com o Apps Script.

Se você encontrar um problema ao usar um serviço avançado, informe-o usando as instruções de suporte da API subjacente.