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 dành cho Trình chỉnh sửa 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 mà bạn có thể 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 dùng được cho 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 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.

Chế độ uỷ quyền

Hàm onOpen() của 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ệ 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 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, 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 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 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 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 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, 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ó 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.

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ột mục trình đơn Extensions (Tiện ích), thì mục đó sẽ 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() 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 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ở, công cụ 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() 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 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 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 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 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 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 đã 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. 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ụ:

• 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 tiện ích đó.

Để 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:

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 lượt đề cập đến Apps Script các dịch vụ hoặc đối tượng liên kết với các dịch vụ đó, 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, 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(). 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 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 đó.

5. Lưu mã và tạo một đợt 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 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ụ.

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