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

• Entenda o que o complemento faz.
• Aprender a criar um complemento usando Apps Script e entenda o que ele e serviços do Google Cloud 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 exibe links de Google Livros em uma do app Documentos Google. Quando você digita ou cola um URL do Google Livros em um documento, o complemento reconhecerá e aciona uma visualização dele. Para visualizar o link, você pode converter o em um ícone inteligente e mantenha o ponteiro do mouse sobre o link para ver um cartão que exibe mais informações sobre o livro.

Este complemento usa serviço UrlFetch do Apps Script para conectar ao Google Livros a API e receber informações sobre o Google Livros para exibir no Google Docs.

Como funciona

No manifesto do Complemento do Google Workspace , o script configura o complemento para estender os Documentos Google e acionar o link visualizações de 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 obter informações sobre o livro (que é uma instância do Volume recurso). O usa essas informações para gerar um ícone inteligente que exibe o título e um card de visualização que mostra um resumo, o número de páginas, uma imagem do a capa do livro e o número de avaliações.

Serviços do Apps Script

Este complemento usa os seguintes serviços:

• UrlFetch Service: conecta-se ao Google Livros. API para obter informações sobre livros (que são instâncias das APIs recurso Volume).
• Card Service: cria o usuário. interface do complemento.

Pré-requisitos

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

• Uma Conta do Google (as contas do Google Workspace podem precisam da aprovação do administrador).

• Um navegador da Web com acesso à Internet.

• um projeto do Google Cloud; a uma conta de faturamento associada. Consulte Ativar faturamento para um projeto.

Configurar o ambiente

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

Abrir o projeto do Cloud no console do Google Cloud

Abra o projeto do Cloud que você pretende usar, caso ele ainda não esteja aberto. 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. 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.

  Ativar a API

Configurar a tela de permissão OAuth

Este complemento requer um projeto do Cloud com 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.

1. No console do Google Cloud, acesse o menu 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 Save and continue.

4. Por enquanto, ignore a adição de escopos e clique em Salvar e continuar. No futuro, quando você criar um aplicativo para usar fora de sua organização do Google Workspace, mude o Tipo de usuário para Externo. Em seguida, adicionar os escopos de autorização exigidos pelo app.

5. Analise o resumo do registro do app. Para fazer mudanças, clique em Editar. Se o app estiver tudo certo, 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 o menu 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

As seções a seguir definem o script para a criação da .

Criar o projeto do Apps Script

1. Clique no botão a seguir para abrir a página Visualizar links do Google Livros projeto do Apps Script.
   Abrir o projeto.
2. Clique em info_outline Overview.
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 Code.gs e substitua YOUR_API_KEY pela chave de API que você gerou no na seção anterior.

Copie o número do projeto do Cloud

1. No console do Google Cloud, acesse o menu menu > IAM e Administrador > Configurações.

   Acesse "IAM e Configurações de administrador

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

Definir o projeto do Cloud do projeto do Apps Script

1. No seu 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 seu projeto do Apps Script, clique em code Editor.
2. Substitua YOUR_API_KEY pela chave de API da API Google Books, criada em na seção anterior.
3. Clique em Implantar > Testar implantações.
4. Clique em Instalar > Concluído.

Visualizar um link no app Documentos Google

1. Crie um documento do Google Docs em docs.new.
2. Cole o seguinte URL no documento e pressione a tecla Tab para converta 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 a 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 isso complemento, clique em Visualizar código-fonte para expandir o seção:

{
  "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"
          }
        }
      ]
    }
  }
}

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