Uỷ quyền cho nhiều ứng dụng dựa trên Apps Script rất đơn giản vì dự án tập lệnh yêu cầu mọi quyền còn thiếu cần thiết khi ai đó cố gắng để sử dụng.
Mô hình uỷ quyền cho Tiện ích bổ sung dành cho Editor là phức tạp hơn vì một vài lý do:
Khi người dùng tạo một tệp, tất cả tiện ích bổ sung mà người dùng đó cài đặt được liệt kê trong trình đơn Tiện ích, thậm chí nếu người dùng chưa cho phép các tiện ích bổ sung đó.
Các tiện ích bổ sung này hoạt động trên các tệp trong Google Drive có thể được chia sẻ với cộng tác viên. Cộng tác viên không đã cài đặt Tiện ích bổ sung Trình chỉnh sửa rồi xem tiện ích đó trong tài liệu mà người tạo tệp đã sử dụng.
Tiện ích bổ sung trình chỉnh sửa sẽ tự động chạy
onOpen()
hoạt động khi một tài liệu mở ra.
Để bảo vệ dữ liệu người dùng, các chế độ uỷ quyền được áp dụng để khiến một số dịch vụ
không hỗ trợ onOpen()
. Hướng dẫn này có thể giúp bạn nắm được mã
có thể làm và khi nào.
Mô hình uỷ quyền
Chế độ uỷ quyền của Tiện ích bổ sung Trình chỉnh sửa phụ thuộc trạng thái của tiện ích bổ sung, tuỳ thuộc vào người đang sử dụng tiện ích bổ sung đó: người dùng đã cài đặt tiện ích bổ sung hoặc một cộng tác viên.
Các trạng thái của tiện ích bổ sung dành cho trình chỉnh sửa
Tiện ích bổ sung Trình chỉnh sửa trong trình đơn Tiện ích đã cài đặt, đã bật hay cả hai.
- Một tiện ích bổ sung được cài đặt cho một của người dùng sau khi họ hoặc quản trị viên của họ nhận được URL đó từ Google Workspace Marketplace và cho phép Google Workspace Marketplace truy cập vào dữ liệu của họ trên Google.
- Tiện ích bổ sung được bật trong tài liệu, biểu mẫu hoặc bảng tính khi có ai đó sử dụng chúng ở đó.
- Khi mọi người cộng tác trên một tệp và một người trong số họ sử dụng tiện ích bổ sung, tiện ích bổ sung được cài đặt cho một người dùng và bật cho tệp.
Bảng sau đây tóm tắt sự khác biệt giữa chế độ đã cài đặt và đã bật. Xin lưu ý rằng khi bạn thử nghiệm một tập lệnh dưới dạng tiện ích bổ sung bạn có thể chạy chương trình kiểm thử ở một hoặc cả hai trạng thái này.
Đã cài đặt | Đang bật | |
---|---|---|
Áp dụng cho | Người dùng | Tài liệu, biểu mẫu, bản trình bày hoặc bảng tính |
Nguyên nhân | Tải tiện ích bổ sung từ cửa hàng | Nhận tiện ích bổ sung từ cửa hàng khi sử dụng
tài liệu, biểu mẫu, bản trình bày, bảng tính đó hoặc Sử dụng một tiện ích bổ sung đã cài đặt trước đó trong đó tài liệu, biểu mẫu, bản trình bày hoặc bảng tính |
Trình đơn hiển thị với | Chỉ người dùng đó trong tất cả các tài liệu, biểu mẫu, bản trình bày hoặc bảng tính mà họ mở hoặc tạo | Tất cả cộng tác viên có mặt trên tài liệu, biểu mẫu, bản trình bày đó hoặc bảng tính |
Chế độ uỷ quyền cho onOpen() |
AuthMode.NONE số (trừ phi dịch vụ đó cũng được bật). AuthMode.LIMITED) |
AuthMode.LIMITED |
Chế độ uỷ quyền
Hàm onOpen()
của một Tiện ích bổ sung dành cho trình chỉnh sửa sẽ chạy
tự động khi người dùng mở tài liệu, biểu mẫu, bản trình bày hoặc bảng tính.
Để bảo vệ thì Apps Script sẽ hạn chế những dữ liệu
Hàm onOpen()
có thể làm. Trạng thái tiện ích bổ sung của Trình chỉnh sửa
xác định chế độ uỷ quyền mà hàm onOpen()
chạy.
Nếu một Tiện ích bổ sung Trình chỉnh sửa được bật trong tệp,
biểu mẫu, bản trình bày hoặc bảng tính, onOpen()
sẽ chạy trong
AuthMode.LIMITED
. Nếu tiện ích bổ sung chưa được bật và đang
chỉ được cài đặt, onOpen()
sẽ chạy trong AuthMode.NONE
.
Trong AuthMode.NONE
, tiện ích bổ sung không thể chạy một số
cho đến khi người dùng tương tác với tiện ích bổ sung bằng cách
nhấp hoặc chạy hàm tuỳ chỉnh. Nếu
tiện ích bổ sung sẽ cố gắng sử dụng các dịch vụ này trong onOpen()
,
onInstall()
(hoặc phạm vi trên toàn cầu), quyền không thành công và các lệnh gọi khác, chẳng hạn như
điền vào thực đơn, dừng lại. Trợ giúp là tuỳ chọn duy nhất được hỗ trợ.
Để chạy cuộc gọi dịch vụ bị hạn chế, bạn phải sử dụng lệnh uỷ quyền AuthMode.FULL
. Các chức năng tương tác của người dùng, chẳng hạn như nhấp vào một tuỳ chọn trong trình đơn,
chỉ chạy ở chế độ này. Sau khi chạy mã ở chế độ AuthMode.FULL
,
tiện ích bổ sung có thể sử dụng tất cả các phạm vi mà người dùng đã cho phép.
Apps Script vượt qua chế độ uỷ quyền
làm thuộc tính authMode
của Apps Script
thông số sự kiện, e
; giá trị của
e.authMode
tương ứng với một hằng số trong Apps Script
Enum ScriptApp.AuthMode
.
Chế độ uỷ quyền áp dụng cho tất cả các phương thức thực thi Apps Script,
bao gồm cả việc chạy từ trình chỉnh sửa tập lệnh, từ mục trong trình đơn hoặc từ Apps Script
Cuộc gọi google.script.run
. Tuy nhiên,
chỉ có thể kiểm tra thuộc tính e.authMode
nếu tập lệnh chạy trong kết quả
của một điều kiện kích hoạt như onOpen()
, onEdit()
hoặc onInstall()
. Hàm tuỳ chỉnh
trong Google Trang tính sử dụng chế độ uỷ quyền riêng, AuthMode.CUSTOM_FUNCTION
,
tương tự như LIMITED
nhưng có các hạn chế hơi khác. Dành cho mọi người
các trường hợp khác, tập lệnh sẽ chạy trong AuthMode.FULL
, như được mô tả trong phần sau
bảng.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Xảy ra vào | onOpen() (nếu người dùng đã cài đặt
nhưng chưa bật tiện ích bổ sung đó trong tài liệu, biểu mẫu
bản trình bày hoặc bảng tính) |
onOpen() (tất cả những thời điểm khác)onEdit() (chỉ trong Trang tính) |
Hàm tuỳ chỉnh | Tất cả những thời điểm khác, bao gồm cả: điều kiện kích hoạt có thể cài đặt onInstall() google.script.run |
Quyền truy cập vào dữ liệu người dùng | Chỉ ngôn ngữ | Chỉ ngôn ngữ | Chỉ ngôn ngữ | Có |
Quyền truy cập vào tài liệu, biểu mẫu, bản trình bày hoặc bảng tính | Không | Có | Có — chỉ có thể đọc | Có |
Quyền truy cập vào giao diện người dùng | Thêm món trong thực đơn | Thêm món trong thực đơn | Không | Có |
Quyền truy cập vào Properties |
Không | Có | Có | Có |
Quyền truy cập vào Jdbc , UrlFetch |
Không | Không | Có | Có |
Dịch vụ khác | Logger Utilities |
Mọi dịch vụ không truy cập vào dữ liệu người dùng | Mọi dịch vụ không truy cập vào dữ liệu người dùng | Tất cả dịch vụ |
Vòng đời uỷ quyền của một Tiện ích bổ sung dành cho Trình chỉnh sửa
Khi một tiện ích bổ sung được cài đặt cho người dùng hiện tại
hoặc được bật trong tệp hiện tại,
tiện ích bổ sung được tải cho tài liệu, biểu mẫu, bản trình bày
hoặc bảng tính khi tệp đó được mở. Tiện ích bổ sung này
được liệt kê trong trình đơn Tiện ích và bắt đầu lắng nghe
các điều kiện kích hoạt đơn giản onInstall()
,
onOpen()
và onEdit()
. Nếu người dùng nhấp vào
Mục trong trình đơn Tiện ích, mục này chạy.
Đã cài đặt tiện ích bổ sung Trình chỉnh sửa
Khi một Tiện ích bổ sung Trình chỉnh sửa được cài đặt từ cửa hàng,
Hàm onInstall()
chạy trong AuthMode.FULL
. Trong chế độ uỷ quyền này,
có thể chạy một quy trình thiết lập phức tạp. Bạn cũng nên
sử dụng onInstall()
để tạo các mục trong trình đơn, vì tài liệu, biểu mẫu, bản trình bày
hoặc bảng tính đã mở và hàm onOpen()
của bạn chưa chạy.
Mẫu sau đây trình bày cách gọi hàm onOpen()
qua hàm onInstall()
:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
Tiện ích bổ sung Trình chỉnh sửa đã được mở
Khi một tài liệu, biểu mẫu, bản trình bày hoặc bảng tính mở, ứng dụng này sẽ tải mọi
Tiện ích bổ sung của Trình chỉnh sửa mà người dùng hiện tại đã cài đặt hoặc
mà bất kỳ cộng tác viên nào đã bật trong tệp và gọi
từng hàm onOpen()
của chúng. Chế độ uỷ quyền mà onOpen()
Việc này phụ thuộc vào việc tiện ích bổ sung có được
được cài đặt hoặc bật.
Nếu tiện ích bổ sung chỉ tạo một trình đơn cơ bản, thì chế độ này
không quan trọng. Mẫu sau đây trình bày một hàm onOpen()
cơ bản:
function onOpen(e) {
SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
.addItem('Insert chart', 'insertChart')
.addItem('Update charts', 'updateCharts')
.addToUi();
}
Để thêm các mục trình đơn động dựa vào Apps Script đã lưu trữ thuộc tính, để đọc nội dung của tệp hiện tại hoặc để thực hiện các tác vụ nâng cao khác, bạn phải xác định chế độ uỷ quyền và xử lý thích hợp.
Mẫu sau đây là một hàm onOpen()
nâng cao có thể thay đổi
dựa trên chế độ uỷ quyền:
function onOpen(e) {
var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
if (e && e.authMode == ScriptApp.AuthMode.NONE) {
// Add a normal menu item (works in all authorization modes).
menu.addItem('Start workflow', 'startWorkflow');
} else {
// Add a menu item based on properties (doesn't work in AuthMode.NONE).
var properties = PropertiesService.getDocumentProperties();
var workflowStarted = properties.getProperty('workflowStarted');
if (workflowStarted) {
menu.addItem('Check workflow status', 'checkWorkflow');
} else {
menu.addItem('Start workflow', 'startWorkflow');
}
}
menu.addToUi();
}
Xin lưu ý rằng tiện ích bổ sung không thể mở thanh bên hoặc hộp thoại khi thực thi trong
AuthMode.LIMITED
. Bạn có thể sử dụng các mục trong trình đơn
để mở thanh bên và hộp thoại vì các thanh bên và hộp thoại này chạy trong AuthMode.FULL
.
Một người dùng chạy Tiện ích bổ sung của Trình chỉnh sửa
Khi người dùng nhấp vào một mục trong trình đơn Tiện ích,
Trước tiên, Apps Script sẽ kiểm tra xem người dùng đã cài đặt
và
nhắc họ làm như vậy nếu không. Nếu người dùng đã cấp quyền
tập lệnh sẽ chạy hàm
tương ứng với mục trình đơn trong AuthMode.FULL
. Chiến lược phát hành đĩa đơn
đã bật tiện ích bổ sung trong tài liệu, biểu mẫu
bản trình bày hoặc bảng tính nếu chưa có.
Khắc phục sự cố trình đơn tiện ích bổ sung không hiển thị
Trình đơn tiện ích bổ sung có thể không hiển thị nếu mã của bạn không quản lý chính xác chế độ ủy quyền. Ví dụ:
Tiện ích bổ sung cố gắng chạy Apps Script dịch vụ không được chế độ uỷ quyền hiện tại hỗ trợ.
Tiện ích bổ sung cố gắng thực hiện lệnh gọi dịch vụ trước khi người dùng tương tác với từ khoá đó.
Để xoá hoặc sắp xếp lại lệnh gọi dịch vụ gây ra lỗi về quyền trong
AuthMode.NONE
, hãy thử những thao tác sau:
- Mở dự án Apps Script cho tiện ích bổ sung của bạn rồi tìm
hàm
onOpen()
. - Tìm kiếm hàm
onOpen()
để xem các lượt đề cập đến Apps Script các dịch vụ hoặc đối tượng liên kết với chúng, chẳng hạn nhưPropertiesService
,SpreadsheetApp
hoặcGmailApp
. - Nếu một dịch vụ được dùng cho bất kỳ mục đích nào khác ngoài việc tạo các thành phần trên giao diện người dùng,
xoá nhận xét hoặc gói nhận xét trong khối nhận xét.
Chỉ để lại các phương thức sau:
.getUi()
,.createMenu()
,.addItem()
, và.addToUi()
. Đồng thời, hãy tìm và xoá mọi dịch vụ nằm ngoài một hàm. - Xác định các hàm có thể chứa các dòng mã đã được nhận xét hoặc xoá ở bước trước, đặc biệt là những thao tác sử dụng thông tin họ tạo ra, rồi di chuyển lệnh gọi dịch vụ đến các hàm cần đến chúng. Sắp xếp lại hoặc viết lại cơ sở mã của bạn để phù hợp với thay đổi được thực hiện trong các bước trước đó.
Lưu mã và tạo một đợt triển khai kiểm thử.
Khi bạn tạo một đợt triển khai thử nghiệm, hãy đảm bảo rằng trường Cấu hình được Cài đặt cho người dùng hiện tại và văn bản bên dưới hộp Cấu hình cho biết Thử nghiệm ở
AuthMode.None
Triển khai thử nghiệm rồi mở trình đơn Tiện ích.
Nếu tất cả các mục trong trình đơn đều xuất hiện, thì tức là vấn đề đã được khắc phục. Nếu bạn chỉ thấy trình đơn Trợ giúp, hãy quay lại bước 1. Bạn có thể đã bỏ lỡ một cuộc gọi dịch vụ.