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

  • Capire la funzione del componente aggiuntivo.
  • Capire come creare un componente aggiuntivo utilizzando Apps Script e comprendere che cosa dei servizi Google.
  • Configurare l'ambiente.
  • Configura lo script.
  • Esegui lo script.

Informazioni su questo componente aggiuntivo di Google Workspace

In questo esempio, crei un componente aggiuntivo di Google Workspace che mostra l'anteprima dei link da Google Libri in un Documento di Documenti Google. Quando digiti o incolli un URL di Google Libri in una documento, il componente aggiuntivo riconosce del link e attiva l'anteprima del link. Per visualizzare l'anteprima del link, puoi convertire il collegarsi a uno smart chip e tenere premuto il puntatore sopra il link per visualizzare una scheda mostra ulteriori informazioni sul libro.

Questo componente aggiuntivo utilizza dal servizio UrlFetch di Apps Script a collegati al Google Libri API e ottenere informazioni su Google Libri da visualizzare in Documenti Google.

Come funziona

Nel file manifest del componente aggiuntivo di Google Workspace file, lo script configura il componente aggiuntivo per estendere Documenti Google e attivare il link anteprime per URL che corrispondono a determinati pattern dal 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 del Volume risorsa). La usa queste informazioni per generare uno smart chip che mostra la titolo e una scheda di anteprima che mostra un riepilogo, il conteggio delle pagine, un'immagine la copertina del libro e il numero di valutazioni.

Servizi Apps Script

Questo componente aggiuntivo utilizza i seguenti servizi:

  • Servizio UrlFetch: si collega a Google Libri API per ottenere informazioni sui libri (ovvero istanze delle API Volumerisorsa).
  • Card Service (Servizio carta): crea l'utente l'interfaccia del componente aggiuntivo.

Prerequisiti

Per utilizzare questo esempio, sono necessari i seguenti prerequisiti:

Configura l'ambiente

Nelle sezioni seguenti è possibile configurare l'ambiente per lo sviluppo come componente aggiuntivo.

Apri il tuo 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, potrebbe essere necessario attivare la fatturazione per il progetto.

Attivare l'API Google Books

Questo componente aggiuntivo si connette 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 un schermata per il consenso configurata. La configurazione della schermata per il consenso OAuth definisce 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 al Menu > API e Servizi > Schermata consenso OAuth.

    Vai alla schermata per il consenso OAuth

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

  4. Per ora, puoi saltare l'aggiunta di ambiti e fare clic su Salva e continua. In futuro, quando creerai un'app da utilizzare al di fuori del tuo Nell'organizzazione Google Workspace, devi modificare il Tipo di utente in Esterno e poi aggiungi gli ambiti di autorizzazione richiesti dalla tua app.

  5. Esamina il riepilogo della registrazione dell'app. Per apportare modifiche, fai clic su Modifica. Se l'app la registrazione sembra a posto, 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 al Menu > API e Servizi > Credenziali.

    Vai a credenziali

  3. Fai clic su Crea credenziali > Chiave API.

  4. Prendi nota della tua chiave API da utilizzare in un passaggio successivo.

Configurare lo script

Le sezioni seguenti consentono di impostare lo script per la creazione dell'elemento come componente aggiuntivo.

Creare il progetto Apps Script

  1. Fai clic sul seguente pulsante per aprire i Link di anteprima da Google Libri progetto Apps Script.
    Apri il progetto
  2. Fai clic su Panoramica.
  3. Nella pagina Panoramica, fai clic su Icona per creare una copia Crea una copia.
  4. Nella tua copia del progetto Apps Script, vai a Code.gs e sostituisci YOUR_API_KEY con la chiave API generata nell' sezione precedente.

Copia il numero del progetto Cloud

  1. Nella console Google Cloud, vai al Menu > IAM e Amministratore > Impostazioni.

    Vai a Impostazioni IAM e amministrazione

  2. Copia il valore nel campo Numero progetto.

Impostare il progetto Cloud del progetto Apps Script

  1. Nel tuo progetto Apps Script, fai clic su Icona delle impostazioni progetto Impostazioni progetto.
  2. In Progetto Google Cloud Platform (Google Cloud), 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

Le seguenti sezioni testano il componente aggiuntivo che hai creato.

Installa un deployment di prova

  1. Nel progetto Apps Script fai clic su Editor.
  2. Sostituisci YOUR_API_KEY con la chiave API per l'API Google Books, creata in una sezione precedente.
  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 al documento e premi il tasto Tab per converti 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 a il componente aggiuntivo. Viene visualizzata la scheda di anteprima informazioni sul libro.

La seguente immagine mostra l'anteprima del link:

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

Esamina il codice

Per esaminare il codice di Apps Script fai clic su Visualizza codice sorgente per espandere la sezione:

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