Nível de programação: intermediário
Duração: 30 minutos
Tipo de projeto: complemento do Google Workspace
Objetivos
- Entenda o que o complemento faz.
- Aprender a criar um complemento usando o Apps Script e entender a função dos serviços do Apps Script.
- Configurar o ambiente.
- Configure o script.
- Execute o script.
Sobre este complemento do Google Workspace
Neste exemplo, você cria um complemento do Google Workspace que exibe links do Google Livros em um documento do Documentos Google. Quando você digita ou cola um URL do Google Livros em um documento, o complemento reconhece o link e aciona uma visualização dele. Para visualizar o link, você pode convertê-lo em um ícone inteligente e manter o ponteiro do mouse sobre ele para visualizar um cartão com mais informações sobre o livro.
Este complemento usa o serviço UrlFetch do Apps Script para se conectar à API Google Books e receber informações sobre o Google Livros para exibir nos Documentos Google.
Como funciona
No arquivo de manifesto do complemento
Google Workspace, o script configura
o complemento para ampliar os Documentos Google e acionar visualizações
de links para URLs que correspondam a determinados padrões do site do Google Livros
(https://books.google.com
).
No arquivo de código, o script se conecta à API Google Books e usa o URL para receber informações sobre o livro, que é uma instância do recurso Volume
. O
script usa essas informações para gerar um ícone inteligente que mostra o título
do livro e um card de visualização com um resumo, a contagem de páginas, uma imagem da
capa do livro e o número de classificações.
Serviços do Apps Script
Este complemento usa os seguintes serviços:
- UrlFetch Service: conecta-se à API Google Books para receber informações sobre livros (que são instâncias do recurso
Volume
da API). - Card Service: cria a interface do usuário do complemento.
Pré-requisitos
Para usar este exemplo, você precisa dos seguintes pré-requisitos:
- Uma Conta do Google (contas do Google Workspace podem exigir aprovação do administrador).
Um navegador da Web com acesso à Internet.
um projeto do Google Cloud com uma conta de faturamento associada. Consulte Ativar o faturamento de um projeto.
Configure seu ambiente
Nas seções a seguir, você configura o ambiente para criar o complemento.
Abrir o projeto do Cloud no console do Google Cloud
Se ele ainda não estiver aberto, abra o projeto do Cloud que você pretende usar para esta amostra:
- No console do Google Cloud, acesse a página Selecionar um projeto.
- Selecione o projeto do Google Cloud que você quer usar. Se preferir, clique em Criar projeto e siga as instruções na tela. Se você criar um projeto do Google Cloud, talvez seja necessário ativar o faturamento dele.
Ativar a API Google Books
Este complemento se conecta à API Google Books. Antes de usar as APIs do Google, você precisa ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.
No projeto do Cloud, ative a API Books.
Configurar a tela de permissão OAuth
Este complemento requer um projeto do Cloud com uma tela de permissão configurada. A configuração da tela de permissão OAuth define o que o Google exibe aos usuários e registra seu app para que você possa publicá-lo mais tarde.
- No console do Google Cloud, acesse Menu > APIs e serviços > Tela de permissão OAuth.
- Em Tipo de usuário, selecione Interno e clique em Criar.
- Preencha o formulário de registro do app e clique em Save and continue.
Por enquanto, ignore a adição de escopos e clique em Salvar e continuar. No futuro, ao criar um aplicativo para uso fora da sua organização do Google Workspace, você precisará alterar o Tipo de usuário para Externo e adicionar os escopos de autorização exigidos pelo aplicativo.
- Analise o resumo do registro do app. Para fazer mudanças, clique em Editar. Se o registro do app estiver OK, clique em Voltar para o painel.
Gerar uma chave de API para a API Google Books
- Acesse o Console do Google Cloud. Verifique se o projeto com faturamento ativado está aberto.
No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
Clique em Criar credenciais > Chave de API.
Anote sua chave de API para usar em uma etapa posterior.
Configurar o script
As seções a seguir configuram o script para criar o complemento.
Criar o projeto do Apps Script
- Clique no botão a seguir para abrir o projeto do Apps Script Visualizar links do Google Livros.
Abrir o projeto. - Clique em Overview.
- Na página de visão geral, clique em Fazer uma cópia.
- Na sua cópia do projeto do Apps Script, acesse o arquivo
Code.gs
e substituaYOUR_API_KEY
pela chave de API gerada na seção anterior.
Copie o número do projeto do Cloud
- No console do Google Cloud, acesse Menu > IAM e administrador > Configurações.
- No campo Número do projeto, copie o valor.
Definir o projeto do Cloud do projeto do Apps Script
- No seu projeto do Apps Script, clique em Configurações do projeto.
- Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
- Em Número do projeto do GCP, cole o número do projeto do Google Cloud.
- Clique em Configurar projeto.
Testar o complemento
As seções a seguir testam o complemento que você criou.
Instalar uma implantação de teste
- No seu projeto do Apps Script, clique em Editor.
- Substitua
YOUR_API_KEY
pela chave de API da API Google Books, criada em uma seção anterior. - Clique em Implantar > Testar implantações.
- Clique em Instalar > Concluído.
Visualizar um link no app Documentos Google
- Crie um documento Google em docs.new.
- Cole o URL abaixo no documento e pressione a tecla Tab para
converter o URL em um ícone inteligente:
https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
- Mantenha o ponteiro do mouse sobre o ícone inteligente e, quando solicitado, autorize o acesso para executar o complemento. O card de visualização mostra informações sobre o livro.
A imagem a seguir mostra a visualização do link:
Revisar o código
Para revisar o código do Apps Script para este complemento, clique em Ver código-fonte para expandir a seção: