Trang này được dịch bởi Cloud Translation API.

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 thay mặt họ 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ẽ đưa ra 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 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 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 từng quyền này dưới dạng phạm vi OAuth.

Bạn khai báo các phạm vi trong tệp kê khai bằng cách sử dụng các chuỗi URL. Trong quy trình uỷ quyền, Apps Script sẽ trình bày cho người dùng nội dung mô tả dễ đọc về phạm vi. 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 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, 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 thư 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 thực hiện các bước sau:

Mở dự án tập lệnh.
Ở bên trái, hãy nhấp vào Tổng quan .
Xem các phạm vi trong phần "Project OAuth Scopes" (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 tường minh

Apps Script tự động xác định những phạm vi mà một 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 kiểm soát trực tiếp hơn đối với các phạm vi.

Ví dụ: Apps Script có thể cấp cho dự án tập lệnh tiện ích bổ sung phạm vi https://mail.google.com rất cho phép 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 đã xuất bản, bạn phải thay thế phạm vi này bằng một tập hợp hạn chế hơn để đáp ứng nhu cầu của tiện ích bổ sung và không hơn.

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ử dụng bằng cách chỉnh sửa tệp manifest (tệp kê khai) của dự án đó. 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 cho dự án, hãy làm như sau:

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.
Mở tệp kê khai của tiện ích bổ sung.
Tìm trường cấp cao nhất có nhãn oauthScopes. Nếu không có, bạn có thể thêm.
Trường oauthScopes chỉ định một mảng gồm các 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 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ó những thông tin sau:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
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 trước khi bạn có thể xuất bản tiện ích đó. Để 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 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 xuất bản một tiện ích bổ sung cho Gmail hoặc Editor 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ế được chỉ định trước khi có thể xuất bản.

Hãy xem danh sách đầy đủ các phạm vi bị hạn chế trước khi bạn tìm cách xuất bản. Nếu tiện ích bổ sung của bạn sử dụng bất kỳ phạm vi nào trong số này, thì 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 xuất bản.

Tiện ích Google Workspace Developer Tools cho Visual Studio Code cung cấp thông tin chẩn đoán cho tất cả các phạm vi, bao gồm cả nội dung mô tả phạm vi và liệu phạm vi đó có nhạy cảm hay bị hạn chế hay không.

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

Các phần sau đây cung cấp những phạm vi thường được dùng cho tiện ích bổ sung 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 giúp mở rộng Tài liệu, Trang tính và Trang trình bày.

Lưu ý: Phạm vi currentonly chỉ có trong Dịch vụ Apps Script. Quy tắc này không áp dụng cho Dịch vụ nâng cao của Apps Script hoặc các lệnh gọi trực tiếp đến API Google Workspace.

Phạm vi
Quyền truy cập vào tệp Docs 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 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 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 công khai.
Quyền truy cập vào tệp 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 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 công khai.
Quyền truy cập theo từng 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 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 từng tệp đối với 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, điều này không cho 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 đối với tệp được cấp cho từng tệp và sẽ bị thu hồi khi người dùng huỷ uỷ 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 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 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 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 Google Workspace mở rộng Gmail; những phạm vi được gắn nhãn Bắt buộc phải được thêm 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.

Đừng quên 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 nhóm 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 và không hơn thế nữa.

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 các trình kích hoạt thao tác soạn thư. Cho phép tiện ích bổ sung tạm thời tạo tin nhắn và thư trả lời nháp mới. Hãy xem phần Soạn thảo 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ư. Cần có mã truy cập.
Đọc siêu dữ liệu về 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 thư chưa 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 các trình kích hoạt thao tác soạn thư. Đối với hành động soạn thư, phạm vi này là bắt buộc nếu một trình kích hoạt soạn thư cần có 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 thành phần kích hoạt truy cập vào danh sách người nhận (đến:, cc: và bcc:) của một bản nháp email trả lời.
Đọ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ư mở khi người dùng tương tác, chẳng hạn như khi người dùng chọn một mục trong trình đơn tiện ích bổ sung. Cần có mã truy cập.
Đọc nội dung trong chuỗi thảo luận 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ở. Cũng 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ở. Cần có 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, kể cả thư 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ộ chuỗi thư. Cảnh báo: Đây là một phạm vi bị hạn chế rất rộng. Chỉ sử dụng nếu thực sự cần thiết.

Phạm vi của Lịch Google

Dưới đây là các phạm vi thường dùng cho tiện ích bổ sung 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ó 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ó 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 Chat

Để gọi Chat API, bạn phải xác thực với tư cách là 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 phương thức Chat API nào cũng hỗ trợ xác thực ứng dụng.

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

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

Phương thức	Hỗ trợ xác thực ứng dụng	Các phạm vi uỷ quyền được hỗ trợ
Gửi tin nhắn		Với Xác thực người dùng: `chat.messages.create` `chat.messages` `chat.import` Với tính năng Xác thực ứng dụng: `chat.bot`
Tạo không gian		Với Xác thực người dùng: `chat.spaces.create` `chat.spaces` `chat.import` Với tính năng Xác thực ứng dụng và phê duyệt của quản trị viên (có trong Bản dùng thử cho nhà phát triển): `chat.app.spaces.create` `chat.app.spaces`
Tạo và thêm thành viên vào không gian	—	Với Xác thực người dùng: `chat.spaces.create` `chat.spaces`
Thêm người dùng vào không gian		Với Xác thực người dùng: `chat.memberships` `chat.memberships.app` `chat.import` Với tính năng Xác thực ứng dụng và phê duyệt của quản trị viên (có trong Bản dùng thử cho nhà phát triển): `chat.app.memberships`
Liệt kê các hoạt động hoặc sự kiện trong một không gian trên Chat	—	Với Xác thực người dùng, bạn phải sử dụng một phạm vi cho mỗi kiểu sự kiện có trong yêu cầu: Đối với các sự kiện về tin nhắn: `chat.messages` `chat.messages.readonly` Đối với các sự kiện về lượt thể hiện cảm xúc: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` Đối với sự kiện về gói hội viên: `chat.memberships` `chat.memberships.readonly` Đối với các sự kiện về không gian: `chat.spaces` `chat.spaces.readonly`

Phạm vi của Google Drive

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

Phạm vi

Đọc siêu dữ liệu của mục đã chọn

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 một 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 đọ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 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 chọn phương pháp này 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 cho từng tệp đối với 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, điều này không cho 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 cho tệp được cấp trên cơ sở từng tệp và sẽ bị thu hồi khi người dùng huỷ uỷ quyền cho ứ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.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

Bắt buộc nếu tiện ích bổ sung triển khai một 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 đọ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 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 chọn phương pháp này 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 cho từng tệp đối với 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, điều này không cho 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 cho tệp được cấp trên cơ sở từng tệp và sẽ bị thu hồi khi người dùng huỷ uỷ quyền cho ứ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 dùng trong tiện ích bổ sung 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 thao tác.

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 các phạm vi bổ sung 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ể 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ế chúng bằng một lựa chọn 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 Google Workspace thường 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 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`. Bạn cũng cần phải làm như vậ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ờ hiện tại của người dùng. 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 các trình kích hoạt .
Xem trước đường liên kết đến dịch vụ 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 các đường liên kết từ một dịch vụ bên thứ ba. Cho phép dự án xem một đường liên kết trong một ứng dụng của 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 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 Google Workspace. Để tìm hiểu thêm, hãy xem bài viết Tạo tài nguyên của bên thứ ba bằng trình đơn @.