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

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 yêu cầu mọi quyền còn thiếu cần thiết khi ai đó cố gắng để sử dụng.

Mô hình uỷ quyền cho Tiện ích bổ sung dành cho Editor 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 có thể được 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 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 hỗ trợ 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. Lưu ý rằng khi bạn thử nghiệm 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 này.

Chế độ uỷ quyền

Hàm onOpen() của một Tiện ích bổ sung cho Trình chỉnh sửa sẽ chạy tự động khi người dùng mở 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 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, onOpen() sẽ chạy trong AuthMode.LIMITED. Nếu tiện ích bổ sung chưa được bật và đang chỉ được cài đặt, 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 sẽ cố gắng sử dụng các dịch vụ này trong onOpen(), onInstall() (hoặc phạm vi trên toàn cầu), 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 thực đơn, dừng lại. Trợ giúp là tuỳ 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 chức năng 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, chỉ có thể kiểm tra thuộc tính e.authMode nếu tập lệnh chạy trong 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 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ục trong trình đơn Tiện ích, mục này 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() của bạn 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 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ở, ứng dụng 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() Việc này phụ thuộc vào việc tiện ích bổ sung có được được cài đặt hoặc bật.

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 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 vào Apps Script đã lưu trữ thuộc tính, để đọ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ý 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 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 thanh bên và hộp thoại này chạy trong AuthMode.FULL.

Một người dùng chạy Tiện ích bổ sung của 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 đã cấp quyền 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ụ:

• Tiện ích bổ sung cố gắng chạy Apps Script dịch vụ không được chế độ uỷ quyền hiện tại hỗ trợ.

• Tiện ích bổ sung cố gắng thực hiện lệnh gọi dịch vụ trước người dùng tương tác với từ khoá đó.

Để 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 của bạn rồi 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 chú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, xoá nhận xét hoặc đặt 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(). Đồng thời, 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ã đã nhận xét hoặc bị 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 đợt triển khai thử nghiệm, hãy đảm bảo rằng trường Cấu hình được 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 cho biết Thử nghiệm ở AuthMode.None

6. 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 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
• Loại tiện ích bổ sung
• Kiểm thử tiện ích bổ sung dành cho Trình chỉnh sửa