Предварительный просмотр ссылок из Google Книг с помощью смарт-чипов

Уровень владения программированием : Средний
Продолжительность : 30 минут
Тип проекта : Дополнение для Google Workspace

Цели

• Разберитесь, что делает это дополнение.
• Разберитесь, как создавать дополнения с помощью Apps Script, и поймите, для чего нужны службы Apps Script.
• Настройте свою среду.
• Настройте скрипт.
• Запустите скрипт.

Об этом дополнении для Google Workspace

В этом примере вы создаёте надстройку для Google Workspace, которая отображает предварительный просмотр ссылок из Google Books в документе Google Docs. Когда вы вводите или вставляете URL-адрес Google Books в документ, надстройка распознаёт ссылку и запускает предварительный просмотр. Чтобы просмотреть ссылку, вы можете преобразовать её в смарт-чип и навести указатель мыши на ссылку, чтобы увидеть карточку с дополнительной информацией о книге.

Это дополнение использует сервис UrlFetch из Apps Script для подключения к API Google Books и получения информации о книгах Google для отображения в документах Google Docs.

Как это работает

В файле манифеста дополнения Google Workspace скрипт настраивает дополнение таким образом, чтобы оно расширяло функциональность Google Docs и запускало предварительный просмотр ссылок для URL-адресов, соответствующих определенным шаблонам веб-сайта Google Books ( https://books.google.com ).

В файле с кодом скрипт подключается к API Google Books и использует URL-адрес для получения информации о книге (которая является экземпляром ресурса Volume ). Скрипт использует эту информацию для создания смарт-чипа, отображающего название книги и карточку предварительного просмотра, которая показывает краткое содержание, количество страниц, изображение обложки книги и количество оценок.

Сервисы Apps Script

Данное дополнение использует следующие сервисы:

• Сервис UrlFetch подключается к API Google Books для получения информации о книгах (которые являются экземплярами ресурса Volume API).
• Сервис обработки карт — создает пользовательский интерфейс дополнения.

Предварительные требования

Для использования этого примера необходимы следующие условия:

• Для работы потребуется учетная запись Google (для учетных записей Google Workspace может потребоваться подтверждение администратора).

• Веб-браузер с доступом в интернет.

• Проект Google Cloud .

Настройте свою среду

В следующих разделах вы настроите среду для сборки дополнения.

Откройте свой облачный проект в консоли Google Cloud.

Если проект Cloud, который вы собираетесь использовать в этом примере, еще не открыт, откройте его:

1. В консоли Google Cloud перейдите на страницу «Выберите проект» .

   Выберите облачный проект

2. Выберите проект Google Cloud, который хотите использовать. Или нажмите «Создать проект» и следуйте инструкциям на экране. Если вы создаете проект Google Cloud, вам может потребоваться включить оплату для этого проекта .

Включите API Google Книги

Это дополнение подключается к API Google Books. Прежде чем использовать API Google, необходимо включить их в проекте Google Cloud. В одном проекте Google Cloud можно включить один или несколько API.

• В вашем облачном проекте включите API для работы с книгами.

  Включите API

Настройте экран согласия OAuth.

Для работы этого дополнения требуется облачный проект с настроенным экраном согласия. Настройка экрана согласия OAuth определяет, что Google отображает пользователям, и регистрирует ваше приложение, чтобы вы могли опубликовать его позже.

1. В консоли Google Cloud перейдите в >Google Auth platform > Брендинг .

   Перейти к разделу «Брендинг»

2. Если вы уже настроили Google Auth platformВы можете настроить следующие параметры экрана согласия OAuth в разделах «Брендинг» , «Аудитория» и «Доступ к данным» . Если вы видите сообщение, в котором говорится... Google Auth platform Если конфигурация еще не выполнена , нажмите «Начать» :
1. В разделе «Информация о приложении» , в поле «Название приложения» , введите название для приложения.
2. В разделе «Электронная почта службы поддержки пользователей» выберите адрес электронной почты, по которому пользователи смогут связаться с вами, если у них возникнут вопросы относительно их согласия.
3. Нажмите «Далее» .
4. В разделе «Аудитория» выберите «Внутренняя» .
5. Нажмите «Далее» .
6. В поле «Контактная информация» укажите адрес электронной почты , на который вы сможете получать уведомления об изменениях в вашем проекте.
7. Нажмите «Далее» .
8. В разделе «Завершить» ознакомьтесь с Политикой использования пользовательских данных сервисов Google API и, если вы согласны, выберите «Я согласен с Политикой использования пользовательских данных сервисов Google API» .
9. Нажмите «Продолжить» .
10. Нажмите «Создать» .
3. На данный момент добавление областей действия можно пропустить. В будущем, при создании приложения для использования за пределами вашей организации Google Workspace, необходимо изменить тип пользователя на «Внешний» . Затем добавьте необходимые для вашего приложения области авторизации. Для получения дополнительной информации см. полное руководство по настройке согласия OAuth .

Получите ключ API для Google Books API

1. Перейдите в консоль Google Cloud . Убедитесь, что ваш проект с включенной функцией выставления счетов открыт.

2. В консоли Google Cloud перейдите в > API и сервисы > Учетные данные .

   Перейдите в раздел «Учетные данные».

3. Нажмите «Создать учетные данные» > «Ключ API» .

4. Запишите свой API-ключ для использования на следующем шаге.

Настройте скрипт

В следующих разделах описывается настройка скрипта для сборки дополнения.

Создайте проект Apps Script.

1. Нажмите на следующую кнопку, чтобы открыть ссылки предварительного просмотра из проекта Google Books Apps Script.
   Откройте проект
2. Нажмите на Overview .
3. На странице обзора нажмите Сделайте копию .
4. В вашей копии проекта Apps Script перейдите к файлу Code.gs и замените YOUR_API_KEY на ключ API, который вы сгенерировали в предыдущем разделе.

В будущем, если вы захотите использовать определенные API Google или опубликовать свое приложение, вам необходимо будет связать свой проект Cloud с проектом Apps Script. В этом руководстве это делать не требуется. Для получения дополнительной информации см. руководство по проектам Google Cloud .

Протестируйте дополнение

В следующих разделах вы сможете протестировать созданное вами дополнение.

Установите тестовую среду развертывания.

1. В проекте Apps Script нажмите «Редактор .
2. Нажмите «Развернуть» > «Проверить развертывания» .
3. Нажмите «Установить» > «Готово» .

Предварительный просмотр ссылки в Google Документах

1. Создайте документ Google Docs на сайте docs.new .
2. Вставьте следующий URL-адрес в документ и нажмите клавишу Tab , чтобы преобразовать URL-адрес в смарт-чип: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Наведите указатель мыши на смарт-чип и, когда появится запрос, разрешите доступ для выполнения дополнения. На карточке предварительного просмотра отобразится информация о книге.

На следующем изображении показан предварительный просмотр ссылки:

Просмотрите код

Чтобы просмотреть код Apps Script для этого дополнения, нажмите «Просмотреть исходный код» , чтобы развернуть раздел:

Просмотреть исходный код

appsscript.json

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

Посмотреть на GitHub

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

Посмотреть на GitHub

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

Связанные темы

• Предварительный просмотр соединений со смарт-чипами
• Документация по API Google Books