Uỷ quyền tiện ích bổ sung dành cho trình chỉnh sửa

Việc uỷ quyền cho nhiều ứng dụng Google Apps Script rất đơn giản. Dự án tập lệnh sẽ yêu cầu mọi quyền còn thiếu mà dự án cần khi có người cố gắng sử dụng dự án đó.

Mô hình uỷ quyền cho Tiện ích bổ sung của Trình chỉnh sửa phức tạp hơn vì một số lý do:

Khi người dùng tạo một tệp, tất cả các tiện ích bổ sung mà người dùng cài đặt sẽ xuất hiện trong trình đơn Tiện ích bổ sung, ngay cả khi người dùng chưa uỷ quyền cho 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 mà bạn có thể chia sẻ với cộng tác viên. Những cộng tác viên chưa cài đặt tiện ích bổ sung Trình chỉnh sửa sẽ thấy tiện ích này trong những tài liệu mà người tạo tệp đã sử dụng.
Các tiện ích bổ sung của trình chỉnh sửa sẽ tự động chạy các hàm onOpen 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 dùng được cho onOpen. Hướng dẫn này giải thích những việc mà mã của bạn có thể làm và thời điểm thực hiện.

Mô hình uỷ quyền

Chế độ uỷ quyền của một tiện ích bổ sung của Trình chỉnh sửa phụ thuộc vào trạng thái của tiện ích bổ sung đó, trạng thái này phụ 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 của Trình chỉnh sửa trong trình đơn Tiện ích được cài đặt, bật hoặc cả hai:

Tiện ích bổ sung được cài đặt cho một người dùng cụ thể sau khi người dùng đó hoặc quản trị viên của họ tải tiện ích bổ sung xuống từ Google Workspace Marketplace và cho phép tiện ích bổ sung truy cập vào dữ liệu trên Google của họ.
Tiện ích bổ sung sẽ được bật trong tài liệu, biểu mẫu, bản trình bày hoặc bảng tính khi có người sử dụng tiện ích đó.
Khi mọi người cộng tác trên một tệp và một trong số họ sử dụng một tiện ích bổ sung, tiện ích đó sẽ được cài đặt cho người dùng đó và bật cho tệp.

Bảng sau đây tóm tắt những điểm khác biệt giữa trạng thái đã cài đặt và đã bật. Khi kiểm thử một tập lệnh dưới dạng tiện ích bổ sung, bạn có thể chạy kiểm thử ở một hoặc cả hai trạng thái.

	Đã 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	Tải tiện ích bổ sung từ cửa hàng trong khi sử dụng tài liệu, biểu mẫu, bản trình bày hoặc 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ị đối với	Chỉ người dùng đó, trong tất 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 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` (trừ phi được bật, trong trường hợp đó `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Chế độ uỷ quyền

Hàm onOpen của một tiện ích bổ sung cho Trình chỉnh sửa sẽ tự động chạy khi người dùng mở một tài liệu, biểu mẫu, bản trình bày hoặc bảng tính. Để bảo vệ dữ liệu của người dùng, Apps Script hạn chế những việc mà hàm onOpen có thể làm. Trạng thái của tiện ích bổ sung Trình chỉnh sửa sẽ xác định chế độ uỷ quyền mà hàm onOpen chạy.

Nếu một tiện ích bổ sung của Trình chỉnh sửa được bật trong tệp, biểu mẫu, bản trình bày hoặc bảng tính, thì onOpen sẽ chạy trong AuthMode.LIMITED. Nếu tiện ích bổ sung chưa được bật và chỉ được cài đặt, thì onOpen sẽ chạy trong AuthMode.NONE.

Trong AuthMode.NONE, một tiện ích bổ sung không thể chạy một số dịch vụ nhất định 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 các hàm tuỳ chỉnh. Nếu tiện ích bổ sung của bạn cố gắng sử dụng các dịch vụ này trong phạm vi onOpen, onInstall hoặc phạm vi toàn cầu, thì các quyền sẽ không hoạt động và các lệnh gọi khác, chẳng hạn như điền vào trình đơn, sẽ dừng. Trợ giúp là lựa chọn duy nhất được hỗ trợ.

Để chạy các lệnh gọi dịch vụ bị hạn chế, bạn phải sử dụng chế độ uỷ quyền AuthMode.FULL. Các lượt tương tác của người dùng (chẳng hạn như nhấp vào một lựa chọn trong trình đơn) chỉ chạy ở chế độ này. Sau khi mã được chạy ở chế độ AuthMode.FULL, tiện ích bổ sung có thể sử dụng tất cả các phạm vi được uỷ quyền.

Chỉ những tiện ích bổ sung dành cho Trình chỉnh sửa đã xuất bản mới có thể nằm trong AuthMode.NONE; các tiện ích bổ sung dành cho Trình chỉnh sửa chưa xuất bản sẽ chạy onOpen trong AuthMode.LIMITED. Tuy nhiên, dự kiến ở một trong hai chế độ uỷ quyền. Để làm việc này, hãy kiểm thử một tiện ích bổ sung của Trình chỉnh sửa.

Apps Script truyền chế độ uỷ quyền làm thuộc tính authMode của tham số sự kiện Apps Script, e; giá trị của e.authMode tương ứng với một hằng số trong enum ScriptApp.AuthMode của Apps Script.

Các chế độ uỷ quyền áp dụng cho tất 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ột mục trong trình đơn hoặc từ lệnh gọi google.script.run Apps Script. Tuy nhiên, bạn chỉ có thể kiểm tra thuộc tính e.authMode nếu tập lệnh chạy do trình 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 là AuthMode.CUSTOM_FUNCTION, tương tự như LIMITED nhưng có các quy tắc hạn chế hơi khác. Đối với tất cả các trường hợp khác, tập lệnh sẽ chạy trong AuthMode.FULL, như mô tả trong bảng sau.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Xảy ra trong	`onOpen` (nếu người dùng đã cài đặt một tiện ích bổ sung nhưng chưa bật tiện ích đó 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ả các thời điểm khác) `onEdit` (chỉ trong Trang tính)	Hàm tuỳ chỉnh	Tất cả các lần 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 trình bà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ó
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 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 đó sẽ đượ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 xuất hiện trong trình đơn Tiện ích và bắt đầu theo dõi các trình kích hoạt đơn giản onInstall, onOpen và onEdit. Nếu người dùng nhấp vào một mục trong trình đơn Tiện ích, thì tiện ích đó sẽ chạy.

Đã cài đặt tiện ích bổ sung dành cho trình chỉnh sửa

Khi một tiện ích bổ sung của Trình chỉnh sửa được cài đặt từ cửa hàng, hàm onInstall của tiện ích đó sẽ chạy trong AuthMode.FULL. Trong chế độ uỷ quyền này, tiện ích bổ sung 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 cho thấy cách gọi hàm onOpen từ hàm onInstall:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Tiện ích bổ sung dành cho trình chỉnh sửa sẽ mở ra

Khi một tài liệu, biểu mẫu, bản trình bày hoặc bảng tính mở ra, tiện ích bổ sung 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, đồng thời gọi từng hàm onOpen của tiện ích bổ sung đó. Chế độ uỷ quyền mà onOpen chạy phụ thuộc vào việc tiện ích bổ sung có được cài đặt hay bật hay không.

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 cho thấ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 trong trình đơn động dựa trên thuộc tính Apps Script đã lưu trữ, đọ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ý chế độ đó một cách thích hợp.

Mẫu sau đây cho thấy một hàm onOpen nâng cao thay đổi hành động 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();
}

Khi hàm onOpen chạy, toàn bộ tập lệnh sẽ tải và các câu lệnh chung sẽ chạy ở cùng một chế độ uỷ quyền như onOpen. Nếu chế độ uỷ quyền cấm các câu lệnh chung, thì cả câu lệnh chung và onOpen đều không chạy được. Nếu tiện ích bổ sung đã xuất bản không thêm được các mục trong trình đơn, hãy xem xét bảng điều khiển trình duyệt để biết có lỗi nào được trả về hay không. Sau đó, hãy kiểm tra tập lệnh để xem hàm onOpen hoặc các biến toàn cục có gọi những dịch vụ không được phép trong AuthMode.NONE hay không.

Tiện ích bổ sung không thể mở thanh bên hoặc hộp thoại trong khi thực thi trong AuthMode.LIMITED. Bạn có thể dùng các mục trong trình đơn để mở thanh bên và hộp thoại vì các mục này chạy trong AuthMode.FULL.

Người dùng chạy tiện ích bổ sung 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, Apps Script trước tiên sẽ kiểm tra xem người dùng đã cài đặt tiện ích bổ sung hay chưa và nhắc họ cài đặt nếu chưa. Nếu người dùng đã uỷ quyền cho tiện ích bổ sung, thì tập lệnh sẽ chạy hàm tương ứng với mục trong trình đơn trong AuthMode.FULL. Tiện ích bổ sung sẽ được bật 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 bật.

Khắc phục sự cố không hiển thị trình đơn tiện ích bổ sung

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ý đúng các chế độ uỷ quyền. Ví dụ:

Một tiện ích bổ sung cố gắng chạy một dịch vụ Apps Script không được chế độ uỷ quyền hiện tại hỗ trợ.
Tiện ích bổ sung cố gắng chạy một lệnh gọi dịch vụ trước khi người dùng tương tác với tiện ích đó.

Để xoá hoặc sắp xếp lại một lệnh gọi dịch vụ gây ra lỗi về quyền trong AuthMode.NONE, hãy thử các thao tác sau:

Mở dự án Apps Script cho tiện ích bổ sung của bạn và tìm hàm onOpen.
Tìm hàm onOpen để biết thông tin về các dịch vụ hoặc đối tượng Apps Script được liên kết với hàm này, chẳng hạn như PropertiesService, SpreadsheetApp hoặc GmailApp.
Nếu một dịch vụ được dùng cho mục đích khác ngoài việc tạo các phần tử trên giao diện người dùng, hãy xoá dịch vụ đó hoặc gói dịch vụ đó trong một khối nhận xét. Chỉ giữ 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 những 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 hàm sử dụng thông tin mà chúng tạo ra và di chuyển các lệnh gọi dịch vụ đến những hàm cầ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 những thay đổi được thực hiện ở các bước trước.
Lưu mã và tạo một bản triển khai thử nghiệm. Khi bạn tạo một bản triển khai thử nghiệm, hãy đảm bảo rằng trường Config (Cấu hình) có giá trị Installed for current user (Đã cài đặt cho người dùng hiện tại) và văn bản bên dưới hộp Config (Cấu hình) có nội dung Test in AuthMode.NONE (Thử nghiệm trong AuthMode.NONE).
Khởi chạy quá trình triển khai thử nghiệm và 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ì 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. Có thể bạn đã lỡ một cuộc gọi dịch vụ.

Uỷ quyền tiện ích bổ sung dành cho trình chỉnh sửa Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.