Kính ngắm

Người dùng phải cho phép các tiện ích bổ sung và ứng dụng khác truy cập vào dữ liệu của họ hoặc thay mặt họ thực hiện hành động. Khi người dùng chạy một tiện ích lần đầu tiên, giao diện người dùng của tiện ích sẽ hiển thị lời nhắc uỷ quyền để bắt đầu quy trình uỷ quyền.

Trong quy trình này, lời nhắc sẽ cho người dùng biết ứng dụng muốn được phép làm gì. Ví dụ: một tiện ích bổ sung có thể muốn được phép đọc email của người dùng hoặc tạo sự kiện trong lịch của họ. Dự án tập lệnh của tiện ích bổ sung xác định các quyền riêng lẻ này là phạm vi OAuth.

Bạn khai báo phạm vi trong tệp kê khai bằng cách sử dụng chuỗi URL. Trong quy trình uỷ quyền, Apps Script sẽ hiển thị cho người dùng nội dung mô tả phạm vi mà con người có thể đọc được. Ví dụ: tiện ích bổ sung Google Workspace của bạn có thể sử dụng phạm vi "Đọc thư hiện tại". Phạm vi này được viết trong tệp kê khai dưới dạng https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Trong quy trình uỷ quyền, một tiện ích bổ sung có phạm vi này sẽ yêu cầu người dùng cho phép tiện ích bổ sung: Xem email của bạn khi tiện ích bổ sung đang chạy.

Xem phạm vi

Bạn có thể xem các phạm vi mà dự án tập lệnh của mình hiện yêu cầu bằng cách làm như sau:

1. Mở dự án tập lệnh.
2. Ở bên trái, hãy nhấp vào biểu tượng Tổng quan info_outline.
3. Xem các phạm vi trong phần "Phạm vi OAuth của dự án".

Bạn cũng có thể xem phạm vi hiện tại của dự án tập lệnh trong tệp kê khai dự án, trong trường oauthScopes, nhưng chỉ khi bạn đã đặt các phạm vi đó một cách rõ ràng.

Đặt phạm vi tường minh

Apps Script tự động xác định phạm vi mà tập lệnh cần bằng cách quét mã của tập lệnh để tìm các lệnh gọi hàm yêu cầu phạm vi đó. Đối với hầu hết các tập lệnh, điều này là đủ và giúp bạn tiết kiệm thời gian, nhưng đối với các tiện ích bổ sung đã xuất bản, bạn nên kiểm soát trực tiếp hơn các phạm vi.

Ví dụ: theo mặc định, Apps Script có thể cấp cho dự án tập lệnh bổ sung phạm vi rất cởi mở https://mail.google.com. Khi người dùng uỷ quyền cho một dự án tập lệnh có phạm vi này, dự án đó sẽ được cấp toàn quyền truy cập vào tài khoản Gmail của người dùng. Đối với các tiện ích bổ sung đã phát hành, bạn phải thay thế phạm vi này bằng một tập hợp hạn chế hơn, chỉ bao gồm các nhu cầu của tiện ích bổ sung và không được vượt quá phạm vi đó.

Bạn có thể thiết lập rõ ràng các phạm vi mà dự án tập lệnh sử dụng bằng cách chỉnh sửa tệp tệp kê khai. Trường tệp kê khai oauthScopes là một mảng gồm tất cả các phạm vi mà tiện ích bổ sung sử dụng. Để đặt phạm vi của dự án, hãy làm như sau:

1. Xem các phạm vi mà tiện ích bổ sung của bạn hiện đang sử dụng. Xác định những thay đổi cần thực hiện, chẳng hạn như sử dụng phạm vi hẹp hơn.
2. Mở tệp kê khai của tiện ích bổ sung.
3. Tìm trường cấp cao nhất có nhãn oauthScopes. Nếu không có, bạn có thể thêm.

4. Trường oauthScopes chỉ định một mảng chuỗi. Để đặt phạm vi mà dự án của bạn sử dụng, hãy thay thế nội dung của mảng này bằng phạm vi mà bạn muốn dự án sử dụng. Ví dụ: đối với một tiện ích bổ sung của Google Workspace mở rộng Gmail, bạn có thể có các thông tin sau:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. Lưu các thay đổi đối với tệp kê khai.

Xác minh OAuth

Việc sử dụng một số phạm vi OAuth nhạy cảm có thể yêu cầu tiện ích bổ sung của bạn phải trải qua quy trình xác minh ứng dụng OAuth thì bạn mới có thể phát hành tiện ích bổ sung đó. Để biết thêm thông tin chi tiết, vui lòng xem hướng dẫn dưới đây:

• Xác minh ứng dụng OAuth cho Apps Script
• Ứng dụng chưa được xác minh
• Câu hỏi thường gặp về quy trình xác minh OAuth
• Dịch vụ API của Google: Chính sách dữ liệu người dùng

Phạm vi bị hạn chế

Một số phạm vi nhất định bị hạn chế và phải tuân theo các quy tắc bổ sung giúp bảo vệ dữ liệu người dùng. Nếu bạn dự định phát hành một tiện ích bổ sung cho Gmail hoặc Trình chỉnh sửa sử dụng một hoặc nhiều phạm vi bị hạn chế, thì tiện ích bổ sung đó phải tuân thủ tất cả các quy định hạn chế đã chỉ định thì mới có thể phát hành.

Xem danh sách đầy đủ các phạm vi bị hạn chế trước khi bạn cố gắng xuất bản. Nếu tiện ích bổ sung của bạn sử dụng bất kỳ API nào trong số này, bạn phải tuân thủ Các yêu cầu bổ sung đối với phạm vi API cụ thể trước khi phát hành.

Chọn phạm vi cho tiện ích bổ sung của Google Workspace

Các phần sau đây cung cấp các phạm vi thường dùng cho các tiện ích bổ sung của Google Workspace.

Phạm vi của trình chỉnh sửa

Dưới đây là các phạm vi thường dùng cho tiện ích bổ sung của Google Workspace mở rộng Tài liệu, Trang tính và Trang trình bày.

Gmail

Có một số phạm vi được tạo riêng cho các tiện ích bổ sung của Google Workspace để giúp bảo vệ dữ liệu của người dùng trên Gmail. Bạn phải thêm rõ ràng các phạm vi này vào tệp kê khai tiện ích bổ sung, cùng với mọi phạm vi khác mà mã tiện ích bổ sung yêu cầu.

Dưới đây là các phạm vi thường dùng cho tiện ích bổ sung Google Workspace mở rộng Gmail; bạn phải thêm các phạm vi có nhãn Bắt buộc vào tệp kê khai tiện ích bổ sung Google Workspace nếu tiện ích bổ sung của bạn mở rộng Gmail.

Ngoài ra, hãy nhớ thay thế phạm vi https://mail.google.com rất rộng trong tiện ích bổ sung bằng một nhóm phạm vi hẹp hơn cho phép các lượt tương tác mà tiện ích bổ sung cần và không hơn thế.

Phạm vi của Lịch Google

Dưới đây là các phạm vi thường dùng cho các tiện ích bổ sung của Google Workspace mở rộng Lịch Google.

Phạm vi của Google Chat

Để gọi API Chat, bạn phải xác thực dưới dạng người dùng Google Chat hoặc ứng dụng Chat. Mỗi loại xác thực yêu cầu các phạm vi khác nhau và không phải tất cả các phương thức API Chat đều hỗ trợ xác thực ứng dụng.

Để tìm hiểu thêm về các phạm vi Chat và loại xác thực, hãy xem phần Tổng quan về xác thực và uỷ quyền trong Chat API

Bảng sau đây cho thấy các phương thức và phạm vi API Chat thường dùng dựa trên các loại xác thực được hỗ trợ:

Phạm vi của Google Drive

Dưới đây là các phạm vi thường dùng cho các tiện ích bổ sung của Google Workspace mở rộng Google Drive.

Mã truy cập

Để bảo vệ dữ liệu người dùng, các phạm vi Gmail được sử dụng trong các tiện ích bổ sung của Google Workspace chỉ cấp quyền truy cập tạm thời vào dữ liệu người dùng. Để bật quyền truy cập tạm thời, bạn phải gọi hàm GmailApp.setCurrentMessageAccessToken(accessToken) bằng mã truy cập làm đối số. Bạn phải lấy mã truy cập từ một đối tượng sự kiện hành động.

Sau đây là ví dụ về cách đặt mã truy cập để cho phép truy cập vào siêu dữ liệu của một thông báo. Phạm vi duy nhất cần thiết cho ví dụ này là https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Các phạm vi khác của Google Workspace

Tiện ích bổ sung của bạn có thể yêu cầu thêm phạm vi nếu sử dụng các dịch vụ khác của Google Workspace hoặc Apps Script. Trong hầu hết trường hợp, bạn có thể để Apps Script phát hiện các phạm vi này và tự động cập nhật tệp kê khai. Khi chỉnh sửa danh sách phạm vi của tệp kê khai, đừng xoá bất kỳ phạm vi nào trừ phi bạn thay thế các phạm vi đó bằng một phạm vi thay thế phù hợp hơn, chẳng hạn như một phạm vi hẹp hơn.

Bảng sau đây cho thấy danh sách các phạm vi mà các tiện ích bổ sung của Google Workspace thường sử dụng: