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

Livello di codifica: 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 comprendi cosa fanno i servizi di Apps Script.
• 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 di Google Libri in un documento Documenti Google. Quando digiti o incolli un URL di Google Libri in un documento, il componente aggiuntivo lo riconosce e attiva un'anteprima del link. Per visualizzare l'anteprima del link, puoi convertirlo in uno smart chip e tenere premuto il cursore sopra il link per visualizzare una scheda che mostra ulteriori informazioni sul libro.

Questo componente aggiuntivo utilizza il servizio UrlFetch di Apps Script per connettersi all'API Google Libri e recuperare le 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 per estendere Documenti Google e attivare le 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 Libri e utilizza l'URL per recuperare informazioni sul libro (che è un'istanza della Volume risorsa). Lo script utilizza queste informazioni per generare uno smart chip che mostra il titolo del libro e una scheda di anteprima che mostra un riepilogo, 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:

• Servizio UrlFetch: si connette all'API Google Libri per recuperare informazioni sui libri (che sono istanze della risorsa Volume delle API).
• Card Service: crea l'interfaccia dell'utente del componente aggiuntivo.

Prerequisiti

Per utilizzare questo esempio, sono necessari i seguenti prerequisiti:

• Un Account Google (gli account Google Workspace potrebbero richiedere l'approvazione dell'amministratore).

• Un browser web con accesso a internet.

• Un progetto Google Cloud con un account di fatturazione associato. Consulta la sezione Abilitare la fatturazione per un progetto.

Configura l'ambiente

Le sezioni seguenti configurano l'ambiente per la creazione del plug-in.

Aprire 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 Libri

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

• Nel progetto Cloud, attiva l'API Books.

  Attiva l'API

Configura la schermata per il consenso OAuth

Questo componente aggiuntivo richiede un progetto Cloud con una schermata per il consenso configurata. La configurazione della schermata per il consenso OAuth definisce cosa viene mostrato agli utenti da Google e registra la tua app in modo da poterla pubblicare in un secondo momento.

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

   Vai alla schermata per il consenso OAuth

2. In Tipo di utente, seleziona Interno e poi fai clic su Crea.
3. Completa 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 crei un'app da utilizzare al di fuori della tua organizzazione Google Workspace, devi modificare il Tipo di utente in Esterno, quindi 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 sembra corretta, fai clic su Torna alla dashboard.

Ottenere una chiave API per l'API Google Libri

1. Vai alla console Google Cloud. Assicurati che il progetto con la fatturazione attiva 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 chiave API da utilizzare in un passaggio successivo.

Configurare lo script

Le sezioni seguenti configurano lo script per la creazione del plug-in.

Crea il progetto Apps Script

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

Copia il numero del 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 Impostazioni progetto.
2. In Progetto Google Cloud (Google Cloud), fai clic su Cambia progetto.
3. In Numero progetto Google Cloud, incolla il numero del progetto Google Cloud.
4. Fai clic su Imposta progetto.

Testare il componente aggiuntivo

Le sezioni seguenti testano il componente aggiuntivo che hai creato.

Installare 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 di Google Libri, creata in una sezione precedente.
3. Fai clic su Esegui il deployment > Testa i deployment.
4. Fai clic su Installa > Fine.

Visualizzare l'anteprima di un link in Documenti Google

1. Crea un documento Documenti Google su 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 premuto il cursore sopra lo smart chip e, quando richiesto, autorizza l'accesso per eseguire il componente aggiuntivo. La scheda di anteprima mostra informazioni sul libro.

L'immagine seguente mostra l'anteprima del link:

Esamina il codice

Per esaminare il codice di Apps Script di questo plug-in, fai clic su Visualizza codice sorgente per espandere la sezione:

Visualizza codice sorgente

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

Visualizza su GitHub

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

Visualizza su GitHub

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

Argomenti correlati

• Visualizzare l'anteprima dei link con gli smart chip
• Documentazione di riferimento dell'API Google Libri