Người dùng phải uỷ quyền cho 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 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 quy trình này, lời nhắc sẽ cho người dùng biết ứng dụng muốn được cấp quyền làm gì. Ví dụ: một tiện ích bổ sung có thể muốn được cấp 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ọ. 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 quy trình uỷ quyền, Apps Script sẽ trình bày nội dung mô tả phạm vi mà người dùng có thể đọc được. Ví dụ: tiện ích bổ sung của bạn có thể sử dụng phạm vi "Đọc tài liệu hiện tại", được viết trong tệp kê khai của bạn dưới dạng https://www.googleapis.com/auth/documents.currentonly. 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 và quản lý tài liệu mà ứng dụng này đã được cài đặt bên trong.
Các phạm vi mà Apps Script sử dụng cho nhiều dịch vụ trùng lặp với các phạm vi mà API liên quan sử dụng. Ví dụ: dịch vụ Lịch của Apps Script sử dụng nhiều phạm vi giống như API Lịch. Bạn có thể tra cứu các phạm vi mà các phương thức dịch vụ Apps Script cụ thể yêu cầu trong tài liệu tham khảo về Apps Script Apps Script.
Xem phạm vi
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 như 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 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à 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 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 tiện ích bổ sung phạm vi rất cho phép là 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 quyền truy cập đầy đủ 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 phạm vi hạn chế hơn, đáp ứng nhu cầu của tiện ích bổ sung và không nhiều 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 kê khai của dự án. Trường 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 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 trường này không có, bạn có thể thêm trường đó. Trường
oauthScopeschỉ đị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 dành cho Trình chỉnh sửa mở rộng Trang tính, bạn có thể có như sau:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/script.container.ui", "https://www.googleapis.com/auth/spreadsheets" ], ... }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 bổ sung đó. Để 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 xác minh
- Câu hỏi thường gặp về quy trình xác minh 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 dự định xuất bản 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ế được chỉ định trước khi có thể xuất bản.
Xem lại 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ỳ phạm vi nào trong số đó, thì 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 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 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.
Phạm vi tiện ích bổ sung dành cho Trình chỉnh sửa
Khi bạn tạo một tiện ích bổ sung dành cho Trình chỉnh sửa, các phạm vi bắt buộc sẽ được xác định bởi dịch vụ và phương thức Google Apps Script mà mã tiện ích bổ sung sử dụng. Ví dụ: một tiện ích bổ sung dành cho Google Trang tính có thể cần phạm vi https://www.googleapis.com/auth/spreadsheets.readonly để đọc thông tin từ nhiều Trang tính.
Apps Script tự động xác định các phạm vi mà các dịch vụ bạn sử dụng yêu cầu khi bạn thêm mã vào dự án tập lệnh. Đối với các tiện ích bổ sung dành cho Trình chỉnh sửa, bạn thường chỉ cần dựa vào tính năng thu thập phạm vi tự động này thay vì tự xác định phạm vi và đặt phạm vi một cách rõ ràng.
Nếu bạn không đặt phạm vi một cách rõ ràng và tiện ích bổ sung dành cho Trình chỉnh sửa của bạn chỉ đọc hoặc ghi vào tệp trình chỉnh sửa đang mở, hãy thêm nhận xét sau vào một trong các tệp dự án tập lệnh:
/**
* @OnlyCurrentDoc
*/
Nhận xét này yêu cầu Apps Script thu hẹp phạm vi tệp trình chỉnh sửa mà Apps Script đặt thành currentonly. Ví dụ: nếu bạn thêm nhận xét này vào tệp dự án tập lệnh tiện ích bổ sung dành cho Trang tính, thì bạn đang chỉ định rằng tiện ích bổ sung chỉ cần được cấp quyền hoạt động trên Trang tính đang mở và không cần bất kỳ Trang tính nào khác mà người dùng có thể có trong Google Drive. Ngược lại, bạn không nên sử dụng nhận xét này nếu tiện ích bổ sung dành cho Trang tính cần đọc hoặc ghi dữ liệu trong một Trang tính mà người dùng không mở.