Vorschaulinks aus Google Books mit Smartchips

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

Ziele

• Sie müssen wissen, was das Add‑on macht.
• Sie erfahren, wie Sie ein Add‑on mit Apps Script erstellen und was die Apps Script-Dienste tun.
• die Umgebung einrichten
• Richten Sie das Skript ein.
• Führen Sie das Skript aus.

Über dieses Google Workspace-Add‑on

In diesem Beispiel erstellen Sie ein Google Workspace-Add-on, mit dem Links aus Google Books in einem Google Docs-Dokument in der Vorschau angezeigt werden. 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 und den Mauszeiger darauf bewegen. Es wird dann 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 sollen.

Funktionsweise

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

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

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 (die Instanzen der API-Ressource Volume sind).
• Kartendienst: Erstellt die Benutzeroberfläche des Add-ons.

Vorbereitung

Für dieses Beispiel müssen die folgenden Voraussetzungen erfüllt sein:

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

• Ein Webbrowser mit Internetzugriff.

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

Umgebung einrichten

In den folgenden Abschnitten wird beschrieben, wie Sie Ihre Umgebung für die Entwicklung des Add-ons einrichten.

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. 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. Klicken Sie alternativ 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.

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

  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. Außerdem wird Ihre App registriert, damit Sie sie später veröffentlichen können.

1. Rufen Sie in der Google Cloud Console das Menü menu > Google Auth platform > Branding auf.

   Zu Branding

2. Wenn Sie die Google Auth platformbereits konfiguriert haben, können Sie die folgenden Einstellungen für den OAuth-Zustimmungsbildschirm unter Branding, Zielgruppe und Datenzugriff konfigurieren. Wenn Sie die Meldung Google Auth platform noch nicht konfiguriert sehen, klicken Sie auf Jetzt starten:
1. Geben Sie unter App-Informationen im Feld App-Name einen Namen für die App ein.
2. Wählen Sie unter E-Mail-Adresse des Nutzersupports eine Support-E-Mail-Adresse aus, über die Nutzer Sie mit Fragen zu ihrer Einwilligung kontaktieren können.
3. Klicken Sie auf Weiter.
4. Wählen Sie unter Zielgruppe die Option Intern aus.
5. Klicken Sie auf Weiter.
6. Geben Sie unter Kontaktdaten eine E-Mail-Adresse ein, unter der Sie über Änderungen an Ihrem Projekt benachrichtigt werden können.
7. Klicken Sie auf Weiter.
8. Sehen Sie sich unter Abschließen die Nutzerdatenrichtlinie für Google API-Dienste an. Wenn Sie damit einverstanden sind, wählen Sie Ich stimme der Nutzerdatenrichtlinie für Google API-Dienste zu aus.
9. Klicken Sie auf Weiter.
10. Klicken Sie auf Erstellen.
3. Sie können das Hinzufügen von Bereichen 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 in der vollständigen Anleitung OAuth-Zustimmung konfigurieren.

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. Rufen Sie in der Google Cloud Console das Menü menu > APIs und Dienste > Anmeldedaten auf.

   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.

Skript einrichten

In den folgenden Abschnitten wird das Skript für das Erstellen des Add-ons eingerichtet.

Apps Script-Projekt erstellen

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

Cloud-Projektnummer kopieren

1. Rufen Sie in der Google Cloud Console das Menü menu > IAM & Verwaltung > Einstellungen auf.

   Weiter zur Seite „IAM & Verwaltung“

2. Kopieren Sie den Wert aus dem Feld Projektnummer.

Cloud-Projekt für das Apps Script-Projekt 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 die Google Cloud-Projektnummer in GCP-Projektnummer ein.
4. Klicken Sie auf Projekt festlegen.

Add-on testen

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

Test-Deployment installieren

1. Klicken Sie in Ihrem Apps Script-Projekt auf code 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 > Testbereitstellungen.
4. Klicken Sie auf Installieren > Fertig.

Vorschau eines Links in Google Docs ansehen

1. Erstellen Sie ein Google-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, wenn Sie dazu aufgefordert werden, um das Add-on auszuführen. 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 ansehen möchten, klicken Sie auf Quellcode ansehen, um den Bereich zu maximieren:

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

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
• Google Books API-Referenzdokumentation