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

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

Mục tiêu

• Tìm hiểu chức năng của tiện ích bổ sung.
• Hiểu cách tạo một tiện ích bổ sung bằng Apps Script và 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 một tài liệu trên Google Tài liệu. Khi bạn nhập hoặc dán một 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ỏ lê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 bản xem trước đường liên kết cho những 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 kết nối với Google Books API và sử dụng URL để lấy thông tin về sách (đây là một phiên bản của Volumetài nguyên). Tập lệnh này dùng thông tin này để tạo một chip thông minh hiển thị tiêu đề của 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ượng lượt đánh giá.

Các dịch vụ của 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 Books API để lấy thông tin về sách (là các thực thể của tài nguyên Volume của 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:

• Một 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).

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

• Một dự án trên Google Cloud có tài khoản thanh toán được liên kết. Tham khảo phần Bật tính năng thanh toán cho một 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 để bạn tạo tiện ích bổ sung.

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

Nếu chưa mở, hãy mở dự án trên Cloud mà bạn dự định 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 trong 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 một 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 Books API

Tiện ích bổ sung này kết nối với Google Books 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 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 đá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 Cloud có màn hình đồng ý đã định cấu hình. Việc định cấu hình màn hình yêu cầu sự đồng ý OAuth sẽ xác định những gì Google hiển thị cho người dùng và đăng ký ứng dụng của bạn để sau này bạn có thể xuất bản ứng dụng.

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn menu > Google Auth platform > Thương hiệu.

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

2. Nếu đã định cấu hình Google Auth platform, bạn có thể định cấu hình các chế độ cài đặt sau đây cho Màn hình đồng ý OAuth trong phần Thương hiệu, Đối tượng và Quyền truy cập vào dữ liệu. Nếu bạn thấy thông báo Google Auth platform chưa được định cấu hình, hãy nhấp vào Bắt đầu:
1. Trong phần Thông tin về ứng dụng, hãy nhập tên cho ứng dụng trong mục Tên ứng dụng.
2. Trong phần Email hỗ trợ người dùng, hãy chọn một địa chỉ email hỗ trợ mà người dùng có thể liên hệ với bạn nếu họ có thắc mắc về sự đồng ý của mình.
3. Nhấp vào Tiếp theo.
4. Trong phần Đối tượng người xem, 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 để 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 kỹ Chính sách dữ liệu người dùng của dịch vụ API của Google. 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 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 sự đồng ý của OAuth.

Lấy khoá API cho Google Books API

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

2. Trong Google Cloud Console, hãy chuyển đến phầ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 đăng nhập

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

4. Hãy 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 Xem trước đường liên kết từ Google Sách Apps Script.
   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 biểu tượng Tạo bản sao.
4. Trong bản sao dự án Apps Script, hãy chuyển đến tệp Code.gs rồi thay thế YOUR_API_KEY bằng khoá API mà bạn đã tạo trong phần trước.

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

1. Trong Bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn menu > IAM và Quản trị > Cài đặt.

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

2. Sao chép giá trị trong trường Số dự án.

Đặt dự án Cloud cho dự án Apps Script

1. Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án.
2. Trong mục Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
3. Trong Số dự án trên Google Cloud Platform, 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 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. Thay thế YOUR_API_KEY bằng khoá API cho API Google Sách mà bạn đã tạo trong phần trước.
3. Nhấp vào Triển khai > Kiểm thử việc 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 một 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 uỷ quyền 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 của đường liên kết:

Xem lại mã

Để xem xét mã Apps Script của 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ề Google Books API