Vorschaulinks aus Google Books mit Smartchips

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

Zielsetzungen

• Informieren Sie sich über die Funktion des Add-ons.
• Hier erfahren Sie, wie Sie ein Add-on mit Apps Script erstellen und was die Apps Script-Dienste bewirken.
• die Umgebung einrichten
• Richten Sie das Skript ein.
• Führen Sie das Skript aus.

Informationen zu diesem Google Workspace-Add-on

In diesem Beispiel erstellen Sie ein Google Workspace-Add-on, das Links aus Google Books in einem Google Docs-Dokument als Vorschau 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. Um eine Vorschau des Links anzuzeigen, kannst du den Link in einen Smartchip umwandeln und den Mauszeiger über den Link bewegen. Daraufhin wird eine Karte mit weiteren Informationen zum Buch angezeigt.

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 wird das Add-on so konfiguriert, dass Google Docs erweitert wird und eine Linkvorschau für URLs ausgelöst wird, die bestimmten Mustern von der Google Books-Website (https://books.google.com) entsprechen.

In der Codedatei stellt das Skript eine Verbindung zur Google Books API her und ruft über die URL Informationen zum Buch ab. Dabei handelt es sich um eine Instanz der Ressource Volume. Anhand dieser Informationen generiert das Skript einen Smartchip, auf dem der Titel des Buchs und eine Vorschaukarte mit einer Zusammenfassung, der Seitenzahl, einem Bild des Buchcovers und der Anzahl der Bewertungen angezeigt werden.

Apps Script-Dienste

Dieses Add-on verwendet die folgenden Dienste:

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

Voraussetzungen

Damit Sie dieses Beispiel verwenden können, müssen folgende Voraussetzungen erfüllt sein:

• Ein Google-Konto (Google Workspace-Konten erfordern möglicherweise die Genehmigung eines Administrators).

• Ein Webbrowser mit Zugriff auf das Internet.

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

Umgebung einrichten

In den folgenden Abschnitten wird Ihre Umgebung zum Erstellen des Add-ons eingerichtet.

Cloud-Projekt in der Google Cloud Console öffnen

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

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. 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.

Die 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 Zustimmungsbildschirm erforderlich. Durch die Konfiguration des OAuth-Zustimmungsbildschirms wird festgelegt, was Google den Nutzern anzeigt, und deine App registriert, damit du sie später veröffentlichen kannst.

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

   Zum OAuth-Zustimmungsbildschirm

2. Wählen Sie für Nutzertyp die Option Intern aus und klicken Sie dann auf Erstellen.
3. Füllen Sie das App-Registrierungsformular aus und klicken Sie dann auf Speichern und fortfahren.

4. Vorerst können Sie das Hinzufügen von Bereichen überspringen und auf Speichern und fortfahren klicken. Wenn Sie in Zukunft eine Anwendung zur Verwendung außerhalb Ihrer Google Workspace-Organisation erstellen, müssen Sie den Nutzertyp in Extern ändern und dann die Autorisierungsbereiche hinzufügen, die Ihre Anwendung benötigt.

5. Überprüfen Sie die Registrierungsübersicht der App. Klicken Sie auf Bearbeiten, um Änderungen vorzunehmen. Wenn die Anwendungsregistrierung in Ordnung ist, klicken Sie auf Zurück zum Dashboard.

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

1. Öffnen Sie die Google Cloud Console. Das Projekt mit aktivierter Abrechnung muss geöffnet sein.

2. Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > APIs und Dienste > Anmeldedaten.

   Zu den Anmeldedaten

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

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

Skript einrichten

In den folgenden Abschnitten wird das Skript 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. Wechseln 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.

Cloud-Projektnummer kopieren

1. Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > IAM und Verwaltung > Einstellungen.

   IAM- und Verwaltungseinstellungen aufrufen

2. Kopieren Sie den Wert im 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 in 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. Halten Sie den Mauszeiger über den Smartchip und autorisieren Sie bei entsprechender Aufforderung den Zugriff zum Ausführen des Add-ons. Auf der Vorschaukarte werden Informationen zum Buch angezeigt.

Die folgende Abbildung zeigt die Linkvorschau:

Code ansehen

Wenn Sie den Apps Script-Code für dieses Add-on überprüfen möchten, klicken Sie auf Quellcode anzeigen, um den Abschnitt 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