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 ví dụ này, bạn sẽ tạo một Tiện ích bổ sung cho Google Workspace để xem trước đường liên kết trên 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 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 rồi di chuột qua đường liên kết để xem thẻ hiện 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à nhận 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 đị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 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 (đây 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 cho thấy tên sách và thẻ xem trước cho thấy nội dung tóm tắt, số lượng 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 để nhận thông tin về sách (là bản sao 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 có các điều kiện tiên quyết sau:

• Tài khoản Google (các 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 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

Mở dự án Cloud trong bảng điều khiển Google Cloud

Nếu chưa mở, hãy mở dự án Cloud 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 dự án.

   Chọn một dự án trên Google Cloud

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 một 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 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 các API của Google, bạn cần bật những 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 Cloud, hãy bật Books API (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 Cloud 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 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 sau.

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > 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ộ, rồi 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. Sau này, khi tạo một ứng dụng để dùng bên ngoài tổ chức Google Workspace của mình, bạn phải thay đổi Loại người dùng thành Bên ngoài, sau đó thêm phạm vi uỷ quyền mà ứng dụng của bạn yêu cầu.

5. Xem lại tóm tắt đăng ký ứng dụng của bạn. Để chỉnh sửa, hãy nhấp vào Chỉnh sửa. Nếu quá trình đăng ký ứng dụng có vẻ ổn, hãy nhấp vào Back to Dashboard (Quay lại Trang tổng quan).

Nhận khoá API cho Google Books API

1. Chuyển đến bảng điều khiển Google Cloud. Đảm bảo dự án có hỗ trợ thanh toán của bạn đang mở.

2. Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > 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 của bạn để sử dụng trong bước sau.

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

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 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 ở phần trước.

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

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

   Chuyển đến phần Cài đặt quản trị viên và quản lý danh tính và quyền truy cập (IAM)

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

Đặt dự án Cloud của dự án Apps Script

1. Trong dự án Apps Script, hãy nhấp vào Project Settings (Cài đặt dự án).
2. Trong mục Dự á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 Google Cloud.
4. Nhấp vào Đặt dự án.

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

Cài đặt quá trình triển khai thử nghiệm

1. Trong dự án Apps Script, hãy nhấp vào Trình chỉnh sửa.
2. Mở tệp Code.gs rồi nhấp vào Run (Chạy). Khi được nhắc, hãy cho phép tập lệnh.
3. Nhấp vào Triển khai > Thử nghiệm các lượt 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 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 thẻ để 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ô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 đoạn 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 bên dưới:

Xem mã nguồn

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

Xem trên GitHub

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

Xem trên GitHub

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

Các bước tiếp theo

• 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