Vorschaulinks aus Google Books mit Smartchips

Codierungslevel: Mittel
Dauer: 30 Minuten
Projekttyp: Google Workspace-Add-on

Lernziele

• Informieren Sie sich über die Funktionsweise des Add-ons.
• Informationen zum Erstellen eines Add-ons mit Apps Script und zu den Funktionen der Apps Script-Dienste.
• die Umgebung einrichten
• Richten Sie das Script ein.
• Führen Sie das Skript aus.

Dieses Google Workspace-Add-on

In diesem Beispiel erstellen Sie ein Google Workspace-Add-on, das in einem Google Docs-Dokument eine Vorschau von Links aus Google Books anzeigt. 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. Wenn Sie eine Vorschau des Links aufrufen möchten, können Sie ihn in einen Smartchip umwandeln. Bewegen Sie den Mauszeiger dann auf den Link, 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 sollen.

Funktionsweise

In der Manifestdatei des Google Workspace-Add-ons konfiguriert das Script das Add-on, um Google Docs zu erweitern und Linkvorschauen für URLs auszulösen, die bestimmten Mustern von der Google Books-Website entsprechen (https://books.google.com).

In der Codedatei stellt das Script eine Verbindung zur Google Books API her und ruft über die URL Informationen zum Buch ab, das eine Instanz der Volume-Ressource ist. Anhand dieser Informationen generiert das Script einen Smartchip mit dem Titel des Buches und einer Vorschaukarte mit einer Zusammenfassung, der Seitenzahl, einem Bild des Buchcovers und der Anzahl der Bewertungen.

Apps Script-Dienste

Für dieses Add-on werden die folgenden Dienste verwendet:

• UrlFetch-Dienst: Stellt eine Verbindung zur Google Books API her, um Informationen zu Büchern abzurufen (dies sind Instanzen der Volume-Ressource der APIs).
• Kartendienst: Hiermit wird die Benutzeroberfläche des Add-ons erstellt.

Vorbereitung

Für die Verwendung dieses Beispiels sind die folgenden Voraussetzungen erforderlich:

• Ein Google-Konto (für Google Workspace-Konten ist möglicherweise die Administratorzustimmung erforderlich).

• Einen Webbrowser mit Internetzugriff.

• Ein Google Cloud-Projekt mit einem verknüpften Abrechnungskonto. Weitere Informationen finden Sie unter Abrechnung für ein Projekt aktivieren.

Umgebung einrichten

In den folgenden Abschnitten richten Sie Ihre Umgebung für die Erstellung des Add-ons ein.

Cloud-Projekt in der Google Cloud Console öffnen

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

1. Rufen Sie in der Google Cloud Console die Seite Projekt auswählen auf.

   Cloud-Projekt auswählen

2. Wählen Sie das Google Cloud-Projekt aus, das Sie verwenden möchten. Sie können auch auf Projekt erstellen klicken und der Anleitung auf dem Bildschirm folgen. 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.

• Aktivieren Sie in Ihrem Cloud-Projekt die Books API.

  API aktivieren

OAuth-Zustimmungsbildschirm konfigurieren

Für dieses Add-on ist ein Cloud-Projekt mit einem konfigurierten Einwilligungsbildschirm erforderlich. Mit der Konfiguration des OAuth-Zustimmungsbildschirms legen Sie fest, was Google Nutzern anzeigt, und registrieren Ihre App, damit Sie sie später veröffentlichen können.

1. Klicken Sie in der Google Cloud Console auf das Dreistrich-Menü  > APIs und Dienste > OAuth-Zustimmungsbildschirm.

   Zum OAuth-Zustimmungsbildschirm

2. Wählen Sie unter Nutzertyp die Option Intern aus und klicken Sie dann auf Erstellen.
3. Füllen Sie das Formular zur App-Registrierung aus und klicken Sie dann auf Speichern und fortfahren.

4. Sie können das Hinzufügen von Bereichen vorerst überspringen und auf Speichern und fortfahren klicken. 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 und dann die erforderlichen Autorisierungsbereiche hinzufügen.

5. Überprüfen Sie die Zusammenfassung der App-Registrierung. Wenn Sie Änderungen vornehmen möchten, klicken Sie auf Bearbeiten. Wenn die App-Registrierung korrekt ist, klicken Sie auf Zurück zum Dashboard.

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

1. Öffnen Sie die Google Cloud Console. Das Projekt, für das die Abrechnung aktiviert ist, muss geöffnet sein.

2. Gehen Sie in der Google Cloud 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 zum Erstellen des Add-ons eingerichtet.

Apps Script-Projekt erstellen

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

Cloud-Projektnummer kopieren

1. Klicken Sie in der Google Cloud Console auf das Dreipunkt-Menü  > IAM und Verwaltung > Einstellungen.

   Weiter zur Seite „IAM & Verwaltung“

2. Kopieren Sie den Wert aus dem Feld Projektnummer.

Cloud-Projekt des Apps Script-Projekts festlegen

1. Klicken Sie in Ihrem Apps Script-Projekt auf  Projekteinstellungen.
2. Klicken Sie unter Google Cloud Platform-Projekt (GCP-Projekt) auf Projekt ändern.
3. Fügen Sie unter GCP-Projektnummer die Google Cloud-Projektnummer ein.
4. Klicken Sie auf Projekt festlegen.

Add-on testen

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

Testbereitstellung installieren

1. Klicken Sie in Ihrem Apps Script-Projekt auf  Editor.
2. Ersetzen Sie YOUR_API_KEY durch den API-Schlüssel für die Google Books API, den Sie in einem vorherigen Abschnitt erstellt haben.
3. Klicken Sie auf Bereitstellen > Bereitstellungen testen.
4. Klicken Sie auf Installieren > Fertig.

Vorschau eines Links in Google Docs ansehen

1. Erstellen Sie ein Google Docs-Dokument unter docs.new.
2. Fügen Sie die folgende URL in das Dokument ein und drücken Sie die Tabulatortaste, 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. Auf der Vorschaukarte sind Informationen zum Buch zu sehen.

Die folgende Abbildung zeigt die Linkvorschau:

Code ansehen

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

Quellcode ansehen

appsscript.json

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

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Weitere Informationen

• Vorschaulinks mit Smartchips
• Referenzdokumentation zur Google Books API