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.
  • Entender como criar um complemento usando o Apps Script e o que os serviços do Apps Script fazem.
  • Preparar o ambiente.
  • Configurar o script.
  • Executar 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 Google Docs. Ao digitar ou colar um URL do Google Books em um documento, o complemento reconhece o link e aciona uma prévia. Para visualizar o link, você pode convertê-lo em um ícone inteligente e manter o ponteiro 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 Livros e receber informações sobre o Google Livros para mostrar no Google Docs.

Como funciona

No arquivo de manifesto do complemento do Google Workspace, o script configura o complemento para estender o Google Docs e acionar prévias 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 Livros e usa o URL para receber informações sobre o livro (que é uma instância do Volume recurso). O script usa essas informações para gerar um ícone inteligente que mostra o título do livro e um card de prévia que mostra um resumo, a contagem de páginas, uma imagem da capa do livro e o número de avaliações.

Serviços do Apps Script

Esse complemento usa os seguintes serviços:

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.

Preparar o ambiente

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

Abrir o projeto na nuvem no console do Google Cloud

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

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

    Selecionar um projeto na nuvem

  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 para ele.

Ativar a API Google Livros

Esse complemento se conecta à API Google Livros. Antes de usar as APIs do Google, você precisa ativá-las em um projeto na nuvem do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

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

  1. No Console de APIs do Google, acesse Menu > Plataforma de autenticação do Google > Branding.

    Acessar o branding

  2. Se você já configurou a plataforma de autenticação do Google, pode configurar as seguintes configurações da tela de permissão OAuth em Branding, Público e Acesso a dados. Se você vir uma mensagem informando que a plataforma de autenticação do Google ainda não está configurada, clique em Começar:
    1. Em Informações do app, em Nome do app, insira um nome para o app.
    2. Em E-mail para suporte do usuário, escolha um endereço de e-mail de suporte para que os usuários possam entrar em contato com você se tiverem dúvidas sobre o consentimento.
    3. Clique em Próxima.
    4. Em Público, selecione Interno.
    5. Clique em Próxima.
    6. Em Informações de contato, insira um endereço de e-mail para receber notificações sobre mudanças no seu projeto.
    7. Clique em Próxima.
    8. Em Concluir, revise a Política de dados do usuário dos serviços de API do Google e, se concordar, selecione Concordo com a Política de dados do usuário dos serviços de API do Google.
    9. Clique em Continuar.
    10. Clique em Criar.
  3. Por enquanto, você pode pular a adição de escopos. No futuro, ao criar um app para uso fora da sua organização do Google Workspace, você precisará mudar o Tipo de usuário para Externo. Em seguida, adicione os escopos de autorização necessários para o app. Para saber mais, consulte o guia completo Configurar a tela de permissão OAuth guide.

Gerar uma chave de API para a API Google Livros

  1. Vá para o Console de APIs do Google. Verifique se o projeto ativado para faturamento está aberto.

  2. No Console de APIs do Google, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  3. Clique em Criar credenciais > Chave de API.

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

  1. Clique no botão a seguir para abrir o projeto do Apps Script Visualizar links do Google Livros.
    Abrir o projeto
  2. Clique em Visão geral.
  3. Na página de visão geral, clique em O í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 gerada na seção anterior.

No futuro, se você quiser usar determinadas APIs do Google ou publicar seu app, será necessário associar seu projeto na nuvem ao projeto do Apps Script. Para este guia, não é necessário fazer isso. Para saber mais, consulte o guia Projetos do Google Cloud.

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. Clique em Implantar > Implantações de teste.
  3. Clique em Instalar > Concluído.
  1. Crie um documento do Google Docs em docs.new.
  2. Cole o URL a seguir 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 sobre o ícone inteligente e, quando solicitado, autorize o acesso para executar o complemento. O card de prévia mostra informações sobre o livro.

A imagem a seguir mostra a prévia do link:

Uma visualização do link do livro "Engenharia de software no Google".

Revisar o código

Para revisar o código do Apps Script desse complemento, clique em Acessar o código-fonte para expandir a seção:

Acessar 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
/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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();
  }
}