使用智慧型方塊預覽 Google 圖書中的連結

程式設計層級：中級
時間長度：30 分鐘
專案類型：Google Workspace 外掛程式

目標

  • 瞭解外掛程式的功能。
  • 瞭解如何使用 Apps Script 建構外掛程式，以及 Apps Script 服務的功能。
  • 設定環境。
  • 設定指令碼。
  • 執行指令碼。

關於這個 Google Workspace 外掛程式

在此範例中，您將建立 Google Workspace 外掛程式，以便在 Google 文件文件中預覽 Google 圖書中的連結。在文件中輸入或貼上 Google 圖書網址時，外掛程式會辨識該連結並觸發連結預覽。如要預覽連結，可以將連結轉換為智慧型方塊，將滑鼠遊標懸停在連結上，即可查看含有書籍詳細資訊的資訊卡。

這個外掛程式會使用 Apps Script 的 UrlFetch 服務連線至 Google 圖書 API，並取得要在 Google 文件中顯示的 Google 圖書相關資訊。

運作方式

在 Google Workspace 外掛程式的資訊清單檔案中，指令碼會設定外掛程式擴充 Google 文件的功能，並針對符合 Google 圖書網站 (https://books.google.com) 中特定模式的網址觸發連結預覽。

在程式碼檔案中，指令碼會連線至 Google 圖書 API，並使用該網址取得書籍相關資訊 (即 Volume 資源的執行個體)。指令碼會使用這些資訊產生智慧型方塊，其中顯示書籍標題，以及顯示摘要、頁數、書籍封面圖片和評分數量的預覽資訊卡。

Apps Script 服務

這個外掛程式使用的服務如下：

必要條件

如要使用這個範例，您必須具備以下先決條件：

設定環境

在 Google Cloud 控制台中開啟 Cloud 專案

如果尚未開啟，請開啟要用於本範例的 Cloud 專案：

  1. 前往 Google Cloud 控制台的「選取專案」頁面。

    選取 Cloud 專案

  2. 選取要使用的 Google Cloud 專案。或是按一下「建立專案」，然後按照畫面上的指示操作。建立 Google Cloud 專案後，可能需要開啟專案的計費功能。

啟用 Google 圖書 API

這個外掛程式會連結到 Google 圖書 API。 使用 Google API 前，請先在 Google Cloud 專案中啟用這些 API。您可以在單一 Google Cloud 專案中啟用一或多個 API。

  • 在您的 Cloud 專案中開啟 Books API。

    啟用 API

此外掛程式需要使用已設定同意畫面的 Cloud 專案。設定 OAuth 同意畫面可定義 Google 向使用者顯示的內容，並註冊您的應用程式，以便您之後發布。

  1. 在 Google Cloud 控制台中，依序點選「選單」圖示 >「API 和服務」>「OAuth 同意畫面」。

    前往 OAuth 同意畫面

  2. 在「使用者類型」部分，選取「內部」，然後按一下「建立」。
  3. 填寫應用程式註冊表單，然後按一下「儲存並繼續」。

  4. 目前，您可以略過新增範圍，然後按一下「儲存並繼續」。日後建立用於 Google Workspace 機構外部的應用程式時，必須將「使用者類型」變更為「外部」，然後新增應用程式所需的授權範圍。

  5. 查看您的應用程式註冊摘要。如要變更，請按一下「編輯」。如果應用程式註冊正確無誤，請按一下「Back to Dashboard」(返回資訊主頁)。

取得 Google 圖書 API 的 API 金鑰

  1. 前往 Google Cloud 控制台。請確定已啟用計費功能的專案已開啟。

  2. 在 Google Cloud 控制台中，依序點選「選單」圖示 >「API 和服務」>「憑證」。

    前往「憑證」頁面

  3. 依序按一下「建立憑證」>「API 金鑰」。

  4. 記下 API 金鑰，在後續步驟中使用。

設定指令碼

建立 Apps Script 專案

  1. 按一下底下按鈕即可開啟「從 Google 圖書預覽連結」Apps Script 專案的「預覽連結」。
    開啟專案
  2. 按一下 「Overview」(總覽)。
  3. 在總覽頁面上，按一下「用於建立副本的圖示 建立副本」。
  4. 在 Apps Script 專案副本中，前往 Code.gs 檔案，然後將 YOUR_API_KEY 替換成您在上一節產生的 API 金鑰。

複製 Cloud 專案編號

  1. 在 Google Cloud 控制台中，依序點選「選單」圖示 >「IAM 與管理」>「設定」。

    前往「IAM 與管理員設定」

  2. 複製「Project number」欄位中的值。

設定 Apps Script 專案的 Cloud 專案

  1. 在 Apps Script 專案中，按一下 專案設定圖示「Project Settings」。
  2. 按一下「Google Cloud Platform (GCP) 專案」下方的「變更專案」。
  3. 在「GCP 專案編號」中貼上 Google Cloud 專案編號。
  4. 按一下「設定專案」。

測試外掛程式

安裝測試部署作業

  1. 在 Apps Script 專案中，按一下「編輯器」圖示 。
  2. 開啟 Code.gs 檔案，然後按一下「Run」。出現提示時，請授權指令碼。
  3. 依序點選「部署」>「測試部署作業」。
  4. 依序點選「安裝」>「完成」。
  1. 在 docs.new 建立 Google 文件文件。
  2. 將下列網址貼到文件，然後按下 Tab 鍵，將網址轉換為智慧型方塊：https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. 將遊標懸停在智慧型方塊上，並在系統提示時授權執行外掛程式的存取權。預覽資訊卡會顯示書籍的相關資訊。

下圖顯示連結預覽：

書籍「Google 軟體工程」的連結預覽。

檢查程式碼

如要查看這個外掛程式的 Apps Script 程式碼，請點選下方的「查看原始碼」：

查看原始碼

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

後續步驟