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 componenti aggiuntivi utilizzando Apps Script e 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, 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 un documento, il componente aggiuntivo riconosce il link e ne attiva l'anteprima. Per visualizzare l'anteprima del link, puoi convertire il link in uno smart chip e tenere premuto il puntatore sul 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 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 per estendere Documenti Google e attivare le anteprime dei link per gli 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 Libri 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 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 ottenere informazioni sui libri (che sono istanze della risorsa Volume dell'API).
• Card Service: crea l'interfaccia utente del componente aggiuntivo.

Prerequisiti

Per utilizzare questo esempio, sono necessari i seguenti prerequisiti:

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

• Un browser web con accesso a internet.

• Un progetto Google Cloud con un account di fatturazione associato. Fai riferimento ad Abilitare la fatturazione per un progetto.

Configura l'ambiente

Le sezioni seguenti configurano l'ambiente per la creazione del 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.

• Nel tuo progetto Cloud, attiva l'API Books.

  Attiva l'API

Configurare la schermata per il consenso OAuth

Questo componente aggiuntivo richiede un progetto Cloud con una schermata di consenso configurata. La configurazione della schermata per il consenso OAuth definisce cosa 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, 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 della tua organizzazione Google Workspace, dovrai cambiare il Tipo di utente in Esterno e poi aggiungere gli ambiti di autorizzazione richiesti dall'app.

5. Esamina il riepilogo della registrazione dell'app. Per apportare modifiche, fai clic su Modifica. Se la registrazione dell'app è 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 a 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 seguenti sezioni consentono di impostare lo script per la creazione del componente aggiuntivo.

Creare il progetto Apps Script

1. Fai clic sul pulsante seguente per aprire il progetto Apps Script Anteprima 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 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. Copia il valore nel campo Numero progetto.

Impostare il progetto Cloud del progetto Apps Script

1. Nel progetto Apps Script, fai clic su 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.

Visualizzare l'anteprima di un link in Documenti Google

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:

Esamina il codice

Per esaminare il codice di Apps Script per questo componente aggiuntivo, 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 smart chip
• Documentazione di riferimento dell'API Google Books