Visualizza l'anteprima dei link da Google Libri con smart chip

Livello di programmazione: intermedio
Durata: 30 minuti
Tipo di progetto: componente aggiuntivo di Google Workspace

Obiettivi

  • Scopri cosa fa il componente aggiuntivo.
  • Scopri come creare un componente aggiuntivo utilizzando Apps Script e comprendere cosa fanno i servizi Apps Script.
  • Configurare l'ambiente.
  • Configura lo script.
  • Esegui lo script.

Informazioni su questo componente aggiuntivo di Google Workspace

In questo esempio, creerai un componente aggiuntivo di Google Workspace che mostra in anteprima i link di Google Libri in un documento di Documenti Google. Quando digiti o incolli un URL di Google Libri in un documento, il componente aggiuntivo riconosce il link e attiva un'anteprima del link. Per visualizzare l'anteprima del link, puoi convertirlo in uno smart chip e passare il mouse sopra il link per visualizzare una scheda con maggiori informazioni sul libro.

Questo componente aggiuntivo utilizza il servizio UrlFetch di Apps Script per connettersi all'API Google Books e ottenere informazioni su Google Libri da visualizzare in Documenti Google.

Come funziona

Nel file manifest del componente aggiuntivo di Google Workspace, lo script configura il componente aggiuntivo in modo da estendere Documenti Google e attivare anteprime dei link per gli URL che corrispondono a determinati pattern del sito web di Google Libri (https://books.google.com).

Nel file di codice, lo script si connette all'API Google Books e utilizza l'URL per ottenere informazioni sul libro (che è un'istanza della risorsa Volume). Lo script utilizza queste informazioni per generare uno smart chip che mostri il titolo del libro e una scheda di anteprima che mostra un riassunto, il numero di pagine, un'immagine della copertina del libro e il numero di valutazioni.

Servizi Apps Script

Questo componente aggiuntivo utilizza i seguenti servizi:

Prerequisiti

Per utilizzare questo esempio, devi disporre dei seguenti prerequisiti:

configura l'ambiente

Apri il progetto Cloud nella console Google Cloud

Se non è già aperto, apri il progetto Cloud che intendi utilizzare per questo esempio:

  1. Nella console Google Cloud, vai alla pagina Seleziona un progetto.

    Seleziona un progetto Cloud

  2. Seleziona il progetto Google Cloud che vuoi utilizzare. In alternativa, fai clic su Crea progetto e segui le istruzioni sullo schermo. Se crei un progetto Google Cloud, potresti dover attivare la fatturazione per il progetto.

Attivare l'API Google Books

Questo componente aggiuntivo si collega all'API Google Books. Prima di utilizzare le API di Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

Questo componente aggiuntivo richiede un progetto Cloud con una schermata di consenso configurata. La configurazione della schermata per il consenso OAuth definisce ciò che Google mostra agli utenti e registra la tua app in modo che tu possa pubblicarla in un secondo momento.

  1. Nella console Google Cloud, vai a Menu > API e servizi > Schermata consenso OAuth.

    Vai alla schermata per il consenso OAuth

  2. In Tipo di utente, seleziona Interno e poi fai clic su Crea.
  3. Compila il modulo di registrazione dell'app, poi fai clic su Salva e continua.

  4. Per il momento, puoi saltare l'aggiunta di ambiti e fare clic su Salva e continua. In futuro, quando creerai un'app da utilizzare al di fuori della tua organizzazione Google Workspace, dovrai cambiare Tipo di utente in Esterno e poi aggiungere gli ambiti di autorizzazione richiesti dalla tua app.

  5. Rivedi il riepilogo della registrazione dell'app. Per apportare modifiche, fai clic su Modifica. Se la registrazione dell'app è corretta, fai clic su Torna alla dashboard.

Ottenere una chiave API per l'API Google Books

  1. Vai alla console Google Cloud. Assicurati che il progetto abilitato per la fatturazione sia aperto.

  2. Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.

    Vai a Credenziali

  3. Fai clic su Crea credenziali > Chiave API.

  4. Prendi nota della tua chiave API per utilizzarla in un passaggio successivo.

Configura lo script

Crea il progetto Apps Script

  1. Fai clic sul pulsante seguente per aprire il progetto Apps Script di Anteprima dei link del Google Libri.
    Apri il progetto
  2. Fai clic su Panoramica.
  3. Nella pagina Panoramica, fai clic su L'icona per creare una copia Crea una copia.
  4. Nella copia del progetto Apps Script, vai al file Code.gs e sostituisci YOUR_API_KEY con la chiave API generata nella sezione precedente.

Copia il numero di progetto Cloud

  1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Impostazioni.

    Vai a Impostazioni IAM e amministrazione

  2. Nel campo Numero progetto, copia il valore.

Imposta il progetto Cloud del progetto Apps Script

  1. Nel progetto Apps Script, fai clic su Icona delle impostazioni progetto Impostazioni progetto.
  2. In Progetto Google Cloud Platform (GCP), fai clic su Cambia progetto.
  3. In Numero di progetto Google Cloud, incolla il numero di progetto Google Cloud.
  4. Fai clic su Imposta progetto.

Testa il componente aggiuntivo

Installa un deployment di prova

  1. Nel progetto Apps Script, fai clic su Editor.
  2. Apri il file Code.gs e fai clic su Esegui. Quando richiesto, autorizza lo script.
  3. Fai clic su Esegui il deployment > Testa i deployment.
  4. Fai clic su Installa > Fine.
  1. Crea un documento di Documenti Google all'indirizzo docs.new.
  2. Incolla il seguente URL nel documento e premi il tasto Tab per convertire l'URL in uno smart chip: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. Tieni il puntatore sopra lo smart chip e, quando richiesto, autorizza l'accesso per eseguire il componente aggiuntivo. La scheda di anteprima mostra informazioni sul libro.

La seguente immagine mostra l'anteprima del link:

Un'anteprima link del libro, Software Engineering di Google.

Rivedi il codice

Per esaminare il codice di Apps Script di questo componente aggiuntivo, fai clic su Visualizza codice sorgente di seguito:

Visualizza codice sorgente

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

Passaggi successivi