Tạo tiện ích bổ sung cho Google Workspace bằng Node.js

Tạo tiện ích bổ sung cho Google Workspace trong Cloud Functions bằng thời gian chạy Node.js.

Mục tiêu

  • Thiết lập môi trường.
  • Tạo và triển khai một Cloud Function.
  • Tạo và triển khai tiện ích bổ sung.
  • Cài đặt tiện ích bổ sung.

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

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

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

  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 đó.

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

Tiện ích bổ sung của Google Workspace yêu cầu phải có cấu hình màn hình đồng ý. Việc định cấu hình màn hình đồng ý OAuth của tiện ích bổ sung sẽ xác định những gì Google hiển thị cho người dùng.

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > 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ượngQuyề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.

Tạo và triển khai một Cloud Function

  1. Trong bảng điều khiển Google Cloud, hãy nhấp vào Kích hoạt Cloud Shell Kích hoạt nút Cloud Shell.

    Kích hoạt Cloud Shell

    Cloud Shell Terminal sẽ mở ra và khởi chạy một phiên trong ngăn dưới cùng của bảng điều khiển Google Cloud.

  2. Nhấp vào Uỷ quyền để cung cấp và kết nối với Cloud Shell.

  3. Trong Cloud Shell Terminal, hãy bật Cloud Functions API, Cloud Build API, Google Workspace Add-ons API và Compute Engine API:

    gcloud services enable cloudfunctions.googleapis.com  \
                        cloudbuild.googleapis.com  \
                        gsuiteaddons.googleapis.com  \
                        compute.googleapis.com
    
  4. Chạy Cloud Shell Editor bằng cách nhấp vào Nút Trình soạn thảo mã Open Editor (Mở trình chỉnh sửa) trên thanh công cụ của cửa sổ Cloud Shell.

    Trình chỉnh sửa mã tích hợp này mang đến sự thuận tiện khi xem và chỉnh sửa các tệp trong cùng một môi trường nơi các dự án được tạo và triển khai.

  5. Trong thư mục trống, hãy tạo tệp function.js bằng đoạn mã mẫu sau:

    /**
     * Cloud Function that loads the homepage for a
     * Google Workspace add-on.
     *
     * @param {Object} req Request sent from Google
     * @param {Object} res Response to send back
     */
    exports.loadHomePage = function addonsHomePage (req, res) {
      res.send(createAction());
    };
    
    /** Creates a card with two widgets. */
    function createAction() {
      return {
        "action": {
          "navigations": [
            {
              "pushCard": {
                "header": {
                  "title": "Cats!"
                },
                "sections": [
                  {
                    "widgets": [
                      {
                        "textParagraph": {
                          "text": "Your random cat:"
                        }
                      },
                      {
                        "image": {
                          "imageUrl": "https://cataas.com/cat"
                         }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      };
    }
    
  6. Trong cùng thư mục, hãy tạo tệp package.json bằng đoạn mã mẫu sau:

    {
      "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
      }
    }
    
  7. Quay lại cửa sổ dòng lệnh Cloud Shell bằng cách nhấp vào Nút Kích hoạt Cloud Shell Open Terminal (Mở cửa sổ dòng lệnh).

  8. Thêm vai trò Cloud Build Service Account (roles/cloudbuild.builds.builder) vào tài khoản dịch vụ mặc định của Compute Engine.

    Trước tiên, hãy thiết lập quyền cho tài khoản dịch vụ:

    export PROJECT_ID=$(gcloud config get project)
    export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
      --format="value(defaultServiceAccount)")
    

    Tiếp theo, hãy cấp quyền còn thiếu cho tài khoản dịch vụ:

    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
      --role="roles/cloudbuild.builds.builder"
    
  9. Chạy lệnh sau để triển khai hàm:

    gcloud functions deploy loadHomePage --runtime nodejs22 --trigger-http
    

    Nếu được nhắc, hãy chỉ định rằng bạn không cho phép các lệnh gọi chưa được xác thực của hàm. Có thể mất vài phút để triển khai chức năng này.

Tạo một lượt triển khai tiện ích bổ sung

  1. Tìm email tài khoản dịch vụ cho tiện ích bổ sung:

    gcloud workspace-add-ons get-authorization
    
  2. Cấp cho tài khoản dịch vụ vai trò cloudfunctions.invoker. Thay thế SERVICE_ACCOUNT_EMAIL bằng trường serviceAccountEmail ở bước trước.

    gcloud functions add-iam-policy-binding loadHomePage \
       --role roles/cloudfunctions.invoker \
       --member serviceAccount:SERVICE_ACCOUNT_EMAIL
    
  3. Lấy URL của hàm đã triển khai. Để lấy URL, hãy chạy lệnh sau và tìm trường url trong phần httpsTrigger:

    gcloud functions describe loadHomePage
    
  4. Quay lại Trình chỉnh sửa Cloud Shell bằng cách nhấp vào Nút Trình soạn thảo mã Mở trình chỉnh sửa.

  5. Trong cùng thư mục với package.json, hãy tạo tệp deployment.json bằng mã mẫu sau. Thay thế URL bằng url của hàm đã triển khai ở bước trước.

    {
      "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
      "addOns": {
        "common": {
          "name": "My HTTP Add-on",
          "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
          "homepageTrigger": {
            "runFunction": "URL"
          }
        },
        "gmail": {},
        "drive": {},
        "calendar": {},
        "docs": {},
        "sheets": {},
        "slides": {},
        "httpOptions": {
          "granularOauthPermissionSupport": "OPT_IN"
        }
      }
    }
    
  6. Quay lại Cửa sổ dòng lệnh Cloud Shell để tạo hoạt động triển khai:

    gcloud workspace-add-ons deployments create quickstart \
       --deployment-file=deployment.json
    

Cài đặt tiện ích bổ sung

  1. Cài đặt bản triển khai ở chế độ phát triển:

    gcloud workspace-add-ons deployments install quickstart
    
  2. Mở hoặc tải lại Gmail để xem tiện ích bổ sung. Trong thanh công cụ ở bên phải, hãy tìm biểu tượng cốc thuỷ tinh.

  3. Nhấp vào biểu tượng để mở tiện ích bổ sung. Nếu được nhắc, hãy uỷ quyền cho tiện ích bổ sung.

Không bắt buộc: Dọn dẹp

Để tránh phát sinh các khoản phí cho tài khoản của bạn, hãy xoá những tài nguyên mà bạn đã tạo:

  1. Gỡ cài đặt tiện ích bổ sung khỏi Tài khoản Google của bạn:

    gcloud workspace-add-ons deployments uninstall quickstart
    
  2. Để tránh bị tính phí cho các tài nguyên được dùng trong hướng dẫn bắt đầu nhanh này, hãy xoá dự án trên Cloud:

    gcloud projects delete PROJECT_ID
    

    Thay PROJECT_ID bằng mã dự án trên Google Cloud mà bạn đã dùng cho hướng dẫn bắt đầu nhanh. Bạn có thể tìm thấy mã dự án trên Cloud trong Google Cloud Console trên trang Trang tổng quan.

Để thêm nhiều tính năng hơn vào tiện ích bổ sung Google Workspace, hãy tham khảo những thông tin sau: