Kính ngắm

Người dùng phải uỷ quyền cho 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 hành động thay mặt họ. Khi người dùng chạy một tiện ích bổ sung lần đầu tiên, giao diện người dùng 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 làm gì. Ví dụ: một tiện ích bổ sung có thể muốn có quyền đọc thư 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à các 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 hiển thị cho người dùng thông tin mô tả về phạm vi mà người dùng có thể đọc được. Ví dụ: Tiện ích bổ sung của 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, 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.

Phạm vi xem

Bạn có thể xem các phạm vi mà dự án tập lệnh của bạn 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 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 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 thực hiện nhiều quyền kiểm soát hơn đối với các phạm vi.

Ví dụ: Apps Script có thể cung cấp một dự án tập lệnh tiện ích bổ sung về phạm vi rất rộng https://mail.google.com theo mặc định. 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 có giới hạn hơn để đáp ứng nhu cầu của tiện ích bổ sung và không còn nữa.

Bạn có thể đặt rõ 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 của 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 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 nó không 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 mở rộng Gmail, bạn có thể có:

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

Để sử dụng một số phạm vi OAuth nhạy cảm, bạn có thể phải vượt qua quy trình xác minh ứng dụng OAuth trước khi 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 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 định phát hành một Tiện ích bổ sung 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 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 bạn cố gắng phát hành. Nếu tiện ích bổ sung của bạn sử dụng bất kỳ tiện ích nào trong số đó, bạn phải tuân thủ Các 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à các phạm vi thường dùng cho 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 của 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 bạn đặt trường tệp kê khai addOns.calendar.eventAccess 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 bạn đặt trường tệp kê khai addOns.calendar.eventAccess thành WRITE hoặc READ_WRITE.

Phạm vi lái xe

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 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 mục trong Drive. Cho phép tiện ích bổ sung đọc siêu dữ liệu có 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 của biểu tượng và tiện ích bổ sung có quyền truy cập mục đó.

Truy cập theo tệp https://www.googleapis.com/auth/drive.file

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

Xem Ví dụ về yêu cầu quyền truy cập vào các tệp đã chọn.

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

Có một số phạm vi được tạo riêng 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 mọi phạm vi khác mà mã tiện ích bổ sung của bạn yêu cầu.

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 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 của 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 lượt tương tác mà tiện ích bổ sung của bạn cần và 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 trình kích hoạt hành động soạn thư. Cho phép tiện ích bổ sung tạm thời tạo tin nhắn nháp và tin nhắn trả lời. 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 dùng với các thao tác soạn. Yêu cầu phải có mã truy cập.

Đọc siêu dữ liệu tin nhắn 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 tin nhắn mở (chẳng hạn như chủ đề hoặc người nhận). Không cho phép đọc nội dung thông báo 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 trình kích hoạt hành động soạn thư. Đối với các hành động soạn, phạm vi này là bắt buộc nếu trình kích hoạt soạn cần truy cập vào siêu dữ liệu. Trong thực tế, phạm vi này cho phép Compose kích hoạt danh sách người nhận truy cập (to:, cc: và bcc:) thư nháp trả lời email.

Đọ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 khi người dùng tương tác, chẳng hạn như khi chọn một mục trong trình đơn bổ sung. Yêu cầu phải có mã truy cập.

Đọc nội dung của chuỗi tin nhắn đ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ư mở. Đồng thời, cấp quyền truy cập vào nội dung của các tin nhắn khác trong chuỗi mở. Yêu cầu phải có mã truy cập.

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

Đọc mọi siêu dữ liệu và nội dung 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 tiến hành truy vấn tìm kiếm hoặc đọc toàn bộ chuỗi thư.

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 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. Để cho phép 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.

Dưới đâ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 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 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.

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

Bắt buộc nếu tiện ích bổ sung truy cập API Apps Script Docs. 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 vào tệp Trang tính hiện tại https://www.googleapis.com/auth/spreadsheets.currentonly

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

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

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

Truy cập theo tệp https://www.googleapis.com/auth/drive.file

Bắt buộc để tiện ích bổ sung sử dụng onFileScopeGrantedTrigger và nếu tiện ích bổ sung truy cập API API Tài liệu, Trang tính, Trang trình bày hoặc Drive. Cấp quyền truy cập trên mỗi tệp cho các tệp do ứng dụng tạo hoặc mở bằng cách sử dụng Dịch vụ Drive nâng cao của Apps Script. Tuy nhiên, việc này không cho phép dùng các thao tác tương tự bằng cách sử dụng dịch vụ Drive cơ bản. Hoạt động ủy quyền tệp được cấp trên cơ sở từng tệp và bị thu hồi khi người dùng huỷ ủy quyền ứ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 phạm vi bổ sung nếu sử dụng các dịch vụ Apps Script khác. Trong hầu hết các 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, bạn đừng xoá bất kỳ phạm vi nào trừ phi bạn đang thay thế các phạm vi đó bằng một phạm vi thay thế thích 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 các 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 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 thực hiện các yêu cầu UrlFetch. Việc này cũng là bắt buộc nếu dự án sử dụng thư viện OAuth2 cho Apps Script.

Đọc múi giờ và ngôn ngữ 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. Vui lòng xem phần Truy cập vào múi giờ và ngôn ngữ của người dùng để biết thêm 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 trình kích hoạt.