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 dựa trên Apps Script rất đơn giản vì dự án tập lệnh sẽ yêu cầu mọi quyền còn thiếu khi có người cố gắng sử dụng ứng dụng đó.

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

• Tiện ích bổ sung của Trình chỉnh sửa 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 onOpen(). Hướng dẫn này có thể giúp bạn hiểu được mã của mình có thể làm gì và khi nào.

Mô hình uỷ quyền

Chế độ uỷ quyền của tiện ích bổ sung 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 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.

• Một tiện ích bổ sung được cài đặt cho một người dùng cụ thể sau khi họ hoặc quản trị viên của họ lấy tiện ích đó từ Google Workspace Marketplace và cho phép tiện ích đó truy cập vào dữ liệu của họ trên Google.
• 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 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. Xin lưu ý rằng khi kiểm thử 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 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	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 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 đó
Thực đơ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 tính năng này cũng được bật, trong trường hợp đó AuthMode.LIMITED)	AuthMode.LIMITED

Chế độ uỷ quyền

Hàm onOpen() của tiện ích bổ sung 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 xác định chế độ uỷ quyền mà hàm onOpen() chạy trong đó.

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 trình bà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 onOpen(), onInstall() hoặc phạm vi toàn cục, quyền sẽ không được cấp 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 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 mã chạy ở 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.

Lưu ý: Chỉ tiện ích bổ sung đã xuất bản cho Trình chỉnh sửa mới có thể nằm trong AuthMode.NONE; tiện ích bổ sung chưa xuất bản cho Trình chỉnh sửa sẽ chạy onOpen() trong AuthMode.LIMITED. Tuy nhiên, bạn có thể kiểm thử tiện ích bổ sung cho Trình chỉnh sửa để xác minh rằng tiện ích bổ sung đang được phát triển hoạt động như dự kiến ở một trong hai chế độ uỷ quyền.

Apps Script truyền chế độ uỷ quyền dưới dạng thuộc tính authMode của thông 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.

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 của 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 một 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, AuthMode.CUSTOM_FUNCTION, tương tự như LIMITED nhưng có một số hạn chế 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 đối với	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() (mọi thời điểm khác) onEdit() (chỉ có trong Trang tính)	Hàm tuỳ chỉnh	Tất cả thời điểm khác, bao gồm: trình 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 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 Extensions (Tiện ích) và bắt đầu 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ột mục trình đơn Extensions (Tiện ích), thì mục đó 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 cho 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. Ở 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() 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 đượ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 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 các 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 hoặc bật hay không.

Nếu một tiện ích bổ sung chỉ tạo một trình đơn cơ bản, thì chế độ sẽ 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 trình đơn động dựa trên thuộc tính Apps Script được 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();
}

Cảnh báo: Khi hàm onOpen() chạy, toàn bộ tập lệnh sẽ tải và tất cả câu lệnh toàn cục đều chạy ở cùng chế độ uỷ quyền với 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 đã phát hành không thêm được các mục trình đơn, hãy xem lại bảng điều khiển JavaScript của 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 của bạn để 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.

Xin lưu ý rằng các 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ể 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 trong 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 Extensions (Tiện ích), trước tiên, Apps Script 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 đã cho phép tiện ích bổ sung, tập lệnh sẽ chạy hàm tương ứng với mục 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ố 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ách 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 lệnh gọi dịch vụ trước khi người dùng tương tác với lệnh gọi đó.

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

1. Mở dự án Apps Script cho tiện ích bổ sung và tìm hàm onOpen().
2. Tìm kiếm hàm onOpen() để xem các dịch vụ hoặc đối tượng Apps Script được liên kết với hàm đó, chẳng hạn như PropertiesService, SpreadsheetApp hoặc GmailApp.
3. Nếu một dịch vụ được dùng cho 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, hãy xoá 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.
4. Xác định các hàm có thể chứa các dòng mã được chú thích hoặc xoá trong bước trước, đặc biệt là các hàm sử dụng thông tin mà các dòng mã đó 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ác dòng mã đó. Sắp xếp lại hoặc viết lại cơ sở mã để phù hợp với những thay đổi đã thực hiện ở các bước trước.

5. Lưu mã và tạo một bản triển khai kiểm thử.

   Khi bạn tạo một 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 là Kiểm thử trong AuthMode.None

6. Chạy quá trình triển khai kiểm thử và mở trình đơn Extensions (Tiện ích).

7. 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. Bạn có thể đã lỡ một cuộc gọi dịch vụ.

Chủ đề có liên quan

• Ứng dụng web
• Các loại tiện ích bổ sung
• Kiểm thử tiện ích bổ sung dành cho Trình chỉnh sửa