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

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

Cele

• Dowiedz się, do czego służy ten dodatek.
• Dowiedz się, jak utworzyć dodatek za pomocą Apps Script, i do czego służą usługi 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 URL z Książek Google w dokumencie, dodatek rozpozna link i wyświetli jego podgląd. Aby wyświetlić podgląd linku, możesz przekonwertować link na element inteligentny, najeżdżając na niego kursorem i wyświetlając kartę zawierającą więcej informacji o książce.

Ten dodatek używa usługi UrlFetch Apps Script do łączenia się z interfejsem API Książek Google i pobierania informacji o Książkach Google do wyświetlenia w Dokumentach Google.

Jak to działa

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

W pliku kodu skrypt łączy się z interfejsem API Książek Google i używa adresu URL do pobrania informacji o książce (która jest instancją zasobu Volume). Na podstawie tych informacji skrypt generuje element inteligentny wyświetlający tytuł książki oraz kartę podglądu z podsumowaniem, liczbą stron, zdjęciem okładki książki i liczbą ocen.

Usługi Apps Script

Ten dodatek korzysta z następujących usług:

• UrlFetch Service – łączy się z interfejsem API Książek Google, by pobierać informacje o książkach (które są wystąpieniami zasobu Volume API).
• Card Service (Usługa karty) – tworzy interfejs użytkownika dodatku.

Wymagania wstępne

Aby korzystać z tego przykładu, musisz spełnić te wymagania wstępne:

• Konto Google (konta Google Workspace mogą wymagać zatwierdzenia przez administratora).

• Przeglądarka z dostępem do internetu.

• Projekt Google Cloud z powiązanym kontem rozliczeniowym. Więcej informacji znajdziesz w artykule Włączanie płatności za projekt.

Konfigurowanie środowiska

W sekcjach poniżej dowiesz się, jak skonfigurować środowisko, w którym chcesz utworzyć dodatek.

Otwieranie projektu Cloud w konsoli Google Cloud

Jeśli projekt nie jest jeszcze otwarty, otwórz go, którego zamierzasz użyć w tym przykładzie:

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

   Wybierz projekt Cloud

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 tworzysz projekt Google Cloud, konieczne może być włączenie dla niego płatności.

Włączanie interfejsu API Książek Google

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

• W swoim projekcie Cloud włącz Books API.

  Włącz interfejs API

Konfigurowanie ekranu zgody OAuth

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

1. W konsoli Google Cloud otwórz Menu > Interfejsy API i usługi > Ekran zgody OAuth.

   Otwórz ekran zgody OAuth

2. Jako Typ użytkownika wybierz Wewnętrzny i kliknij Utwórz.
3. Wypełnij formularz rejestracji aplikacji, a potem kliknij Zapisz i kontynuuj.

4. Na razie możesz pominąć dodawanie zakresów i kliknąć Zapisz i kontynuuj. W przyszłości, gdy utworzysz aplikację do użytku poza swoją organizacją Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny, a następnie dodać zakresy autoryzacji wymagane przez aplikację.

5. Przejrzyj podsumowanie rejestracji aplikacji. Aby wprowadzić zmiany, kliknij Edytuj. Jeśli rejestracja aplikacji wygląda dobrze, kliknij Wróć do panelu.

Uzyskiwanie klucza interfejsu API Książek Google

1. Otwórz konsolę Google Cloud. Sprawdź, czy projekt z włączonymi płatnościami jest otwarty.

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

   Przejdź do danych logowania

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

4. Zanotuj swój klucz interfejsu API – będzie Ci potrzebny w późniejszym kroku.

Konfigurowanie skryptu

Skrypt tworzenia dodatku został omówiony w poniższych sekcjach.

Tworzenie projektu Apps Script

1. Kliknij ten przycisk, aby otworzyć projekt Podgląd linków z Książek Google Apps Script.
   Otwórz projekt
2. Kliknij Przegląd.
3. Na stronie Przegląd kliknij Utwórz kopię.
4. Przejdź do pliku Code.gs w kopii projektu Apps Script i zastąp YOUR_API_KEY kluczem interfejsu API wygenerowanym w poprzedniej sekcji.

Kopiuj numer projektu Cloud

1. W konsoli Google Cloud otwórz Menu > Administracja > Ustawienia.

   Otwórz stronę Administracja

2. Skopiuj wartość z pola Numer projektu.

Ustawianie projektu Cloud w projekcie Apps Script

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

Testowanie dodatku

Poniższe sekcje pozwalają przetestować utworzony dodatek.

Instalowanie wdrożenia testowego

1. W projekcie Apps Script kliknij Edytor.
2. Zastąp YOUR_API_KEY kluczem interfejsu Google Books API utworzonym w poprzedniej sekcji.
3. Kliknij Wdróż > Testuj wdrożenia.
4. Kliknij Zainstaluj > Gotowe.

Wyświetlanie podglądu linku w Dokumentach Google

1. Utwórz dokument w Dokumentach Google na stronie docs.new.
2. Wklej ten adres URL do dokumentu i naciśnij klawisz Tab, aby przekonwertować adres URL na element inteligentny: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Najedź kursorem na element inteligentny, a gdy pojawi się prośba, autoryzuj dostęp, aby uruchomić dodatek. Na karcie podglądu zobaczysz informacje o książce.

Na tej ilustracji widać podgląd linku:

Sprawdź kod

Jeśli chcesz przejrzeć kod Apps Script tego dodatku, kliknij Wyświetl kod źródłowy w celu rozwinięcia sekcji:

Pokaż kod źródłowy

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

Wyświetl w GitHubie

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

Wyświetl w GitHubie

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

Powiązane artykuły

• Podgląd linków z elementami inteligentnymi
• Dokumentacja interfejsu API Książek Google