Quy trình ủy 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 mà nó cần khi ai đó cố gắng sử dụng dự án đó.

Mô hình uỷ quyền cho Tiện ích bổ sung 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 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. 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 tài liệu nơi 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 các hàm onOpen() khi một tài liệu mở.

Để 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 hoạt động được với onOpen(). Hướng dẫn này có thể giúp bạn hiểu 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 dành cho trình chỉnh sửa phụ thuộc vào trạng thái của tiện ích đó, tuỳ thuộc vào người sử dụng tiện ích đó: 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

Bạn có thể cài đặt, bật hoặc bật cả hai Tiện ích bổ sung dành cho trình chỉnh sửa trong trình đơn Tiện ích.

• 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ọ tải 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 đượ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 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, tệp đó sẽ đượ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 dữ liệu đã 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 của 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 đó
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á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 đó 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 Tiện ích bổ sung trình chỉnh sửa xác định chế độ uỷ quyền mà hàm onOpen() chạy.

Nếu bạn bật Tiện ích bổ sung trình chỉnh sửa 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, 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 chung, 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 trình đơn, dừng. Trợ giúp là tuỳ 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 trên 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 đã uỷ quyền.

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

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 Apps Script ScriptApp.AuthMode.

Chế độ uỷ quyền áp dụng cho tất cả các phương thức thực thi của 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 trong 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 dưới dạng 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 quy định 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 vào	onOpen() (nếu người dùng đã cài đặ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 thời điểm 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ó
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 các món trong thực đơn	Thêm các 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ả cá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 được liệt kê trong trình đơn Tiện ích và bắt đầu theo dõi 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 trong trình đơn 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 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 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 đang 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, nó sẽ tải mọi Tiện ích bổ sung 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 và 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ài đặt hay bật.

Nếu một 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 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ý phù hợp.

Mẫu sau đây cho thấy một hàm onOpen() nâng cao thay đổi thao tác 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ác câu lệnh chung sẽ chạy trong 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 đã phát hành không thêm được các mục trong trình đơn, hãy xem lại bảng điều khiển JavaScript của trình duyệt để xem có trả về lỗi hay không. Sau đó, hãy kiểm tra tập lệnh của bạn để xem hàm onOpen() hoặc biến chung 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 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.

Một 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, 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ọ làm vậy nếu chưa cài đặt. Nếu người dùng đã uỷ quyền 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 đã đượ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ý các chế độ uỷ quyền một cách chính xác. Ví dụ:

• Một tiện ích bổ sung sẽ cố chạy dịch vụ Apps Script mà chế độ uỷ quyền hiện tại không hỗ trợ.

• Tiện ích bổ sung sẽ cố 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ử những thao tác sau:

1. Mở dự án Apps Script cho tiện ích bổ sung của bạn và tìm hàm onOpen().
2. Tìm kiếm hàm onOpen() để đề cập đến các dịch vụ hoặc đối tượng của Apps Script 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.
3. 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, hãy xoá hoặc đặt 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(). Đồng thời tìm và xoá mọi dịch vụ nằm ngoài một hàm.
4. Xác định những hàm có thể chứa các dòng mã được nhận xét hoặc xoá trong bước trước, đặc biệt là những hàm sử dụng thông tin mà các hàm đó tạo và di chuyển lệnh gọi dịch vụ đến các hàm cần chúng. Sắp xếp lại hoặc viết lại cơ sở mã cho phù hợp với những thay đổi đã thực hiện trong các bước trước.

5. Lưu mã và tạo phiên bản triển khai thử nghiệm.

   Khi bạn tạo một hoạt động triển khai thử nghiệm, hãy đảm bảo rằng trường Config (Cấu hình) là 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 sẽ có nội dung là Test in AuthMode.None (Kiểm thử trong AuthMode.None)

6. Chạy quy trình triển khai thử nghiệm rồi mở trình đơn Tiện ích.

7. Nếu tất cả các mục trong trình đơn đều hiển thị, thì sự cố đã đượ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ụ.

Chủ đề có liên quan

• Ứng dụng web
• Loại tiện ích bổ sung
• Kiểm thử một Tiện ích bổ sung dành cho trình chỉnh sửa