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

编码水平：中级
时长：30 分钟
项目类型：Google Workspace 加载项

目标

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

关于此 Google Workspace 加购项

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

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

运作方式

在 Google Workspace 加载项的清单文件中，脚本将加载项配置为扩展 Google 文档，并针对符合 Google 图书网站 (https://books.google.com) 中特定模式的网址触发链接预览。

在代码文件中，脚本连接到 Google Books API，并使用网址获取有关图书（即 Volume 资源的实例）的信息。该脚本会使用此信息生成一个智能芯片，其中显示图书的标题；还会生成一个预览卡，其中显示摘要、页数、图书封面图片和评分数量。

Apps 脚本服务

此插件使用以下服务：

前提条件

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

设置环境

以下部分将设置用于构建插件的环境。

在 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 项目。配置 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 同意指南。

获取 Google Books API 的 API 密钥

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

  2. 在 Google Cloud 控制台中，依次前往菜单 > API 和服务 > 凭据。

    转到“凭据”页面

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

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

设置脚本

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

创建 Apps 脚本项目

  1. 点击以下按钮，打开 Google 图书中的预览链接 Apps 脚本项目。
    打开项目
  2. 点击 概览。
  3. 在概览页面上，点击 用于创建副本的图标 复制。
  4. 在您的 Apps 脚本项目副本中，前往 Code.gs 文件，然后将 YOUR_API_KEY 替换为您在上一部分中生成的 API 密钥。

复制 Cloud 项目编号

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

    前往“IAM 和管理”设置

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

设置 Apps 脚本项目的 Cloud 项目

  1. 在您的 Apps 脚本项目中，点击 项目设置的图标 项目设置。
  2. 在 Google Cloud Platform (GCP) 项目下，点击更改项目。
  3. 在 GCP project number 中，粘贴 Google Cloud 项目编号。
  4. 点击设置项目。

测试插件

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

安装测试部署

  1. 在 Apps 脚本项目中，点击 编辑器。
  2. 将 YOUR_API_KEY 替换为在上一部分中创建的 Google Books API 的 API 密钥。
  3. 依次点击部署 > 测试部署。
  4. 依次点击安装 > 完成。
  1. 通过 docs.new 创建 Google 文档。
  2. 将以下网址粘贴到文档中，然后按 Tab 键将该网址转换为智能条状标签： https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. 将指针悬停在智能条状标签上，并在系统提示时授权访问，以执行该插件。预览卡片会显示有关图书的信息。

下图显示了链接预览：

图书《Google 的软件工程》的链接预览。

查看代码

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

查看源代码

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