Vorschaulinks aus Google Books mit Smartchips

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

Zielsetzungen

• Informieren Sie sich über den Zweck 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. Für die Vorschau des Links kannst du den Link 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 Skript das Add-on so, dass Google Docs erweitert und Linkvorschauen für URLs ausgelöst werden, die mit bestimmten Mustern auf der Google Books-Website (https://books.google.com) übereinstimmen.

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. Das Skript verwendet diese Informationen, um einen Smartchip zu generieren, der den Buchtitel und eine Vorschaukarte mit einer Zusammenfassung, der Seitenanzahl, einem Bild des Buchcovers und der Anzahl der Bewertungen anzeigt.

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

Voraussetzungen

Sie benötigen die folgenden Voraussetzungen, um dieses Beispiel verwenden zu können:

• Ein Google-Konto (Google Workspace-Konten erfordern möglicherweise die Administratorgenehmigung).

• Ein Webbrowser mit Zugang zum Internet.

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

Umgebung einrichten

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.

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. Wenn Sie den OAuth-Zustimmungsbildschirm konfigurieren, wird definiert, was Google den Nutzern anzeigt, und Ihre Anwendung wird registriert, damit Sie sie später veröffentlichen können.

1. Rufen Sie in der Google Cloud Console das Menü menu auf > 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 außerhalb Ihrer Google Workspace-Organisation erstellen, müssen Sie den Nutzertyp in Extern ändern und dann die für die Anwendung erforderlichen Autorisierungsbereiche hinzufügen.

5. Prüfen Sie die Zusammenfassung der App-Registrierung. Wenn Sie Änderungen vornehmen möchten, klicken Sie auf Bearbeiten. Wenn die Anwendungsregistrierung in Ordnung 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 mit aktivierter Abrechnung muss geöffnet sein.

2. Klicken Sie in der Google Cloud Console auf das Dreistrich-Menü menu > 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

Apps Script-Projekt erstellen

1. Klicken Sie auf die folgende Schaltfläche, um das Apps Script-Projekt Vorschaulinks aus Google Books zu öffnen.
   Projekt öffnen
2. Klicken Sie auf info_outline Ü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ü menu > IAM und Verwaltung > Einstellungen.

   Zur Seite „IAM und Verwaltung“

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) auf Projekt ändern.
3. Fügen Sie unter GCP-Projektnummer die Google Cloud-Projektnummer ein.
4. Klicken Sie auf Projekt festlegen.

Add-on testen

Testbereitstellung installieren

1. Klicken Sie in Ihrem Apps Script-Projekt auf code Bearbeiter.
2. Öffnen Sie die Datei Code.gs und klicken Sie auf Ausführen. Autorisieren Sie das Skript, wenn Sie dazu aufgefordert werden.
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 zu konvertieren: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Bewegen Sie den Mauszeiger auf den Smartchip und gewähren Sie bei Aufforderung den Zugriff zum Ausführen des Add-ons. Auf der Vorschaukarte werden Informationen zum Buch angezeigt.

In der folgenden Abbildung sehen Sie die Linkvorschau:

Code ansehen

Wenn Sie den Apps Script-Code für dieses Add-on überprüfen möchten, klicken Sie unten auf Quellcode anzeigen:

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

Nächste Schritte

• Vorschaulinks mit Smartchips ansehen
• Referenzdokumentation zur Google Books API