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

Mức độ 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à hiểu rõ 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 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 một tài liệu, tiện ích bổ sung sẽ nhận dạng đường liên kết và kích hoạt bản 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 một 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 API Google Sách 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 bản 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 Books API và sử dụng URL để lấy thông tin về cuốn sách (là một thực thể của tài nguyên Volume). 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ị bản tóm tắt, số trang, hình ảnh bìa sách và số điểm 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 API Google Sách để lấy thông tin về sách (là các thực thể của tài nguyên Volume của API).
• Card Service (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 có các điều kiện tiên quyết sau:

• Tài khoản Google (có thể cần có sự phê duyệt của quản trị viên đối với tài khoản Google Workspace).

• Một trình duyệt web có quyền truy cập Internet.

• Dự án trên Google Cloud có tài khoản thanh toán được liên kết. Hãy tham khảo bài viết Bật tính năng thanh toán cho dự án.

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

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

Mở dự án trên Google Cloud trong Google Cloud Console

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

1. Trong Google Cloud Console, 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 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 phải bật tính năng thanh toán cho dự án.

Bật API Google Sách

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

• Trong dự án trên Google Cloud, hãy bật API Sách.

  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 Cloud có màn hình đồng ý đã đị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 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ể phát hành ứng dụng sau này.

1. Trong Google Cloud Console, hãy chuyển đến Trình đơn menu > API và dịch vụ > Màn hình đồng ý OAuth.

   Chuyển đến màn hình xin phép bằng OAuth

2. Đối với Loại người dùng, hãy chọn Nội bộ, sau đó nhấp vào Tạo.
3. Hoàn tất biểu mẫu đăng ký ứng dụng, sau đó nhấp vào Lưu và tiếp tục.

4. Hiện tại, bạn có thể bỏ qua bước thêm phạm vi và nhấp vào Lưu và tiếp tục. 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 đó thêm các phạm vi uỷ quyền mà ứng dụng của bạn yêu cầu.

5. Xem lại thông tin tóm tắt về việc đăng ký ứng dụng. Để chỉnh sửa, hãy nhấp vào Chỉnh sửa. Nếu bạn thấy quá trình đăng ký ứng dụng đã hoàn tất, hãy nhấp vào Quay lại trang tổng quan.

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

1. Chuyển đến Bảng điều khiển Google Cloud. Đảm bảo dự án đã bật tính năng thanh toán đang mở.

2. Trong Google Cloud 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 thiết lập tập lệnh để 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 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 ở phần trước.

Sao chép số dự án trên Cloud

1. Trong Google Cloud Console, hãy chuyển đến Trình đơn menu > IAM & Admin (Quản trị viên và quản lý quyền truy cập) > Settings (Cài đặt).

   Chuyển đến phần IAM và Cài đặt quản trị

2. Trong trường Mã dự án, hãy sao chép giá trị.

Thiết lập dự án trên Google Cloud của dự án Apps Script

1. Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án.
2. Trong phần Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
3. Trong mục Số dự án GCP, hãy dán số dự án trên Google Cloud.
4. Nhấp vào Đặt dự án.

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 một bản triển khai kiểm thử

1. Trong dự án Apps Script, hãy nhấp vào code Trình chỉnh sửa.
2. Thay thế YOUR_API_KEY bằng khoá API cho API Google Sách, được tạo trong phần trước.
3. Nhấp vào Triển khai > Kiểm thử bản triển khai.
4. 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 trên 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 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 xét 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"
          }
        }
      ]
    }
  }
}

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 về API Google Sách