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

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

Cele

  • Dowiedz się, jak działa dodatek.
  • Dowiedz się, jak utworzyć dodatek przy użyciu 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 tworzysz 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 do dokumentu, dodatek rozpozna link i wyświetli jego podgląd. Aby wyświetlić podgląd linku, możesz przekonwertować link na element inteligentny i najechać na niego kursorem, aby wyświetlić kartę z dodatkowymi informacjami o książce.

Ten dodatek korzysta z usługi UrlFetch dostępnej w Apps Script, by łączyć się z interfejsem API Książek Google i pobierać informacje o Książkach Google, które mają być wyświetlane w Dokumentach Google.

Jak to działa

W pliku manifestu dodatku Google Workspace skrypt konfiguruje dodatek w taki sposób, aby rozszerzał on Dokumenty Google i uruchamiał podgląd linków do podstron pasujących do określonych wzorców w witrynie Książki Google (https://books.google.com).

W pliku kodu skrypt łączy się z interfejsem Google Books API i używa adresu URL do pobrania informacji o książce (który jest wystąpieniem zasobu Volume). Skrypt korzysta z tych informacji, aby wygenerować element inteligentny, który wyświetla tytuł książki i kartę podglądu, która zawiera podsumowanie, liczbę stron, obraz okładki książki i liczbę ocen.

Usługi Apps Script

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

  • UrlFetch – łączy się z interfejsem Google Books API, aby pobierać informacje o książkach (które są instancjami zasobu Volume interfejsu API).
  • Usługa karty – tworzy interfejs dodatku.

Wymagania wstępne

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

Konfigurowanie środowiska

Otwieranie projektu Cloud w konsoli Google Cloud

Jeśli nie jest jeszcze otwarty, otwórz projekt Cloud, którego chcesz 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 utworzysz projekt Google Cloud, może być konieczne włączenie dla niego płatności.

Włączanie interfejsu Google Books API

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

Ten dodatek wymaga projektu Cloud ze skonfigurowanym ekranem zgody. Skonfigurowanie ekranu zgody OAuth określa, co Google wyświetla użytkownikom, i rejestruje aplikację, aby umożliwić Ci opublikowanie jej później.

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

    Otwórz ekran zgody OAuth

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

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

  5. Przejrzyj podsumowanie rejestracji aplikacji. Aby wprowadzić zmiany, kliknij Edytuj. Jeśli rejestracja aplikacji wygląda na prawidłową, kliknij Back to Dashboard (Powrót do panelu).

Uzyskiwanie klucza interfejsu API dla 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 kliknij Menu > Interfejsy API i usługi > Dane logowania.

    Otwórz stronę Dane 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

Tworzenie projektu Apps Script

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

Kopiowanie numeru projektu Cloud

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

    Otwórz Ustawienia Administracja

  2. Skopiuj wartość z pola Numer projektu.

Ustawianie projektu Cloud dla projektu 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 polu Numer projektu GCP wklej numer projektu Google Cloud.
  4. Kliknij Ustaw projekt.

Testowanie dodatku

Instalowanie wdrożenia testowego

  1. W projekcie Apps Script kliknij Edytor.
  2. Otwórz plik Code.gs i kliknij Uruchom. Gdy pojawi się odpowiedni komunikat, autoryzuj skrypt.
  3. Kliknij Wdróż > Testuj wdrożenia.
  4. Kliknij Zainstaluj > Gotowe.
  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 w celu wykonania dodatku. Karta podglądu zawiera informacje o książce.

Poniższa ilustracja przedstawia podgląd linku:

Podgląd linku do książki Inżynieria oprogramowania w Google.

Sprawdź kod

Aby sprawdzić kod Apps Script tego dodatku, kliknij Wyświetl kod źródłowy poniżej:

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

Dalsze kroki