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

Poziom zaawansowania w zakresie programowania: średni
Czas trwania: 30 minut
Typ projektu: dodatek do Google Workspace

Cele

  • Dowiedz się, do czego służy 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 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 go przekształcić w element inteligentny i przytrzymać nad nim kursor, aby wyświetlić kartę z dodatkowymi informacjami o książce.

Ten dodatek używa usługi UrlFetch Service w Apps Script, aby połączyć się z interfejsem API Google Books i pobrać informacje o Google Books, które mają być wyświetlane w Dokumentach Google.

Jak to działa

W pliku manifestu dodatku Google Workspace skrypt konfiguruje dodatek, aby rozszerzał Dokumenty Google i uruchamiał podgląd linków w przypadku adresów URL pasujących do określonych wzorów z witryny Książki Google (https://books.google.com).

W pliku kodu skrypt łączy się z interfejsem Google Books API i korzysta z adresu URL, aby uzyskać informacje o książce (która jest wystąpieniem zasobu Volume). Skrypt używa tych informacji do wygenerowania elementu inteligentnego, który wyświetla tytuł książki oraz kartę podglądu z podsumowaniem, liczbą stron, obrazem okładki książki i liczbą ocen.

Usługi Apps Script

Ten dodatek korzysta z tych usług:

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

Wymagania wstępne

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

Konfigurowanie środowiska

W następnych sekcjach skonfigurujesz środowisko do tworzenia dodatku.

Otwieranie projektu Cloud w konsoli Google Cloud

Jeśli nie jest jeszcze otwarty, otwórz projekt Cloud, którego chcesz użyć w przypadku tej próbki:

  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 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 je włączyć 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 z skonfigurowanym ekranem zgody. Konfigurując ekran zgody OAuth, określasz, co Google ma wyświetlać użytkownikom, i rejestrujesz aplikację, aby można ją było opublikować.

  1. W konsoli Google Cloud otwórz Menu  > > Identyfikacja marki.

    Przejdź do sekcji Promowanie marki

  2. Jeśli masz już skonfigurowany projekt , możesz skonfigurować te ustawienia ekranu zgody OAuth: Markowanie, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat nie skonfigurowano, kliknij Rozpocznij:
    1. W sekcji Informacje o aplikacji w polu Nazwa aplikacji wpisz nazwę aplikacji.
    2. W sekcji Adres e-mail zespołu pomocy wybierz adres e-mail zespołu pomocy, na który użytkownicy będą mogli się z Tobą kontaktować w sprawie pytań dotyczących zgody.
    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ędą wysyłane powiadomienia o 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 potem, jeśli się z nimi zgadzasz, 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. Gdy w przyszłości 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. Upewnij się, że masz otwarty projekt z włączonymi płatnościami.

  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 następnym kroku.

Konfigurowanie skryptu

W następnych sekcjach skonfiguruj skrypt do tworzenia dodatku.

Tworzenie projektu Apps Script

  1. Kliknij ten przycisk, aby otworzyć projekt Apps Script Podgląd linków z Google Books.
    Otwórz projekt
  2. Kliknij Przegląd.
  3. Na stronie Przegląd kliknij Ikona kopiowania Utwórz kopię.
  4. W kopii projektu Apps Script otwórz plik Code.gs i zastąp wartość YOUR_API_KEY kluczem 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 Google 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 polu Numer projektu GCP wklej numer projektu Google Cloud.
  4. Kliknij Ustaw projekt.

Testowanie dodatku

W następnych sekcjach przetestujesz utworzony przez siebie dodatek.

Instalowanie testowego wdrożenia

  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 w Dokumentach Google na stronie docs.new.
  2. Wklej ten adres URL do dokumentu 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, a gdy pojawi się taka prośba, zezwól na dostęp do dodatku. Karta podglądu zawiera informacje o książce.

Poniższy obraz przedstawia podgląd linku:

Link do podglądu książki „Software Engineering at Google”

Sprawdzanie kodu

Aby sprawdzić kod Apps Script tego dodatku, kliknij Wyświetl kod źródłowy, aby rozwinąć tę 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
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();
  }
}