使用智能条状标签预览 Google 图书中的链接

编码级别：中级
时长：30 分钟
项目类型：Google Workspace 插件

目标

• 了解该插件的作用。
• 了解如何使用 Apps 脚本构建插件，以及 Apps 脚本服务的用途。
• 设置环境。
• 设置脚本。
• 运行脚本。

此 Google Workspace 插件简介

在本示例中，您将创建一个 Google Workspace 插件，用于在 Google 文档中预览 Google 图书中的链接。当您在文档中输入或粘贴 Google 图书网址时，该插件会识别链接并触发链接预览。如需预览链接，您可以将链接转换为智能条状标签，然后将指针悬停在链接上，以查看显示该图书更多信息的卡片。

此插件使用 Apps 脚本的 UrlFetch 服务连接到 Google 图书 API，并获取要显示在 Google 文档中的 Google 图书相关信息。

运作方式

在 Google Workspace 插件的清单文件中，该脚本会配置该插件以扩展 Google 文档，并针对与 Google 图书网站中的某些模式匹配的网址触发链接预览 (https://books.google.com)。

在代码文件中，脚本会连接到 Google Books API，并使用网址获取图书的相关信息（这是 Volume 资源的实例）。该脚本使用这些信息生成一个显示图书名称的智能条状标签，以及一个显示摘要、页数、图书封面图片和评分数量的预览卡片。

Apps 脚本服务

此插件使用以下服务：

• UrlFetch 服务 - 连接到 Google Books API 以获取图书的相关信息（这些信息是 API Volume 资源的实例）。
• 卡片服务 - 创建插件界面。

前提条件

如需使用此示例，您需要满足以下前提条件：

• Google 账号（Google Workspace 账号可能需要管理员批准）。

• 一个能够访问互联网的网络浏览器。

• 具有关联结算账号的 Google Cloud 项目。请参阅为项目启用结算功能。

设置环境

以下部分介绍了如何设置环境以构建插件。

在 Google Cloud 控制台中打开您的 Cloud 项目

如果尚未打开，请打开您打算用于此示例的 Cloud 项目：

1. 在 Google Cloud 控制台中，前往选择项目页面。

   选择 Cloud 项目

2. 选择您要使用的 Google Cloud 项目。或者，点击创建项目，然后按照屏幕上的说明操作。如果您创建 Google Cloud 项目，则可能需要为项目启用结算功能。

启用 Google Books API

此插件会连接到 Google Books API。在使用 Google API 之前，您需要先在 Google Cloud 项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。

• 在您的 Cloud 项目中，开启 Books API。

  启用该 API

配置 OAuth 权限请求页面

此插件需要一个已配置意见征求界面的 Cloud 项目。配置 OAuth 权限请求页面可定义 Google 向用户显示的内容，并注册您的应用以便您日后发布。

1. 在 Google Cloud 控制台中，依次点击“菜单”图标 > API 和服务 > OAuth 权限请求页面。

   转到 OAuth 同意屏幕

2. 在用户类型字段中，选择内部，然后点击创建。
3. 填写应用注册表单，然后点击保存并继续。

4. 现在，您可以跳过添加镜重，然后点击保存并继续。今后，如果您创建的应用要在 Google Workspace 组织之外使用，则必须将用户类型更改为外部，然后添加应用所需的授权范围。

5. 查看应用注册摘要。如需进行更改，请点击修改。如果应用注册未出现任何问题，请点击返回信息中心。

获取 Google Books API 的 API 密钥

1. 前往 Google Cloud 控制台。 确保已打开已启用结算功能的项目。

2. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   转到“凭据”页面

3. 依次点击创建凭据 > API 密钥。

4. 请记下您的 API 密钥，以便在后续步骤中使用。

设置脚本

以下部分将设置用于构建插件的脚本。

创建 Apps 脚本项目

1. 点击以下按钮，打开 Preview links from Google Books Apps 脚本项目。
   打开项目
2. 点击 概览。
3. 在概览页面上，点击 复制。
4. 在您的 Apps Script 项目副本中，打开 Code.gs 文件，然后将 YOUR_API_KEY 替换为您在上一部分中生成的 API 密钥。

复制 Cloud 项目编号

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > IAM 和管理 > 设置。

   前往“IAM 和管理”设置

2. 在项目编号字段中，复制相应值。

设置 Apps 脚本项目的 Cloud 项目

1. 在您的 Apps 脚本项目中，点击 Project Settings（项目设置）。
2. 在 Google Cloud Platform (GCP) Project（Google Cloud Platform [GCP] 项目）下，点击 Change project（更改项目）。
3. 在 GCP project number（GCP 项目编号）中，粘贴 Google Cloud 项目编号。
4. 点击设置项目。

测试插件

以下部分将测试您创建的插件。

安装测试部署

1. 在 Apps 脚本项目中，点击 Editor（编辑器）。
2. 将 YOUR_API_KEY 替换为在上一部分中创建的 Google Books API 的 API 密钥。
3. 依次点击 Deploy > Test deployments。
4. 依次点击安装 > 完成。

在 Google 文档中预览链接

1. 前往 docs.new 创建 Google 文档。
2. 将以下网址粘贴到文档中，然后按 Tab 键将该网址转换为智能条状标签：https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. 将指针悬停在智能条状标签上，然后在系统提示时授予执行该插件所需的访问权限。预览卡片会显示图书的相关信息。

下图显示了链接预览：

查看代码

如需查看此插件对应的 Apps 脚本代码，请点击查看源代码以展开该部分：

查看源代码

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 上查看

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

相关主题

• 预览包含智能条状标签的链接
• Google 图书 API 参考文档