Visualizar links do Google Livros com ícones inteligentes

Nível de codificação: intermediário
Duração: 30 minutos
Tipo de projeto: complemento do Google Workspace

Objetivos

• Entenda o que o complemento faz.
• Entenda como criar um complemento usando o Apps Script e saiba o que os serviços do Apps Script fazem.
• Prepare o ambiente.
• Configure o script.
• Execute o script.

Sobre este complemento do Google Workspace

Neste exemplo, você cria um complemento do Google Workspace que mostra uma prévia de 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 conferir uma prévia do link, converta-o em um ícone inteligente e mantenha o ponteiro do mouse sobre ele para ver um card com mais informações sobre o livro.

Esse complemento usa o Serviço UrlFetch do Apps Script para se conectar à API Google Books e receber informações sobre o Google Books para exibição no Google Docs.

Como funciona

No arquivo de manifesto do complemento do Google Workspace, o script configura o complemento para estender o Documentos Google e acionar visualizações de links para URLs que correspondem 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 que mostra 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:

• Serviço UrlFetch: se conecta à API Google Books para receber informações sobre livros (que são instâncias do recurso Volume das APIs).
• Serviço de cartão: cria a interface do usuário do complemento.

Pré-requisitos

Para usar este exemplo, você precisa dos seguintes pré-requisitos:

• Uma Conta do Google (as contas do Google Workspace podem exigir a 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.

Configurar o ambiente

As seções a seguir configuram seu ambiente para criar o complemento.

Abra seu projeto do Cloud no console do Google Cloud

Se ainda não estiver aberto, abra o projeto do Cloud que você pretende usar para este exemplo:

1. No console do Google Cloud, acesse a página Selecionar um projeto.

   Selecionar um projeto do Cloud

2. Selecione o projeto do Google Cloud que você quer usar. Ou 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

Esse 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 seu projeto do Cloud, ative a API Books.

  Ativar a API

Configurar a tela de permissão OAuth

Esse complemento exige um projeto do Cloud com uma tela de consentimento configurada. A configuração da tela de consentimento do OAuth define o que o Google mostra aos usuários e registra o app para que você possa publicá-lo mais tarde.

1. No console do Google Cloud, acesse Menu > APIs e serviços > Tela de consentimento do OAuth.

   Acessar a tela de permissão OAuth

2. Em Tipo de usuário, selecione Interno e clique em Criar.
3. Preencha o formulário de registro do app e clique em Salvar e continuar.

4. Por enquanto, você pode pular a adição de escopos e clicar em Salvar e continuar. No futuro, quando você criar um app para uso fora da sua organização do Google Workspace, será necessário mudar o Tipo de usuário para Externo e, em seguida, adicionar os escopos de autorização necessários para o app.

5. Analise o resumo do registro do app. Para fazer alterações, clique em Editar. Se o registro do app estiver correto, clique em Voltar ao painel.

Receber uma chave de API para a API Google Books

1. Acesse o Console do Google Cloud. Verifique se o projeto com faturamento ativado está aberto.

2. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

   Ir para Credenciais

3. Clique em Criar credenciais > Chave de API.

4. Anote a chave da 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

1. Clique no botão a seguir para abrir o projeto do Apps Script Preview links from Google Books.
   Abrir o projeto
2. Clique em Visão geral.
3. Na página de visão geral, clique em Fazer uma cópia.
4. Na sua cópia do projeto do Apps Script, acesse o arquivo Code.gs e substitua YOUR_API_KEY pela chave de API gerada na seção anterior.

Copiar o número do projeto do Cloud

1. No console do Google Cloud, acesse Menu > IAM e administrador > Configurações.

   Acessar as configurações de IAM e administrador

2. No campo Número do projeto, copie o valor.

Definir o projeto do Apps Script no Cloud

1. No projeto do Apps Script, clique em Configurações do projeto.
2. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
3. Em Número do projeto do GCP, cole o número do projeto do Google Cloud.
4. Clique em Configurar projeto.

Testar o complemento

As seções a seguir testam o complemento que você criou.

Instalar uma implantação de teste

1. No projeto do Apps Script, clique em Editor.
2. Substitua YOUR_API_KEY pela chave da API Google Books criada em uma seção anterior.
3. Clique em Implantar > Testar implantações.
4. Clique em Instalar > Concluído.

Visualizar um link nos Documentos Google

1. Crie um documento do Documentos Google em docs.new.
2. Cole o seguinte URL 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
3. Mantenha o cursor 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 abaixo mostra a visualização do link:

Revisar o código

Para revisar o código do Apps Script desse complemento, clique em View source code para expandir a seção:

Acessar o código-fonte

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

Ver no GitHub

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "urlFetchWhitelist": [
    "https://www.googleapis.com/books/v1/volumes/"
  ],
  "addOns": {
    "common": {
      "name": "Preview Books Add-on",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/library-icon.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [
        {
          "runFunction": "bookLinkPreview",
          "patterns": [
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books"
            },
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books/edition"
            }
          ],
          "labelText": "Book",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/book-icon.png",
          "localizedLabelText": {
            "es": "Libros"
          }
        }
      ]
    }
  }
}

Code.gs

solutions/add-on/book-smartchip/Code.js

Ver no GitHub

function getBook(id) {
  const apiKey = 'YOUR_API_KEY'; // Replace with your API key
  const apiEndpoint = `https://www.googleapis.com/books/v1/volumes/${id}?key=${apiKey}&country=US`;
  const response = UrlFetchApp.fetch(apiEndpoint);
  return JSON.parse(response);
}

function bookLinkPreview(event) {
 if (event.docs.matchedUrl.url) {
    const segments = event.docs.matchedUrl.url.split('/');
    const volumeID = segments[segments.length - 1];

    const bookData = getBook(volumeID);
    const bookTitle = bookData.volumeInfo.title;
    const bookDescription = bookData.volumeInfo.description;
    const bookImage = bookData.volumeInfo.imageLinks.small;
    const bookAuthors = bookData.volumeInfo.authors;
    const bookPageCount = bookData.volumeInfo.pageCount;

    const previewHeader = CardService.newCardHeader()
      .setSubtitle('By ' + bookAuthors)
      .setTitle(bookTitle);

    const previewPages = CardService.newDecoratedText()
      .setTopLabel('Page count')
      .setText(bookPageCount);

    const previewDescription = CardService.newDecoratedText()
      .setTopLabel('About this book')
      .setText(bookDescription).setWrapText(true);

    const previewImage = CardService.newImage()
      .setAltText('Image of book cover')
      .setImageUrl(bookImage);

    const buttonBook = CardService.newTextButton()
      .setText('View book')
      .setOpenLink(CardService.newOpenLink()
        .setUrl(event.docs.matchedUrl.url));

    const cardSectionBook = CardService.newCardSection()
      .addWidget(previewImage)
      .addWidget(previewPages)
      .addWidget(CardService.newDivider())
      .addWidget(previewDescription)
      .addWidget(buttonBook);

    return CardService.newCardBuilder()
    .setHeader(previewHeader)
    .addSection(cardSectionBook)
    .build();
  }
}

Temas relacionados

• Visualizar links com ícones inteligentes
• Documentação de referência da API Google Books