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 hành động thay mặt cho họ. 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 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 cho người dùng biết ứng dụng muốn gì quyền làm những gì. Ví dụ: một tiện ích bổ sung có thể muốn có quyền đọc nội dung email của người dùng hoặc tạo sự kiện trong lịch của họ. Tập lệnh của tiện ích bổ sung dự án xác định các quyền riêng lẻ này dưới dạng các phạm vi của 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ị
nội dung mô tả phạm vi mà con người có thể đọc được. Ví dụ: Tiện ích bổ sung của Google Workspace
có thể sử dụng thông báo "Đọc tin nhắn 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 ủy 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 cho: 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 đang yêu cầu bằng cách thực hiện 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 "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 oauthScopes
mà chỉ khi bạn đặt một cách rõ ràng các phạm vi đó.
Đặt phạm vi rõ ràng
Apps Script tự động xác định phạm vi mà một tập lệnh cần bằng cách quét mã cho các lệnh gọi hàm cần đến chúng. Đối với hầu hết các tập lệnh, đây là vừa đủ và tiết kiệm thời gian cho bạn, nhưng đối với các tiện ích bổ sung được xuất bản, bạn nên tập quyền kiểm soát trực tiếp hơn đối với phạm vi.
Ví dụ: Apps Script có thể cho phép dự án tập lệnh tiện ích bổ sung không bắt buộc
phạm vi https://mail.google.com theo mặc định. Khi người dùng cho phép một 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 Gmail của người dùng
tài khoản. Đối với 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 có giới hạn bao gồm nhu cầu của các tiện ích bổ sung và không hơn nữa.
Bạn có thể đặt rõ phạm vi mà dự án tập lệnh của mình sẽ sử dụng bằng cách chỉnh sửa
tệp kê khai. Trường tệp kê khai
oauthScopes là một mảng
tất cả phạm vi mà tiện ích bổ sung sử dụng. Để đặt phạm vi cho dự án, hãy thực hiện
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 xem cần thực hiện thay đổi, 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ó mã này, bạn có thể thêm báo cáo đó. oauthScopeschỉ đị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 các phạm vi mà bạn muốn nó 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 tiện ích 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 nhất định có thể yêu cầu tiện ích bổ sung của bạn phải truy cập được Xác minh ứng dụng OAuth trước khi có thể xuất bản. Để 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 bằng 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 bị 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 định xuất bản 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ế, tiện ích bổ sung phải tuân thủ tất cả trước khi có thể xuất bản.
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ỳ quy tắc nào trong số đó, bạn phải tuân thủ với Các yêu cầu khác đối với những phạm vi API cụ thể trước khi xuất bản.
Phạm vi lịch
Dưới đây là các phạm vi thường được dùng cho những tiện ích bổ sung của Google Workspace giúp 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 |
| 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 |
Phạm vi trên Drive
Dưới đây là các phạm vi thường được dùng cho các tiện ích bổ sung của Google Workspace giúp 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 bối cảnh đã 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ề những mặt hàng mà người dùng có đã chọn trong Google Drive. Siêu dữ liệu bị giới hạn ở ID của mục, tiêu đề, loại MIME, URL biểu tượng và liệu tiện ích bổ sung có quyền truy cập truy cập vào mục này. |
| Quyền truy cập theo từng 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 Drive
tệp.
Cấp quyền truy cập theo từng tệp vào các tệp do ứng dụng tạo hoặc mở, bằng cách sử dụng
Drive nâng cao của Apps Script
Dịch vụ. Điều này không cho phép sử dụng các hành động tương tự bằng cách sử dụng
dịch vụ Drive cơ bản,
Tuy nhiên. Quyền truy cập tệp được cấp cho từng tệp và
bị thu hồi khi người dùng hủy cấp quyền ứng dụng. |
Phạm vi tiện ích bổ sung dành cho Gmail
Có một vài phạm vi được tạo riêng cho Tiện ích bổ sung của Google Workspace giúp bảo vệ 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ủa bạn, cùng với bất kỳ tệp kê khai nào khác cần có mã tiện ích bổ sung.
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 có mở rộng Gmail; bạn phải thêm các mục 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.
Hãy nhớ thay thế phạm vi https://mail.google.com rất rộng trong
tiện ích bổ sung có nhóm phạm vi hẹp hơn cho phép tương tác mà tiện ích bổ sung của bạn
nhu cầu và không còn nhu cầu khác.
| 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 đ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 thư nháp mới và trả lời. Xem Soạn tin nhắn nháp để biết thông tin chi tiết; Phạm vi này cũng thường được sử dụng với Compose actions. Cần có mã truy cập. |
| Đọc siêu dữ liệu của thư đang 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ông báo mở (chẳng hạn như
chủ đề 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 thao tác Compose điều kiện kích hoạt. Dành cho Compose actions, phạm vi này là bắt buộc nếu điều kiện kích hoạt 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 Compose kích hoạt danh sách người nhận truy cập (to:, cc: và bcc:) của thư trả lời email nháp. |
| Đọc nội dung thư đ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ô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 trong trình đơn tiện ích bổ sung. Cần có quyền truy cập mã thông báo. |
| Đọc nội dung chuỗi mở |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
Cấp quyền truy cập tạm thời vào nội dung và siêu dữ liệu của thông báo đang mở. Đồng thời cấp quyền truy cập vào nội dung của các thư khác trong công cụ chuỗi. Cần có mã truy cập. |
| Đọc mọi nội dung và siêu dữ liệu của thư |
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 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, các phạm vi của Gmail được sử dụng trong
Chỉ cấp quyền truy cập vào các tiện ích bổ sung của Google Workspace
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
hàm GmailApp.setCurrentMessageAccessToken(accessToken)
sử dụng mã truy cập làm đối số. Bạn phải lấy mã truy cập 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ư. 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 người chỉnh sửa
Dưới đây là các phạm vi thường được dùng cho các 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 tập lệnh 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 Trang tính 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 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 |
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à cập nhật tệp kê khai tự động. Khi chỉnh sửa danh sách phạm vi của tệp kê khai, không xoá bất kỳ phạm vi nào trừ phi bạn đang thay thế chúng bằng một phạm vi phù hợp hơn, chẳng hạn như phạm vi hẹp hơn.
Sau đây là danh sách các phạm vi Apps Script thường dùng trong 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 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 tạo
|
| Đọ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 biết ngôn ngữ và múi giờ của người dùng hiện tại. Xem 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 bổ sung xem trước đường liên kết từ một dịch vụ bên thứ ba. Cho phép dự án thấy 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 dụng đó. Để tìm hiểu thêm, hãy xem 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ụ 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 ứng dụng Google Workspace. Để tìm hiểu thêm, hãy xem Tạo tài nguyên bên thứ ba qua trình đơn @. |