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 dành cho 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ả tiện ích bổ sung mà người dùng cài đặt sẽ được liệt kê trong trình đơn Tiện ích, 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 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 dành cho Trình chỉnh sửa sẽ thấy tiện ích bổ sung này trong các tài liệu mà người tạo tệp đã sử dụng.
Tiện ích bổ sung dành cho 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 để 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 tiện ích bổ sung dành cho 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 cộng tác viên.

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 dành cho 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à uỷ quyền cho tiện ích bổ sung đó truy cập vào dữ liệu Google của họ.
Tiện ích bổ sung được bật trong một 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 bổ sung đó ở đó.
Khi mọi người cộng tác trên một tệp và một trong số họ sử dụng tiện ích bổ sung, thì tiện ích bổ sung đó sẽ được cài đặt cho 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 trạng thái đã cài đặt và đã bật. Khi bạn 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 xuống từ cửa hàng	Tải tiện ích bổ sung xuống 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 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ị cho	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 tiện ích bổ sung đó cũng được bật, trong trường hợp đó là `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Chế độ uỷ quyền

Hàm onOpen của tiện ích bổ sung dành 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 dành cho Trình chỉnh sửa xác định chế độ uỷ quyền mà hàm onOpen chạy.

Nếu tiện ích bổ sung dành cho 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 ở AuthMode.LIMITED. Nếu tiện ích bổ sung không được bật và chỉ được cài đặt, onOpen chạy ở AuthMode.NONE.

Trong AuthMode.NONE, tiện ích bổ sung không thể chạy một số dịch vụ 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 onOpen, onInstall hoặc phạm vi toàn cục, thì quyền sẽ không thành cô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 hàm tương tác với 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ả 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ể ở AuthMode.NONE; những tiện ích bổ sung dành cho Trình chỉnh sửa chưa xuất bản sẽ chạy onOpen ở AuthMode.LIMITED. Tuy nhiên, dự định ở một trong hai chế độ uỷ quyền. Để thực hiện việc này, hãy kiểm thử tiện ích bổ sung dành cho Trình chỉnh sửa.

Apps Script chuyển chế độ uỷ quyền dưới dạng 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 Apps Script google.script.run. 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 một trình kích hoạt như onOpen, onEdit hoặc onInstall. Các 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ó một số hạn chế khác biệt. Đối với tất cả các trường hợp khác, tập lệnh chạy ở AuthMode.FULL, như mô tả trong bảng sau.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Xảy ra đối với	`onOpen` (nếu người dùng đã cài đặt tiện ích bổ sung 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ả các lần 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: đ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ục trong trình đơn	Thêm mục trong trình đơ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 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 được liệt kê 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ì mục đó sẽ chạy.

Tiện ích bổ sung dành cho Trình chỉnh sửa được cài đặt

Khi một tiện ích bổ sung dành cho Trình chỉnh sửa được cài đặt từ cửa hàng, hàm onInstall của tiện ích bổ sung đó sẽ chạy ở AuthMode.FULL. Ở 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 biết 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 đượ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ở ra, tài liệu, biểu mẫu, bản trình bày hoặc bảng tính đó sẽ tải mọi tiện ích bổ sung dành cho Trình chỉnh sửa mà người dùng hiện tại đã cài đặt hoặc 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 họ. 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 các thuộc tính đã lưu trữ của Apps Script , để đọ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 toàn cục 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 toàn cục, thì cả câu lệnh toàn cục 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 lại bảng điều khiển trình duyệt để xem 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 các 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 ở 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 mục này chạy ở AuthMode.FULL.

Người dùng chạy tiện ích bổ sung dành cho 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 sẽ kiểm tra trước tiên xem người dùng đã cài đặt tiện ích bổ sung hay chưa và nhắc người dùng 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 ở AuthMode.FULL. Tiện ích bổ sung đượ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ố 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ý đúng các chế độ uỷ quyền. Ví dụ:

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 bổ sung đó.

Để xoá hoặc sắp xếp lại một lệnh gọi dịch vụ đang 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 kiếm hàm onOpen để tìm các dịch vụ hoặc đối tượng Apps Script được liên kết với các dịch vụ hoặc đối tượng đó, chẳng hạn như PropertiesService, SpreadsheetApp hoặc GmailApp.
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 phần tử 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ỉ để lại các phương thức sau: .getUi, .createMenu, .addItem và .addToUi. Ngoài ra, 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 hàm sử dụng thông tin mà chúng tạo ra, đồng thời di chuyển các lệnh gọi dịch vụ đến các hàm cần có. Sắp xếp lại hoặc viết lại cơ sở mã để phù hợp với các thay đổi được thực hiện ở các bước trước.
Lưu mã và tạo bản triển khai kiểm thử. Khi bạn tạo bản triển khai kiểm thử, hãy đảm bảo rằng trường Cấu hình là Đã 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 có nội dung Kiểm thử trong AuthMode.NONE.
Khởi chạy bản triển khai kiểm thử và mở trình đơn Tiện ích.
Nếu tất cả các mục trong trình đơn đều hiển thị, 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 đã bỏ lỡ một lệnh 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.