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 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 luồng 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 manifest 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 ghi trong tệp kê khai của bạn 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 .
  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 manifest. 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:

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 thủ 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 Tiện ích 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.

Phạm vi
Quyền 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 vào API Tài liệu 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 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 vào API Trang tính của Apps Script. 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 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 của 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 đang mở.

Quyền truy cập trên mỗi tệp https://www.googleapis.com/auth/drive.file

Bắt buộc đối với tiện ích bổ sung để sử dụng onFileScopeGrantedTrigger và nếu tiện ích bổ sung truy cập vào API Tài liệu, Trang tính, Trang trình bày hoặc Drive. Cấp quyền truy cập cho mỗi tệp vào 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, bạn không được phép sử dụng các thao tác tương tự bằng dịch vụ Drive cơ bản. Quyền truy cập vào 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.

Gmail

Có một số phạm vi được tạo riêng cho các Tiện ích 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
Tạo bản thảo 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 Compose. Cho phép tiện ích bổ sung tạm thời tạo thư nháp và thư trả lời mới. Hãy xem phần Thành 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 các thao tác soạn thư. Yêu cầu 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ư đang mở (chẳng hạn như chủ đề hoặc người nhận). Không cho phép đọc nội dung thư 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 trong Compose. Đối với hành động trong Compose, bạn bắt buộc phải có phạm vi này nếu trình kích hoạt trong Compose cần quyền truy cập vào siêu dữ liệu. Trong thực tế, phạm vi này cho phép một trình soạn thư kích hoạt quyền truy cập vào danh sách người nhận (to:, cc: và bcc:) của email trả lời nháp.

Đọc nội dung tin nhắn đang 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ư đang mở khi người dùng tương tác, chẳng hạn như khi chọn một mục trình đơn tiện ích bổ sung. Yêu cầu 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ư đang 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 tin nhắn đang mở. Yêu cầu mã truy cập.

Đọc mọi nội dung và siêu dữ liệu của 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 thực hiện truy vấn tìm kiếm hoặc đọc toàn bộ chuỗi 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
Truy cập 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 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 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.

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 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ỉ được giới hạn ở mã nhận dạng, tiêu đề, loại MIME, URL biểu tượng của mục và liệu tiện ích bổ sung có quyền truy cập vào mục đó hay không.

Quyền truy cập trên mỗi tệp https://www.googleapis.com/auth/drive.file

Bạn nên chọn phương thức này 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 cho mỗi tệp vào 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, bạn không được phép sử dụng các thao tác tương tự bằng dịch vụ Drive cơ bản. Quyền 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ỷ uỷ quyền ứng dụng.

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

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. Để 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à Tiện ích bổ sung của Google Workspace thường sử dụng:

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 các lệnh gọi đến 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. Bạn cũng cần phải làm việc này nếu dự án sử dụng thư viện OAuth2 cho 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. Hãy xem phần 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 trình 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 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 một đường liên kết trong ứng dụng Google Workspace trong khi người dùng đang tương tác với đường liên kết đó. Để tìm hiểu thêm, hãy xem phần 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 đường liên kết đến tài nguyên đó trong một ứng dụng Google Workspace. Để tìm hiểu thêm, hãy xem phần Tạo tài nguyên của bên thứ ba từ trình đơn @.