Serviços avançados do Google

Os serviços avançados no Apps Script permitem que desenvolvedores experientes se conectem a determinadas APIs públicas do Google com menos configuração do que usando as interfaces HTTP. Os serviços avançados são essencialmente wrappers simples dessas APIs do Google. Eles funcionam de maneira muito parecida com os serviços integrados do Apps Script. Por exemplo, oferecem preenchimento automático, e o Apps Script processa o fluxo de autorização automaticamente. No entanto, é necessário ativar um serviço avançado antes de usá-lo em um script.

Para saber quais APIs do Google estão disponíveis como serviços avançados, procure a seção Serviços avançados do Google na Referência. Se você quiser usar uma API do Google que não está disponível como um serviço avançado, basta se conectar a ela como qualquer outra API externa.

Serviços avançados ou HTTP?

Cada um dos serviços avançados do Google está associado a uma API pública do Google. No Apps Script, é possível acessar essas APIs usando serviços avançados ou simplesmente fazendo as solicitações de API diretamente com UrlFetch.

Se você usa o método de serviço avançado, o Apps Script processa o fluxo de autorização e oferece suporte ao preenchimento automático. No entanto, é necessário ativar o serviço avançado antes de usá-lo. Além disso, alguns serviços avançados oferecem apenas um subconjunto da funcionalidade disponível na API.

Se você usar o método UrlFetch para acessar a API diretamente, estará tratando a API do Google como uma API externa. Com esse método, todos os aspectos da API podem ser usados. No entanto, é necessário processar a autorização da API por conta própria. Você também precisa criar os cabeçalhos necessários e analisar as respostas da API.

Em geral, é mais fácil usar um serviço avançado sempre que possível e usar o método UrlFetch apenas quando o serviço avançado não oferece a funcionalidade necessária.

Requisitos

Antes de usar um serviço avançado, é necessário atender aos seguintes requisitos:

1. É necessário ativar o serviço avançado no projeto de script.

2. Verifique se a API correspondente ao serviço avançado está ativada no projeto do Cloud Platform (GCP) usado pelo script.

   Se o projeto de script usar um projeto padrão do GCP criado em 8 de abril de 2019 ou depois dessa data, a API será ativada automaticamente depois que você ativar o serviço avançado e salvar o projeto de script. Se você ainda não tiver feito isso, talvez seja necessário concordar com os Termos de Serviço do Google Cloud e das APIs do Google.

   Se o projeto de script usar um projeto padrão do GCP ou um projeto padrão mais antigo do GCP, ative manualmente a API correspondente do serviço avançado no projeto do GCP. É necessário ter acesso de edição ao projeto do GCP para fazer essa mudança.

Consulte Projetos do Cloud Platform para mais informações.

Ativar serviços avançados

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

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.

Observação: se você estiver usando um projeto padrão do GCP (ou um projeto padrão mais antigo do GCP criado antes de 8 de abril de 2019), também será necessário ativar manualmente a API correspondente ao serviço avançado. Para ativar a API, faça o seguinte:

1. Abra o projeto do GCP associado ao script no console do Google Cloud.
2. Na parte de cima do console, clique na barra de pesquisa e digite parte do nome da API (por exemplo, "Calendar"). Depois, clique no nome quando ele aparecer.
3. Na próxima tela, clique em Ativar API.
4. Feche o console do Google Cloud e volte ao editor de script. Clique em OK na caixa de diálogo.

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

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 script geralmente fornece informações suficientes para começar, mas as regras abaixo 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 e/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, como o serviço avançado do Google Agenda.

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

1. O corpo da solicitação (geralmente um recurso), como um objeto JavaScript.
2. Caminho ou parâmetros obrigatórios, como argumentos individuais.
3. O anexo de upload de mídia, como um argumento Blob.
4. Parâmetros opcionais, 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çalho para valores de cabeçalho.

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

Há algumas exceções especiais:

• 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 de 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 (como um objeto vazio se você não estiver usando parâmetros opcionais).

Suporte para serviços avançados

Os serviços avançados são apenas wrappers simples que permitem o uso de APIs do Google no Apps Script. Portanto, qualquer problema encontrado ao usar essas APIs geralmente é com a API subjacente, não com o próprio Apps Script.

Se você encontrar um problema ao usar um serviço avançado, ele deverá ser denunciado usando as instruções de suporte da API subjacente. Os links para essas instruções de suporte estão disponíveis em cada guia de serviço avançado na seção Referência do Apps Script.