Xem trước đường liên kết trên Google Sách bằng khối thông minh

Cấp độ lập trình: Trung cấp
Thời lượng: 30 phút
Loại dự án: Tiện ích bổ sung của Google Workspace

Mục tiêu

• Tìm hiểu chức năng của tiện ích bổ sung.
• Tìm hiểu cách tạo tiện ích bổ sung bằng Apps Script và tìm hiểu chức năng của các dịch vụ Apps Script.
• Thiết lập môi trường.
• Thiết lập tập lệnh.
• Chạy tập lệnh.

Giới thiệu về tiện ích bổ sung này của Google Workspace

Trong mẫu này, bạn sẽ tạo một tiện ích bổ sung của Google Workspace để xem trước các đường liên kết từ Google Sách trong tài liệu Google Tài liệu. Khi bạn nhập hoặc dán URL của Google Sách vào tài liệu, tiện ích bổ sung sẽ nhận dạng đường liên kết đó và kích hoạt tính năng xem trước đường liên kết. Để xem trước đường liên kết, bạn có thể chuyển đổi đường liên kết đó thành một khối thông minh và giữ con trỏ trên đường liên kết để xem thẻ hiển thị thêm thông tin về cuốn sách.

Tiện ích bổ sung này sử dụng Dịch vụ UrlFetch của Apps Script để kết nối với Google Books API và lấy thông tin về Google Sách để hiển thị trong Google Tài liệu.

Cách hoạt động

Trong tệp kê khai của tiện ích bổ sung Google Workspace, tập lệnh sẽ định cấu hình tiện ích bổ sung để mở rộng Google Tài liệu và kích hoạt tính năng xem trước đường liên kết cho các URL khớp với một số mẫu nhất định trên trang web Google Sách (https://books.google.com).

Trong tệp mã, tập lệnh sẽ kết nối với Google Sách API và sử dụng URL để lấy thông tin về cuốn sách (là một thực thể của Volume tài nguyên). Tập lệnh sử dụng thông tin này để tạo một khối thông minh hiển thị tiêu đề của cuốn sách và một thẻ xem trước hiển thị nội dung tóm tắt, số trang, hình ảnh bìa sách và số lượt xếp hạng.

Dịch vụ Apps Script

Tiện ích bổ sung này sử dụng các dịch vụ sau:

• Dịch vụ UrlFetch – Kết nối với Google Sách API để lấy thông tin về sách (là các thực thể của tài nguyên Volume API).
• Dịch vụ thẻ – Tạo giao diện người dùng của tiện ích bổ sung.

Điều kiện tiên quyết

Để sử dụng mẫu này, bạn cần đáp ứng các điều kiện tiên quyết sau:

• Tài khoản Google (tài khoản Google Workspace có thể yêu cầu quản trị viên phê duyệt).

• Trình duyệt web có quyền truy cập vào Internet.

• Dự án trên Google Cloud.

Thiết lập môi trường

Các phần sau đây sẽ thiết lập môi trường để bạn tạo tiện ích bổ sung.

Mở dự án trên đám mây trong bảng điều khiển Cloud

Nếu chưa mở, hãy mở dự án trên đám mây mà bạn định sử dụng cho mẫu này:

1. Trong Bảng điều khiển Google Cloud, hãy chuyển đến trang Chọn một dự án.

   Chọn một dự án trên đám mây

2. Chọn dự án trên Google Cloud mà bạn muốn sử dụng. Hoặc nhấp vào Tạo dự án rồi làm theo hướng dẫn trên màn hình. Nếu tạo dự án trên Google Cloud, bạn có thể cần bật tính năng thanh toán cho dự án đó.

Bật Google Sách API

Tiện ích bổ sung này kết nối với Google Sách API. Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.

• Trong dự án trên đám mây, hãy bật Books API.

  Bật API

Định cấu hình màn hình xin phép bằng OAuth

Tiện ích bổ sung này yêu cầu một dự án trên đám mây có màn hình xin phép đã định cấu hình. Việc định cấu hình màn hình xin phép bằng OAuth sẽ xác định những nội dung mà Google hiển thị cho người dùng và đăng ký ứng dụng của bạn để bạn có thể xuất bản ứng dụng đó sau này.

1. Trong Google API Console, hãy chuyển đến Trình đơn menu > Nền tảng xác thực của Google > Thương hiệu.

   Chuyển đến trang Thương hiệu

2. Nếu đã định cấu hình nền tảng xác thực của Google, bạn có thể định cấu hình các chế độ cài đặt sau đây cho Màn hình xin phép bằng OAuth trong phần Thương hiệu, Đối tượng và Quyền truy cập dữ liệu. Nếu bạn thấy thông báo Nền tảng xác thực của Google chưa được định cấu hình, hãy nhấp vào Bắt đầu:
1. Trong phần Thông tin ứng dụng, ở mục Tên ứng dụng, hãy nhập tên cho ứng dụng.
2. Trong mục Email hỗ trợ người dùng, hãy chọn địa chỉ email hỗ trợ mà người dùng có thể liên hệ với bạn nếu họ có câu hỏi về việc đồng ý.
3. Nhấp vào Tiếp theo.
4. Trong phần Đối tượng, hãy chọn Nội bộ.
5. Nhấp vào Tiếp theo.
6. Trong phần Thông tin liên hệ, hãy nhập Địa chỉ email mà bạn có thể nhận thông báo về mọi thay đổi đối với dự án của mình.
7. Nhấp vào Tiếp theo.
8. Trong phần Hoàn tất, hãy xem lại Chính sách dữ liệu người dùng của các dịch vụ API của Google và nếu bạn đồng ý, hãy chọn Tôi đồng ý với Chính sách dữ liệu người dùng của các dịch vụ API của Google.
9. Nhấp vào Tiếp tục.
10. Nhấp vào Tạo.
3. Hiện tại, bạn có thể bỏ qua bước thêm phạm vi. Trong tương lai, khi tạo một ứng dụng để sử dụng bên ngoài tổ chức Google Workspace, bạn phải thay đổi Loại người dùng thành Bên ngoài. Sau đó, hãy thêm các phạm vi uỷ quyền mà ứng dụng của bạn yêu cầu. Để tìm hiểu thêm, hãy xem hướng dẫn đầy đủ về cách Định cấu hình màn hình xin phép bằng OAuth.

Lấy khoá API cho Google Sách API

1. Chuyển đến Google API Console. Đảm bảo dự án đã bật tính năng thanh toán đang mở.

2. Trong Google API Console, hãy chuyển đến Trình đơn menu > API và Dịch vụ > Thông tin xác thực.

   Chuyển đến phần Thông tin xác thực

3. Nhấp vào Tạo thông tin xác thực > Khoá API.

4. Ghi lại khoá API để sử dụng trong bước tiếp theo.

Thiết lập tập lệnh

Các phần sau đây sẽ thiết lập tập lệnh để bạn tạo tiện ích bổ sung.

Tạo dự án Apps Script

1. Nhấp vào nút sau để mở dự án Apps Script Xem trước đường liên kết từ Google Sách.
   Mở dự án
2. Nhấp vào info_outline Tổng quan.
3. Trên trang tổng quan, hãy nhấp vào Tạo bản sao.
4. Trong bản sao của dự án Apps Script, hãy chuyển đến tệp Code.gs và thay thế YOUR_API_KEY bằng khoá API mà bạn đã tạo trong phần trước.

Trong tương lai, nếu bạn muốn sử dụng một số API của Google hoặc xuất bản ứng dụng, bạn phải liên kết dự án trên đám mây với dự án Apps Script. Trong hướng dẫn này, bạn không cần làm như vậy. Để tìm hiểu thêm, hãy xem hướng dẫn về dự án trên Google Cloud.

Kiểm thử tiện ích bổ sung

Các phần sau đây sẽ kiểm thử tiện ích bổ sung mà bạn đã tạo.

Cài đặt bản triển khai thử nghiệm

1. Trong dự án Apps Script, hãy nhấp vào code Trình chỉnh sửa.
2. Nhấp vào Triển khai > Bản triển khai thử nghiệm.
3. Nhấp vào Cài đặt > Xong.

Xem trước đường liên kết trong Google Tài liệu

1. Tạo tài liệu Google Tài liệu tại docs.new.
2. Dán URL sau vào tài liệu rồi nhấn phím tab để chuyển đổi URL đó thành một khối thông minh: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Giữ con trỏ trên khối thông minh và khi được nhắc, hãy cho phép truy cập để thực thi tiện ích bổ sung. Thẻ xem trước sẽ hiển thị thông tin về cuốn sách.

Hình ảnh sau đây cho thấy bản xem trước đường liên kết:

Xem lại mã

Để xem lại mã Apps Script cho tiện ích bổ sung này, hãy nhấp vào Xem mã nguồn để mở rộng phần này:

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

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

Chủ đề có liên quan

• Xem trước đường liên kết bằng khối thông minh
• Tài liệu tham khảo API Google Sách