Visualizar links do Google Livros com ícones inteligentes

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

Objetivos

  • Entender o que o complemento faz.
  • Aprenda a criar um complemento usando o Apps Script e entenda o que os serviços do Apps Script fazem.
  • 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 visualiza 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, converta o link em um ícone inteligente e passe o cursor sobre o link 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 Livros para mostrar nos Documentos Google.

Como funciona

No arquivo de manifesto do complemento do Google Workspace, o script configura o complemento para estender os 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 exibe o título do livro e um card de visualização que mostra um resumo, o número de páginas, uma imagem da capa do livro e o número de avaliações.

Serviços do Apps Script

Este complemento usa os seguintes serviços:

Pré-requisitos

Para usar essa amostra, você precisa dos seguintes pré-requisitos:

configurar o ambiente

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 esta amostra:

  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

Este complemento se conecta à API Google Books. Antes de usar as APIs do Google, é preciso ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

Este complemento requer um projeto do Cloud com uma tela de consentimento 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 depois.

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Tela de permissão 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, é possível 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 alterar o Tipo de usuário para Externo e, em seguida, adicionar os escopos de autorização exigidos pelo app.

  5. Analise o resumo de registro do seu app. Para fazer mudanças, clique em Editar. Se o registro do app estiver correto, clique em Voltar para o painel.

Gerar 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 sua chave de API para usar em uma etapa posterior.

Configurar o script

Criar o projeto do Apps Script

  1. Clique no botão a seguir para abrir o projeto Preview links from Google Books no Apps Script.
    Abrir o projeto
  2. Clique em Visão geral.
  3. Na página de visão geral, clique em Ícone para fazer uma cópia 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 que você gerou na seção anterior.

Copie 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 Cloud do projeto do Apps Script

  1. No projeto do Apps Script, clique em O ícone das configurações do projeto 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

Instalar uma implantação de teste

  1. No seu projeto do Apps Script, clique em Editor.
  2. Abra o arquivo Code.gs e clique em Run. Quando solicitado, autorize o script.
  3. Clique em Implantar > Testar implantações.
  4. Clique em Instalar > Concluído.
  1. Crie um arquivo do Documentos Google em docs.new.
  2. 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
  3. 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:

Uma visualização do link do livro "Software Engineering at Google".

Revisar o código

Para analisar o código do Apps Script para este complemento, clique em Ver código-fonte abaixo:

Ver o código-fonte

appsscript.json

solutions/add-on/book-smartchip/appsscript.json
{
  "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
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();
  }
}

Próximas etapas