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 tworzyć dodatki za pomocą Apps Script, i poznaj funkcje usług Apps Script.
  • Skonfiguruj ś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 wyświetli jego podgląd. Aby wyświetlić podgląd linku, możesz przekonwertować go na element inteligentny i najechać na niego kursorem, aby wyświetlić kartę z dodatkowymi informacjami o książce.

Ten dodatek używa usługi UrlFetch Apps Script do łączenia się z interfejsem Google Books API i pobierania informacji o Książkach Google, które mają być wyświetlane w Dokumentach Google.

Jak to działa

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

W pliku kodu skrypt łączy się z interfejsem API Książek Google i używa adresu URL aby uzyskać informacje o książce (która jest instancją Volume zasobu). Skrypt używa tych informacji do wygenerowania elementu inteligentnego, 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 korzystać z tego przykładu, musisz spełnić te wymagania wstępne:

  • Konto Google (w przypadku kont Google Workspace może być wymagana zgoda administratora).

  • Przeglądarka internetowa z dostępem do internetu.

  • Projekt Google Cloud.

Konfigurowanie środowiska

W tych sekcjach skonfigurujesz środowisko do tworzenia dodatku.

Otwieranie projektu w chmurze w konsoli Google Cloud

Jeśli nie jest jeszcze otwarty, otwórz projekt w chmurze, 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 w chmurze Google, 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 w nim płatności.

Włączanie interfejsu Książki Google API

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

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

  1. W konsoli interfejsów API Google otwórz Menu > Platforma uwierzytelniania Google > Elementy marki.

    Otwórz Elementy marki

  2. Jeśli platforma uwierzytelniania Google jest już skonfigurowana, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Elementy marki, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Platforma uwierzytelniania Google nie została jeszcze skonfigurowana, 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ą się z Tobą skontaktować, jeśli mają pytania dotyczące zgody.
    3. Kliknij Dalej.
    4. W sekcji Odbiorcy wybierz Wewnętrzni.
    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 i jeśli się z nimi zgadzasz, zaznacz pole 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 ekranu zgody OAuth.

Uzyskiwanie klucza interfejsu API Książek Google

  1. Otwórz konsolę interfejsów API Google. Upewnij się, że masz otwarty projekt z włączonymi płatnościami.

  2. W konsoli interfejsów API Google otwórz Menu > Interfejsy API i usługi > Dane logowania.

    Otwórz Dane 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 tych sekcjach skonfigurujesz skrypt do tworzenia dodatku.

Tworzenie projektu Apps Script

  1. Kliknij ten przycisk, aby otworzyć projekt Apps Script Wyświetlanie podglądu linków z Książek Google.
    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.

Jeśli w przyszłości będziesz chcieć korzystać z określonych interfejsów API Google lub opublikować aplikację, musisz powiązać projekt w chmurze z projektem Apps Script. W tym przewodniku nie musisz tego robić. Więcej informacji znajdziesz w przewodniku Projekty Google Cloud.

Testowanie dodatku

W tych sekcjach przetestujesz utworzony dodatek.

Instalowanie wdrożenia testowego

  1. W projekcie Apps Script kliknij Edytor.
  2. Kliknij Wdróż > Wdrożenia testowe.
  3. Kliknij Zainstaluj > Gotowe.
  1. Utwórz dokument Google na stronie docs.new.
  2. Wklej w dokumencie 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ź kursorem na element inteligentny i, gdy pojawi się prośba, autoryzuj dostęp do wykonania dodatku. Na karcie podglądu wyświetlą się informacje o książce.

Na tym obrazie widać podgląd linku:

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

Sprawdzanie kodu

Aby sprawdzić kod Apps Script tego dodatku, kliknij Pokaż 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();
  }
}