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

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

Цели

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

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

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

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

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

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

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

Службы сценариев приложений

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

• Служба UrlFetch – подключается к API Google Книг для получения информации о книгах (которые являются экземплярами ресурса Volume API).
• 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 выберите menu > API и службы > Экран согласия OAuth .

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

2. В качестве типа пользователя выберите «Внутренний» , затем нажмите « Создать» .
3. Заполните форму регистрации приложения, затем нажмите «Сохранить и продолжить» .

4. На данный момент вы можете пропустить добавление областей и нажать «Сохранить и продолжить» . В будущем, когда вы создадите приложение для использования за пределами вашей организации Google Workspace, вам необходимо изменить тип пользователя на Внешний , а затем добавить области авторизации, необходимые вашему приложению.

5. Просмотрите сводную информацию о регистрации приложения. Чтобы внести изменения, нажмите «Изменить» . Если регистрация приложения выглядит нормально, нажмите «Вернуться на панель управления» .

Получите ключ API для API Google Книг.

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

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

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

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

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

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

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

Создайте проект скрипта приложений.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Книг