Wyświetlanie podglądu linków z Książek Google za pomocą elementów inteligentnych

Poziom kodowania: średnio zaawansowany
Czas trwania: 30 minut
Typ projektu: dodatek do Google Workspace

Cele

  • Dowiedz się, co robi dodatek.
  • Dowiedz się, jak utworzyć dodatek za pomocą Apps Script, i poznaj działanie usług Apps Script.
  • skonfigurować środowisko,
  • Skonfiguruj skrypt.
  • Uruchom skrypt.

Informacje o tym dodatku do Google Workspace

W tym przykładzie utworzysz dodatek do Google Workspace, który wyświetla podgląd linków z Książek Google w dokumencie Dokumentów Google. Gdy wpiszesz lub wkleisz adres URL Książek Google w dokumencie, dodatek rozpozna link i wywoła podgląd linku. Aby wyświetlić podgląd linku, możesz przekonwertować go na element inteligentny i przytrzymać wskaźnik nad linkiem, aby wyświetlić kartę z dodatkowymi informacjami o książce.

Ten dodatek korzysta z usługi UrlFetch Apps Script, aby połączyć się z interfejsem API Książek Google i uzyskać informacje o Książkach Google, które będą wyświetlane w Dokumentach Google.

Jak to działa

W pliku manifestu dodatku do Google Workspace skrypt konfiguruje dodatek tak, aby rozszerzał funkcje Dokumentów Google i wywoływał podgląd linków do adresów URL, które pasują do określonych wzorców ze strony internetowej Książek Google (https://books.google.com).

W pliku kodu skrypt łączy się z interfejsem Google Books API i używa adresu URL, aby uzyskać informacje o książce (która jest instancją Volumezasobu). Skrypt wykorzystuje te informacje do wygenerowania inteligentnego elementu, który wyświetla tytuł książki, oraz karty podglądu, która zawiera podsumowanie, liczbę stron, obraz okładki i liczbę ocen.

Usługi Apps Script

Ten dodatek korzysta z tych usług:

Wymagania wstępne

Aby użyć tego przykładu, musisz spełnić te wymagania wstępne:

Konfigurowanie środowiska

W sekcjach poniżej znajdziesz instrukcje konfigurowania środowiska do tworzenia dodatku.

Otwórz projekt w Google Cloud Console.

Otwórz projekt w Google Cloud, którego chcesz użyć w tym przykładzie:

  1. W konsoli Google Cloud otwórz stronę Wybierz projekt.

    Wybierz projekt w chmurze

  2. Wybierz projekt Google Cloud, którego chcesz użyć. Możesz też kliknąć Utwórz projekt i postępować zgodnie z instrukcjami wyświetlanymi na ekranie. Jeśli utworzysz projekt Google Cloud, może być konieczne włączenie płatności za ten projekt.

Włączanie interfejsu Google Books API

Ten dodatek łączy się z interfejsem API Książek Google. Zanim zaczniesz korzystać z interfejsów Google API, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.

Ten dodatek wymaga projektu w Cloud ze skonfigurowanym ekranem zgody. Skonfigurowanie ekranu zgody OAuth określa, co Google wyświetla użytkownikom, i rejestruje aplikację, aby można ją było później opublikować.

  1. W konsoli Google Cloud otwórz Menu  > Google Auth platform > Branding.

    Otwórz Branding

  2. Jeśli masz już skonfigurowany Google Auth platform, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Branding, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Google Auth platform Jeszcze nie skonfigurowano, kliknij Rozpocznij:
    1. W sekcji Informacje o aplikacji w polu Nazwa aplikacji wpisz nazwę aplikacji.
    2. W polu Adres e-mail dla użytkowników potrzebujących pomocy wybierz adres e-mail, na który użytkownicy mogą pisać, aby się z Tobą skontaktować w sprawie pytań o ich zgodę.
    3. Kliknij Dalej.
    4. W sekcji Odbiorcy wybierz Wewnętrzny.
    5. Kliknij Dalej.
    6. W sekcji Dane kontaktowe wpisz adres e-mail, na który będziesz otrzymywać powiadomienia o wszelkich zmianach w projekcie.
    7. Kliknij Dalej.
    8. W sekcji Zakończ zapoznaj się z zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google, a jeśli je akceptujesz, kliknij Akceptuję zasady dotyczące danych użytkownika w usługach interfejsu API Google.
    9. Kliknij Dalej.
    10. Kliknij Utwórz.
  3. Na razie możesz pominąć dodawanie zakresów. W przyszłości, gdy będziesz tworzyć aplikację do użytku poza organizacją Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny. Następnie dodaj zakresy autoryzacji wymagane przez aplikację. Więcej informacji znajdziesz w pełnym przewodniku Konfigurowanie zgody OAuth.

Uzyskiwanie klucza interfejsu API Książek Google

  1. Otwórz konsolę Google Cloud. Sprawdź, czy otwarty jest projekt, w którym włączone są płatności.

  2. W konsoli Google Cloud kliknij Menu  > Interfejsy API i usługi > Dane logowania.

    Przejdź do danych logowania

  3. Kliknij Utwórz dane logowania > Klucz interfejsu API.

  4. Zapisz klucz interfejsu API, aby użyć go w późniejszym kroku.

Konfigurowanie skryptu

W sekcjach poniżej skonfigurujesz skrypt do tworzenia dodatku.

Tworzenie projektu Apps Script

  1. Kliknij poniższy przycisk, aby otworzyć projekt Apps Script Podgląd linków z Google Play.
    Otwórz projekt
  2. Kliknij  Przegląd.
  3. Na stronie przeglądu kliknij Ikona tworzenia kopii Utwórz kopię.
  4. W kopii projektu Apps Script otwórz plik Code.gs i zastąp YOUR_API_KEY kluczem interfejsu API wygenerowanym w poprzedniej sekcji.

Skopiuj numer projektu Cloud

  1. W konsoli Google Cloud kliknij Menu  > Administracja > Ustawienia.

    Otwórz Ustawienia w obszarze Administracja

  2. W polu Numer projektu skopiuj wartość.

Ustawianie projektu Cloud w projekcie Apps Script

  1. W projekcie Apps Script kliknij Ikona ustawień projektu Ustawienia projektu.
  2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
  3. W sekcji Numer projektu GCP wklej numer projektu Google Cloud.
  4. Kliknij Ustaw projekt.

Testowanie dodatku

W kolejnych sekcjach przetestujesz utworzony dodatek.

Instalowanie wdrożenia testowego

  1. W projekcie Apps Script kliknij  Edytor.
  2. Zastąp YOUR_API_KEY kluczem interfejsu API Książek Google utworzonym w poprzedniej sekcji.
  3. Kliknij Wdróż > Testuj wdrożenia.
  4. Kliknij Zainstaluj > Gotowe.
  1. Utwórz dokument Google na stronie docs.new.
  2. Wklej do dokumentu ten adres URL i naciśnij klawisz Tab, aby przekonwertować go na element inteligentny:https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. Najedź wskaźnikiem na element inteligentny i gdy pojawi się odpowiedni komunikat, autoryzuj dostęp do wykonania dodatku. Na karcie podglądu wyświetlają się informacje o książce.

Na tym obrazie widać podgląd linku:

Podgląd linku do książki Software Engineering at Google.

Sprawdź kod

Aby sprawdzić kod Apps Script tego dodatku, kliknij Wyświetl kod źródłowy, aby rozwinąć sekcję:

Pokaż kod źródłowy

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