Google Apps Script yêu cầu người dùng uỷ quyền để truy cập vào dữ liệu riêng tư từ các dịch vụ tích hợp của Google hoặc các dịch vụ nâng cao của Google.
Cách hoạt động của việc uỷ quyền cho Các dịch vụ của Google
Khi cần truy cập vào các dịch vụ của Google, tập lệnh sẽ tuân theo quy trình chung sau:
- Phát hiện: Apps Script quét tập lệnh để xác định những dịch vụ mà tập lệnh sử dụng (ví dụ:
SpreadsheetApphoặcGmailApp). - Xác định phạm vi: Dựa trên quá trình quét, Apps Script xác định một nhóm phạm vi OAuth cần thiết để tập lệnh chạy.
- Kiểm tra quyền uỷ quyền: Khi tập lệnh chạy, tập lệnh sẽ kiểm tra xem người dùng đã uỷ quyền cho các phạm vi đó hay chưa.
- Lời nhắc người dùng: Nếu thiếu quyền uỷ quyền, một hộp thoại sẽ xuất hiện yêu cầu người dùng cấp quyền.
- Thực thi: Sau khi được uỷ quyền, tập lệnh có thể truy cập vào dữ liệu được yêu cầu cho người dùng đó.
Quyền và các loại tập lệnh
Danh tính người dùng mà một tập lệnh chạy cùng (và do đó, dữ liệu mà tập lệnh có thể truy cập) sẽ thay đổi tuỳ theo trường hợp mà tập lệnh chạy, như minh hoạ trong bảng sau.
| Loại tập lệnh | Tập lệnh chạy dưới dạng... |
|---|---|
| Độc lập, Tiện ích bổ sung Google Workspace hoặc được liên kết với Google Tài liệu, Google Trang tính, Google Trang trình bày hoặc Google Biểu mẫu | Người dùng sử dụng bàn phím |
| Hàm tuỳ chỉnh trong bảng tính | Người dùng ẩn danh; tuy nhiên, hạn mức được tính cho người dùng đang sử dụng bàn phím |
| Ứng dụng web hoặc Tiện ích Google Sites | Người dùng sử dụng bàn phím hoặc chủ sở hữu tập lệnh, tuỳ thuộc vào các lựa chọn được chọn khi triển khai ứng dụng |
| Điều kiện kích hoạt có thể cài đặt | Người dùng đã tạo điều kiện kích hoạt |
Cấp quyền truy cập
Apps Script tự động xác định các phạm vi uỷ quyền (chẳng hạn như quyền truy cập vào tệp Sheets hoặc Gmail của bạn) dựa trên quá trình quét mã. Mã đã được nhận xét vẫn có thể tạo yêu cầu uỷ quyền. Nếu một tập lệnh cần được uỷ quyền, thì hộp thoại uỷ quyền sẽ xuất hiện khi tập lệnh đó chạy.
Các tập lệnh mà bạn đã uỷ quyền trước đó cũng sẽ yêu cầu uỷ quyền bổ sung nếu một thay đổi về mã thêm các dịch vụ mới. Tập lệnh có thể không yêu cầu uỷ quyền nếu bạn truy cập vào tập lệnh dưới dạng một ứng dụng web chạy theo danh tính người dùng của chủ sở hữu tập lệnh.
Thu hồi quyền truy cập
Để thu hồi quyền truy cập của một tập lệnh vào dữ liệu của bạn, hãy làm theo các bước sau:
- Truy cập vào phần Bảo mật trong Tài khoản Google của bạn.
- Trong phần Các ứng dụng và dịch vụ bên thứ ba mà bạn đã kết nối, hãy nhấp vào Xem tất cả các ứng dụng và dịch vụ đã kết nối.
- Chọn tập lệnh hoặc ứng dụng mà bạn muốn thu hồi quyền truy cập.
- Nhấp vào Xoá tất cả kết nối bạn có với APP_NAME, sau đó nhấp vào Xác nhận.
Giới hạn phạm vi trong tài liệu hiện tại
Nếu đang tạo một tiện ích bổ sung hoặc tập lệnh khác sử dụng Dịch vụ bảng tính, Dịch vụ tài liệu, Dịch vụ trang trình bày hoặc Dịch vụ biểu mẫu, bạn có thể buộc hộp thoại uỷ quyền chỉ yêu cầu quyền truy cập vào các tệp mà tiện ích bổ sung hoặc tập lệnh được dùng, thay vì tất cả bảng tính, tài liệu hoặc biểu mẫu của người dùng. Để thực hiện việc này, hãy thêm chú thích JSDoc sau đây vào một nhận xét ở cấp tệp:
/**
* @OnlyCurrentDoc
*/
Chú thích đối lập @NotOnlyCurrentDoc sẽ có sẵn nếu tập lệnh của bạn có một thư viện khai báo @OnlyCurrentDoc, nhưng tập lệnh chính thực sự cần có quyền truy cập vào nhiều tệp hơn tệp hiện tại.
Vòng đời uỷ quyền cho tiện ích bổ sung
Tiện ích bổ sung cho Trang tính, Tài liệu, Trang trình bày và Biểu mẫu thường tuân theo cùng một mô hình uỷ quyền như các tập lệnh được liên kết với một tài liệu. Tuy nhiên, trong một số trường hợp nhất định, các chức năng onOpen(e) và onEdit(e) của chúng chạy ở chế độ không uỷ quyền, gây ra một số vấn đề phức tạp khác. Để biết thêm thông tin, hãy xem hướng dẫn về vòng đời uỷ quyền của tiện ích bổ sung.
Giới hạn số người dùng ứng dụng OAuth
Các ứng dụng sử dụng OAuth để truy cập vào dữ liệu người dùng trên Google (bao gồm cả các dự án Apps Script) phải tuân theo giới hạn uỷ quyền. Hãy xem phần Giới hạn về số lượng người dùng ứng dụng OAuth để biết thông tin chi tiết.
Hành vi xác thực lại bằng Apps Script
Apps Script không thực thi tần suất xác thực lại được định cấu hình trong chế độ cài đặt dịch vụ Google Cloud. Điều này là do Apps Script có thể tự động chạy bằng cách sử dụng các trình kích hoạt. Các trình kích hoạt này hoạt động mà không cần người dùng tương tác trực tiếp. Những lần thực thi tự động này không kích hoạt lời nhắc xác thực lại. Ứng dụng Apps Script sẽ không tự động yêu cầu bạn xác thực lại sau khoảng thời gian đã chỉ định (ví dụ: 12 giờ).
Đặt các phạm vi rõ ràng trong tệp kê khai
Apps Script tự động xác định các phạm vi bắt buộc bằng cách quét mã để tìm các lệnh gọi hàm. Nếu cần có nhiều quyền kiểm soát hơn, bạn có thể đặt phạm vi một cách rõ ràng trong tệp kê khai dự án (appsscript.json). Bạn nên làm như vậy đối với các tập lệnh đã xuất bản để đảm bảo rằng bạn đang sử dụng các quyền tối thiểu bắt buộc.
Để biết hướng dẫn, hãy xem bài viết Đặt phạm vi rõ ràng.
Khắc phục sự cố
- Lỗi"Cần có quyền uỷ quyền" khi chạy một điều kiện kích hoạt: Người dùng đã tạo điều kiện kích hoạt phải uỷ quyền cho điều kiện kích hoạt. Nếu thêm mã yêu cầu quyền mới, bạn phải chạy một hàm theo cách thủ công trong trình chỉnh sửa tập lệnh một lần để kích hoạt hộp thoại uỷ quyền.
- Phạm vi không cập nhật: Nếu bạn đã cập nhật mã nhưng hộp thoại uỷ quyền không phản ánh các thay đổi, hãy thử lưu dự án và làm mới trình chỉnh sửa. Nếu bạn đang sử dụng các phạm vi rõ ràng trong tệp kê khai, hãy đảm bảo bạn đã thêm phạm vi mới vào mảng
oauthScopes. - "Ứng dụng này bị chặn" hoặc cảnh báo ứng dụng chưa được xác minh: Điều này xảy ra nếu tập lệnh của bạn sử dụng các phạm vi nhạy cảm hoặc hạn chế và chưa được Google xác minh. Xem phần Xác minh ứng dụng OAuth.