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

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

Цели

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

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

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

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

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

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

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

Службы скриптов приложений

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

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

Предпосылки

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

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

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

• Проект Google Cloud с привязанным платёжным аккаунтом. Подробнее см. в разделе Включение платёжных услуг для проекта .

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

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

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

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

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

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

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

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

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

• В вашем облачном проекте включите Books 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. В разделе Готово ознакомьтесь с Политикой обработки данных пользователей API служб Google и, если вы согласны, выберите Я согласен с Политикой обработки данных пользователей API служб Google .
9. Нажмите «Продолжить» .
10. Нажмите «Создать» .
3. На данный момент вы можете пропустить добавление областей действия. В будущем при создании приложения для использования за пределами вашей организации Google Workspace необходимо изменить тип пользователя на «Внешний» . Затем добавьте области действия авторизации, необходимые вашему приложению. Подробнее см. в полном руководстве по настройке согласия OAuth .

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

1. Откройте консоль Google Cloud . Убедитесь, что ваш проект с поддержкой выставления счетов открыт.

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

   Перейти к учетным данным

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

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

Настройте сценарий

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

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

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

Скопируйте номер облачного проекта

1. В консоли Google Cloud перейдите в > IAM и администрирование > Настройки .

   Перейти к настройкам IAM и администрирования

2. В поле Номер проекта скопируйте значение.

Настройте облачный проект проекта Apps Script.

1. В проекте Apps Script нажмите Настройки проекта .
2. В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
3. В поле Номер проекта GCP вставьте номер проекта Google Cloud.
4. Нажмите Установить проект .

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

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

Установить тестовое развертывание

1. В проекте Apps Script нажмите Редактор .
2. Замените YOUR_API_KEY на ключ API для API Google Books, созданный в предыдущем разделе.
3. Нажмите Развернуть > Тестовые развертывания .
4. Нажмите Установить > Готово .

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

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"
          }
        }
      ]
    }
  }
}

Код.gs

решения/дополнение/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 Книги