Vorschaulinks aus Google Books mit Smartchips

Programmierkenntnisse: Mittelstufe
Dauer: 30 Minuten
Projekttyp: Google Workspace-Add-on

Ziele

  • Verstehen, was das Add-on tut.
  • Verstehen, wie ein Add-on mit Apps Script erstellt wird und wie die Apps Script-Dienste funktionieren.
  • Umgebung einrichten
  • Script einrichten
  • Script ausführen

Über dieses Google Workspace-Add-on

In diesem Beispiel erstellen Sie ein Google Workspace-Add-on, mit dem Sie eine Vorschau von Links aus Google Books in einem Google-Dokument ansehen können. Wenn Sie eine Google Books-URL in ein Dokument eingeben oder einfügen, erkennt das Add-on den Link und löst eine Linkvorschau aus. Um eine Vorschau des Links zu sehen, können Sie ihn in einen Smartchip umwandeln und den Mauszeiger auf den Link bewegen, um eine Karte mit weiteren Informationen zum Buch aufzurufen.

Dieses Add-on verwendet den UrlFetch-Dienst von Apps Script, um eine Verbindung zur Google Books API herzustellen und Informationen zu Google Books abzurufen, die in Google Docs angezeigt werden.

Funktionsweise

In der Manifestdatei des Google Workspace-Add-ons konfiguriert das Script das Add-on so, dass es Google Docs erweitert und Linkvorschauen für URLs auslöst, die bestimmten Mustern auf der Google Books-Website () entsprechen.https://books.google.com

In der Codedatei stellt das Script eine Verbindung zur Google Books API her und ruft mit der URL Informationen zum Buch ab (einer Instanz der Volume Ressource). Das Script verwendet diese Informationen, um einen Smartchip mit dem Titel des Buchs und eine Vorschaukarte mit einer Zusammenfassung, der Seitenzahl, einem Bild des Buchcovers und der Anzahl der Bewertungen zu generieren.

Apps Script-Dienste

Dieses Add-on verwendet die folgenden Dienste:

  • UrlFetch-Dienst: Stellt eine Verbindung zur Google Books API her, um Informationen zu Büchern abzurufen (Instanzen der Ressource Volume der API).
  • Card-Dienst: Erstellt die Benutzeroberfläche des Add-ons.

Vorbereitung

Für dieses Beispiel benötigen Sie Folgendes:

  • Ein Google-Konto (für Google Workspace-Konten ist möglicherweise die Genehmigung durch den Administrator erforderlich)

  • Einen Webbrowser mit Internetzugang

  • Ein Google Cloud-Projekt.

Umgebung einrichten

In den folgenden Abschnitten wird die Umgebung für die Erstellung des Add-ons eingerichtet.

Cloud-Projekt in der Google Cloud Console öffnen

Öffnen Sie das Cloud-Projekt, das Sie für dieses Beispiel verwenden möchten, falls es noch nicht geöffnet ist:

  1. Gehen Sie in der Google Cloud Console zur Seite Projekt auswählen.

    Cloud-Projekt auswählen

  2. Wählen Sie das Google Cloud-Projekt aus, das Sie verwenden möchten. Oder klicken Sie auf Projekt erstellen und folgen Sie der Anleitung auf dem Bildschirm. Wenn Sie ein Google Cloud-Projekt erstellen, müssen Sie möglicherweise die Abrechnung für das Projekt aktivieren.

Google Books API aktivieren

Dieses Add-on stellt eine Verbindung zur Google Books API her. Bevor Sie Google APIs verwenden können, müssen Sie sie in einem Google Cloud-Projekt aktivieren. Sie können eine oder mehrere APIs in einem einzelnen Google Cloud-Projekt aktivieren.

Für dieses Add-on ist ein Cloud-Projekt mit einem konfigurierten Zustimmungsbildschirm erforderlich. Wenn Sie den OAuth-Zustimmungsbildschirm konfigurieren, legen Sie fest, was Google den Nutzern anzeigt, und registrieren Ihre App, damit Sie sie später veröffentlichen können.

  1. Gehen Sie in der Google API Console zu „Menü“ > Google Auth Platform > Branding.

    Zum Branding

  2. Wenn Sie die Google Auth Platform bereits konfiguriert haben, können Sie die folgenden Einstellungen für den OAuth-Zustimmungsbildschirm unter Branding, Zielgruppe und Datenzugriff konfigurieren. Wenn die Meldung Google Auth Platform noch nicht konfiguriert angezeigt wird, klicken Sie auf Jetzt starten:
    1. Geben Sie unter App-Informationen in App-Name einen Namen für die App ein.
    2. Wählen Sie unter E‑Mail-Adresse für Nutzersupport eine E‑Mail-Adresse für den Support aus, über die Nutzer Sie kontaktieren können, wenn sie Fragen zu ihrer Einwilligung haben.
    3. Klicken Sie auf Weiter.
    4. Wählen Sie unter Zielgruppe die Option Intern aus.
    5. Klicken Sie auf Weiter.
    6. Geben Sie unter Kontaktinformationen eine E‑Mail-Adresse ein, über die Sie über Änderungen an Ihrem Projekt benachrichtigt werden können.
    7. Klicken Sie auf Weiter.
    8. Lesen Sie unter Fertigstellen die Richtlinie zu Nutzerdaten der Google API-Dienste und wählen Sie bei Zustimmung Ich stimme der Richtlinie zu Nutzerdaten der Google API-Dienste zu aus.
    9. Klicken Sie auf Weiter.
    10. Klicken Sie auf Erstellen.
  3. Das Hinzufügen von Bereichen können Sie vorerst überspringen. Wenn Sie in Zukunft eine App für die Verwendung außerhalb Ihrer Google Workspace-Organisation erstellen, müssen Sie den Nutzertyp in Extern ändern. Fügen Sie dann die Autorisierungsbereiche hinzu, die für Ihre App erforderlich sind. Weitere Informationen finden Sie im vollständigen Leitfaden zum Konfigurieren des OAuth-Zustimmungsbildschirms.

API-Schlüssel für die Google Books API abrufen

  1. Gehen Sie zur Google API Console. Achten Sie darauf, dass Ihr Projekt mit aktivierter Abrechnung geöffnet ist.

  2. Gehen Sie in der Google API Console zu „Menü“ > APIs und Dienste > Anmeldedaten.

    Zu den Anmeldedaten

  3. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.

  4. Notieren Sie sich den API-Schlüssel, da Sie ihn in einem späteren Schritt benötigen.

Script einrichten

In den folgenden Abschnitten wird das Script für die Erstellung des Add-ons eingerichtet.

Apps Script-Projekt erstellen

  1. Klicken Sie auf die folgende Schaltfläche, um das Apps Script-Projekt Vorschau von Links aus Google Books zu öffnen.
    Projekt öffnen
  2. Klicken Sie auf Übersicht.
  3. Klicken Sie auf der Übersichtsseite auf Symbol zum Erstellen einer Kopie Kopie erstellen.
  4. Gehen Sie in Ihrer Kopie des Apps Script-Projekts zur Datei Code.gs und ersetzen Sie YOUR_API_KEY durch den API-Schlüssel, den Sie im vorherigen Abschnitt generiert haben.

Wenn Sie in Zukunft bestimmte Google APIs verwenden oder Ihre App veröffentlichen möchten, müssen Sie Ihr Cloud-Projekt mit Ihrem Apps Script-Projekt verknüpfen. Für diesen Leitfaden ist das nicht erforderlich. Weitere Informationen finden Sie im Leitfaden zu Google Cloud-Projekten.

Add-on testen

In den folgenden Abschnitten wird das erstellte Add-on getestet.

Testbereitstellung installieren

  1. Klicken Sie in Ihrem Apps Script-Projekt auf Editor.
  2. Klicken Sie auf Bereitstellen > Testbereitstellungen.
  3. Klicken Sie auf Installieren > Fertig.
  1. Erstellen Sie unter docs.new ein Google-Dokument.
  2. Fügen Sie die folgende URL in das Dokument ein und drücken Sie die Tab-Taste, um die URL in einen Smartchip umzuwandeln: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. Bewegen Sie den Mauszeiger auf den Smartchip und autorisieren Sie den Zugriff, um das Add-on auszuführen, wenn Sie dazu aufgefordert werden. Auf der Vorschaukarte werden Informationen zum Buch angezeigt.

Die folgende Abbildung zeigt die Linkvorschau:

Eine Linkvorschau des Buchs „Software Engineering at Google“.

Code ansehen

Wenn Sie den Apps Script-Code für dieses Add-on ansehen möchten, klicken Sie auf Quellcode ansehen , um den Abschnitt zu maximieren:

Quellcode ansehen

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
/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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