Kính ngắm

Người dùng phải cho phép tiện ích bổ sung và các ứng dụng khác truy cập vào dữ liệu của họ hoặc hành động thay mặt cho tiện ích bổ sung và ứng dụng khác. Khi người dùng chạy tiện ích bổ sung lần đầu tiên, giao diện người dùng của tiện ích bổ sung 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ó quyền làm gì. Ví dụ: một tiện ích bổ sung có thể muốn có quyền đọ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 luồng uỷ quyền, Apps Script sẽ hiển thị cho người dùng nội dung mô tả về phạm vi mà con người có thể đọc được. Ví dụ: Tiện ích bổ sung Google Workspace có thể sử dụng phạm vi "Đọc thông báo hiện tại" đượ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, 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.

Phạm vi xem

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 .
  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 các 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 rõ ràng

Apps Script tự động xác định những phạm vi mà tập lệnh cần bằng cách quét mã của tập lệnh đó cho các lệnh gọi hàm yêu cầu những 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. Tuy nhiên, đối với các tiện ích bổ sung đã phát hành, bạn nên kiểm soát phạm vi trực tiếp nhiều hơn.

Ví dụ: Theo mặc định, Apps Script có thể cung cấp cho dự án tập lệnh tiện ích bổ sung phạm vi https://mail.google.com rất thoải mái. Khi người dùng uỷ quyền cho 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 nhóm có giới hạn hơn đáp ứng nhu cầu của tiện ích bổ sung đã phát hành.

Bạn có thể đặt rõ ràng các phạm vi mà dự án tập lệnh của bạn sẽ 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 đ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 một 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 chưa có, bạn có thể thêm nó.
  4. Trường oauthScopes chỉ định một mảng chuỗi. Để đặt các 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 các phạm vi mà bạn muốn sử dụng. Ví dụ: Đối với một Tiện ích bổ sung của Google Workspace giúp mở rộng Gmail, bạn có thể:

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

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

Phạm vi bị hạn chế

Một số phạm vi nhất định được hạn chế và 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 dành 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 trước khi có thể phát hành.

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

Phạm vi lịch

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

Phạm vi
Truy cập vào siêu dữ liệu sự kiện https://www.googleapis.com/auth/calendar.addons.execute

Bắt buộc nếu tiện ích bổ sung truy cập vào siêu dữ liệu sự kiện trên Lịch. Cho phép tiện ích bổ sung truy cập vào siêu dữ liệu sự kiện.

Đọc dữ liệu sự kiện do người dùng tạo https://www.googleapis.com/auth/calendar.addons.current.event.read

Bắt buộc nếu tiện ích bổ sung cần đọc dữ liệu sự kiện do người dùng tạo. Cho phép tiện ích bổ sung truy cập vào dữ liệu sự kiện do người dùng tạo. Dữ liệu này chỉ có sẵn nếu trường tệp kê khai addOns.calendar.eventAccess được đặt thành READ hoặc READ_WRITE.

Ghi dữ liệu sự kiện do người dùng tạo https://www.googleapis.com/auth/calendar.addons.current.event.write

Bắt buộc nếu tiện ích bổ sung cần ghi dữ liệu sự kiện do người dùng tạo. Cho phép tiện ích bổ sung chỉnh sửa dữ liệu sự kiện do người dùng tạo. Dữ liệu này chỉ có sẵn nếu trường tệp kê khai addOns.calendar.eventAccess được đặt thành WRITE hoặc READ_WRITE.

Phạm vi trên Drive

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

Phạm vi
Đọc siêu dữ liệu của mục đã chọn https://www.googleapis.com/auth/drive.addons.metadata.readonly

Bắt buộc nếu tiện ích bổ sung triển khai giao diện theo ngữ cảnh được kích hoạt khi người dùng chọn các mục trong Drive. Cho phép tiện ích bổ sung đọc siêu dữ liệu giới hạn về các mục mà người dùng đã chọn trong Google Drive. Siêu dữ liệu chỉ giới hạn ở mã nhận dạng, tiêu đề, loại MIME, URL biểu tượng của mục và việc tiện ích bổ sung có quyền truy cập vào mục đó hay không.

Quyền truy cập theo từng tệp https://www.googleapis.com/auth/drive.file

Bạn nên sử dụng nếu tiện ích bổ sung cần truy cập vào từng tệp riêng lẻ trên Drive. Cấp quyền truy cập vào các tệp do ứng dụng tạo hoặc mở cho mỗi tệp, bằng Dịch vụ Drive nâng cao của Apps Script. Tuy nhiên, thao tác này không cho phép sử dụng các thao tác tương tự thông qua dịch vụ Drive cơ bản. Hoạt động uỷ quyền cho tệp được cấp cho từng tệp và sẽ bị thu hồi khi người dùng huỷ cấp quyền cho ứng dụng.

Hãy xem ví dụ về Yêu cầu quyền truy cập vào tệp đối với các tệp đã chọn.

Phạm vi của tiện ích bổ sung trong Gmail

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

Dưới đây là các phạm vi được dùng thường xuyên cho Tiện ích bổ sung của Google Workspace mở rộng cho Gmail. Bạn phải thêm những tiện ích bổ sung có nhãn Bắt buộc vào tệp kê khai Tiện ích bổ sung trên 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 của bạn bằng một phạm vi hẹp hơn cho phép các hoạt động tương tác mà tiện ích bổ sung của bạn cần mà không cần nữa.

Phạm vi
Tạo bản nháp mới https://www.googleapis.com/auth/gmail.addons.current.action.compose

Bắt buộc nếu tiện ích bổ sung sử dụng điều kiện kích hoạt hành động Compose. Cho phép tiện ích bổ sung tạm thời tạo tin nhắn và câu trả lời nháp mới. Hãy xem phần Soạn thư nháp để biết thông tin chi tiết; phạm vi này cũng thường được dùng với hành động soạn thư. Cần có mã truy cập.

Đọc siêu dữ liệu của thư mở https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Cấp quyền truy cập tạm thời vào siêu dữ liệu của thư mở (chẳng hạn như tiêu đề hoặc người nhận). Không cho phép đọc nội dung tin nhắn và yêu cầu mã truy cập.

Bắt buộc nếu tiện ích bổ sung sử dụng siêu dữ liệu trong các điều kiện kích hoạt hành động trong Compose. Đối với các thao tác Compose, phạm vi này là bắt buộc nếu một điều kiện kích hoạt Compose cần quyền truy cập vào siêu dữ liệu. Trên thực tế, phạm vi này cho phép Compose kích hoạt danh sách người nhận (to:, cc: và bcc:) của email trả lời nháp.

Đọc nội dung thư mở https://www.googleapis.com/auth/gmail.addons.current.message.action

Cấp quyền truy cập vào nội dung của thông báo mở khi người dùng tương tác, chẳng hạn như khi chọn một mục trên trình đơn tiện ích bổ sung. Yêu cầu có mã truy cập.

Đọc nội dung chuỗi đang mở https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Cấp quyền truy cập tạm thời vào siêu dữ liệu và nội dung của thông báo mở. Đồng thời cấp quyền truy cập vào nội dung của các thông báo khác trong chuỗi mở. Cần có mã truy cập.

Đọc mọi siêu dữ liệu và nội dung thư https://www.googleapis.com/auth/gmail.readonly

Đọc mọi siêu dữ liệu và nội dung của email, bao gồm cả thư đang mở. Bắt buộc nếu bạn cần đọc thông tin về các thư khác, chẳng hạn như khi thực hiện một cụm từ tìm kiếm hoặc đọc toàn bộ một chuỗi thư.

Mã truy cập

Để bảo vệ dữ liệu người dùng, phạm vi của Gmail được dùng trong 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. Để cấp quyền truy cập tạm thời, bạn phải gọi hàm GmailApp.setCurrentMessageAccessToken(accessToken) bằng cách sử dụ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 thiết lập mã truy cập để cho phép truy cập vào siêu dữ liệu của 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();
}

Phạm vi chỉnh sửa

Dưới đây là các phạm vi được dùng thường xuyên 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.

Phạm vi
Quyền truy cập hiện tại vào tệp Tài liệu https://www.googleapis.com/auth/documents.currentonly

Bắt buộc nếu tiện ích bổ sung truy cập vào API Tài liệu của Apps Script. Cấp quyền truy cập tạm thời vào nội dung của tài liệu đang mở.

Quyền truy cập hiện tại vào tệp Trang tính https://www.googleapis.com/auth/spreadsheets.currentonly

Bắt buộc nếu tiện ích bổ sung truy cập vào API Apps Script Trang tính. Cấp quyền truy cập tạm thời vào nội dung của bảng tính mở.

Quyền truy cập hiện tại vào tệp Trang trình bày https://www.googleapis.com/auth/presentations.currentonly

Bắt buộc nếu tiện ích bổ sung truy cập vào API Trang trình bày Apps Script. Cấp quyền truy cập tạm thời vào nội dung của bản trình bày mở.

Quyền truy cập theo từng tệp https://www.googleapis.com/auth/drive.file

Bắt buộc nếu tiện ích bổ sung sử dụng onFileScopeGrantedTrigger và liệu tiện ích có truy cập vào API Tài liệu, Trang tính, Trang trình bày hoặc Drive hay không. Cấp quyền truy cập vào các tệp do ứng dụng tạo hoặc mở cho mỗi tệp, bằng Dịch vụ Drive nâng cao của Apps Script. Tuy nhiên, thao tác này không cho phép sử dụng các thao tác tương tự thông qua dịch vụ Drive cơ bản. Hoạt động uỷ quyền tệp được cấp trên từng tệp và bị thu hồi khi người dùng huỷ cấp quyền cho ứng dụng.

Các phạm vi khác

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ụ Apps Script khác. Trong hầu hết trường hợp, bạn có thể cho phép 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ế phạm vi đó bằng một phạm vi thay thế phù hợp hơn, chẳng hạn như phạm vi hẹp hơn.

Để tham khảo, sau đây là danh sách các phạm vi Apps Script thường được dùng kết hợp với Tiện ích bổ sung của Google Workspace:

Phạm vi
Đọc địa chỉ email của người dùng https://www.googleapis.com/auth/userinfo.email

Cho phép dự án đọc địa chỉ email của người dùng hiện tại.

Cho phép cuộc gọi đến các dịch vụ bên ngoài https://www.googleapis.com/auth/script.external_request

Cho phép dự án đưa ra các yêu cầu UrlFetch. Đây cũng là yêu cầu bắt buộc nếu dự án sử dụng thư viện OAuth2 for Apps Script.

Đọc ngôn ngữ và múi giờ của người dùng https://www.googleapis.com/auth/script.locale

Cho phép dự án tìm hiểu ngôn ngữ và múi giờ của người dùng hiện tại. Xem bài viết Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thông tin chi tiết.

Tạo trình kích hoạt https://www.googleapis.com/auth/script.scriptapp

Cho phép dự án tạo điều kiện kích hoạt.

Xem trước đường liên kết của bên thứ ba https://www.googleapis.com/auth/workspace.linkpreview

Bắt buộc nếu tiện ích bổ sung xem trước đường liên kết từ một dịch vụ của bên thứ ba. Cho phép dự án xem đường liên kết trong ứng dụng của Google Workspace khi người dùng đang tương tác với ứng dụng đó. Để tìm hiểu thêm, hãy xem bài viết Xem trước đường liên kết bằng khối thông minh.

Tạo tài nguyên của bên thứ ba https://www.googleapis.com/auth/workspace.linkcreate

Bắt buộc nếu tiện ích bổ sung tạo tài nguyên trong một dịch vụ của bên thứ ba. Cho phép dự án đọc thông tin mà người dùng gửi đến biểu mẫu tạo tài nguyên và chèn một đường liên kết đến tài nguyên trong một ứng dụng của Google Workspace. Để tìm hiểu thêm, hãy xem nội dung Tạo tài nguyên bên thứ ba từ trình đơn @.