Phạm vi uỷ quyền cho tiện ích bổ sung của Trình chỉnh sửa

Người dùng phải uỷ quyền cho các tiện ích bổ sung và ứng dụng khác truy cập vào dữ liệu của họ hoặc thay mặt họ hành động. Khi người dùng chạy một tiện ích bổ sung lần đầu tiên, giao diện người dùng của tiện ích bổ sung sẽ đưa ra lời nhắc uỷ quyền để bắt đầu quy trình uỷ quyền.

Trong quy trình này, lời nhắc cho người dùng biết ứng dụng muốn có quyền làm gì. Ví dụ: một tiện ích bổ sung có thể muốn có quyền đọc thư email của người dùng hoặc tạo sự kiện trong lịch của họ. Dự án tập lệnh của tiện ích bổ sung xác định từng quyền này dưới dạng phạm vi OAuth.

Bạn khai báo các phạm vi trong tệp kê khai bằng cách sử dụng các chuỗi URL. Trong quy trình uỷ quyền, Apps Script sẽ trình bày cho người dùng nội dung mô tả dễ đọc về phạm vi. Ví dụ: tiện ích bổ sung của bạn có thể sử dụng phạm vi "Đọc tài liệu hiện tại", được viết trong tệp kê khai dưới dạng https://www.googleapis.com/auth/documents.currentonly. Trong quy trình uỷ quyền, một tiện ích bổ sung có phạm vi này sẽ yêu cầu người dùng cho phép tiện ích bổ sung: Xem và quản lý tài liệu mà ứng dụng này đã được cài đặt bên trong.

Phạm vi xem

Bạn có thể xem các phạm vi mà dự án tập lệnh của bạn hiện yêu cầu bằng cách thực hiện các bước sau:

  1. Mở dự án tập lệnh.
  2. Ở bên trái, hãy nhấp vào Tổng quan .
  3. Xem các phạm vi trong phần "Project OAuth Scopes" (Phạm vi OAuth của dự án).

Bạn cũng có thể xem các phạm vi hiện tại của dự án tập lệnh trong tệp kê khai dự án, trong trường oauthScopes, nhưng chỉ khi bạn đã đặt các phạm vi đó một cách rõ ràng.

Đặt phạm vi tường minh

Apps Script tự động xác định những phạm vi mà một tập lệnh cần bằng cách quét mã của tập lệnh để tìm các lệnh gọi hàm yêu cầu phạm vi đó. Đối với hầu hết các tập lệnh, điều này là đủ và giúp bạn tiết kiệm thời gian, nhưng đối với các tiện ích bổ sung đã xuất bản, bạn nên thực hiện kiểm soát trực tiếp hơn đối với các phạm vi.

Ví dụ: Apps Script có thể cấp cho dự án tập lệnh tiện ích bổ sung phạm vi https://mail.google.com rất cho phép theo mặc định. Khi người dùng uỷ quyền cho một dự án tập lệnh có phạm vi này, dự án đó sẽ được cấp toàn quyền truy cập vào tài khoản Gmail của người dùng. Đối với các tiện ích bổ sung đã xuất bản, bạn phải thay thế phạm vi này bằng một tập hợp hạn chế hơn để đáp ứng nhu cầu của tiện ích bổ sung và không hơn.

Bạn có thể đặt rõ ràng các phạm vi mà dự án tập lệnh của bạn sử dụng bằng cách chỉnh sửa tệp manifest (tệp kê khai) của dự án đó. Trường tệp kê khai oauthScopes là một mảng gồm tất cả các phạm vi mà tiện ích bổ sung sử dụng. Để đặt phạm vi cho dự án, hãy làm như sau:

  1. Xem các phạm vi mà tiện ích bổ sung của bạn hiện đang sử dụng. Xác định những thay đổi cần thực hiện, chẳng hạn như sử dụng phạm vi hẹp hơn.
  2. Mở tệp kê khai của tiện ích bổ sung.
  3. Tìm trường cấp cao nhất có nhãn oauthScopes. Nếu không có, bạn có thể thêm.

  4. Trường oauthScopes chỉ định một mảng gồm các chuỗi. Để đặt các phạm vi mà dự án của bạn sử dụng, hãy thay thế nội dung của mảng này bằng các phạm vi mà bạn muốn dự án sử dụng. Ví dụ: đối với một tiện ích bổ sung của Trình chỉnh sửa mở rộng Trang tính, bạn có thể có những thông tin sau:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  5. Lưu các thay đổi đối với tệp kê khai.

Xác minh OAuth

Việc sử dụng một số phạm vi OAuth nhạy cảm có thể yêu cầu tiện ích bổ sung của bạn phải trải qua quy trình xác minh ứng dụng OAuth trước khi bạn có thể xuất bản tiện ích đó. Để biết thêm thông tin chi tiết, vui lòng xem hướng dẫn dưới đây:

Phạm vi bị hạn chế

Một số phạm vi bị hạn chế và phải tuân theo các quy tắc bổ sung giúp bảo vệ dữ liệu người dùng. Nếu bạn dự định xuất bản một tiện ích bổ sung cho Gmail hoặc Editor sử dụng một hoặc nhiều phạm vi bị hạn chế, thì tiện ích bổ sung đó phải tuân thủ tất cả các quy định hạn chế được chỉ định trước khi có thể xuất bản.

Hãy xem danh sách đầy đủ các phạm vi bị hạn chế trước khi bạn tìm cách xuất bản. Nếu tiện ích bổ sung của bạn sử dụng bất kỳ phạm vi nào trong số này, thì bạn phải tuân thủ Các yêu cầu bổ sung đối với phạm vi API cụ thể trước khi xuất bản.

Tiện ích Google Workspace Developer Tools cho Visual Studio Code cung cấp thông tin chẩn đoán cho tất cả các phạm vi, bao gồm cả nội dung mô tả phạm vi và liệu phạm vi đó có nhạy cảm hay bị hạn chế hay không.

Phạm vi của tiện ích bổ sung dành cho trình chỉnh sửa

Khi bạn tạo một tiện ích bổ sung cho Trình chỉnh sửa, các phạm vi bắt buộc sẽ do dịch vụ và phương thức Apps Script mà mã tiện ích bổ sung sử dụng xác định. Ví dụ: một tiện ích bổ sung của Trang tính có thể cần phạm vi https://www.googleapis.com/auth/spreadsheets.readonly để đọc thông tin từ nhiều Trang tính.

Apps Script sẽ tự động xác định các phạm vi mà những dịch vụ bạn sử dụng yêu cầu khi bạn thêm mã vào dự án tập lệnh. Đối với các tiện ích bổ sung của Trình chỉnh sửa, bạn thường chỉ cần dựa vào tính năng tự động thu thập phạm vi này thay vì tự xác định phạm vi và đặt chúng một cách rõ ràng.

Nếu bạn không đặt phạm vi một cách rõ ràng và tiện ích bổ sung Trình chỉnh sửa của bạn chỉ đọc hoặc ghi vào tệp trình chỉnh sửa đang mở, hãy thêm nhận xét sau vào một trong các tệp dự án tập lệnh của bạn:

  /**
   * @OnlyCurrentDoc
   */

Chú thích này yêu cầu Apps Script thu hẹp phạm vi tệp của trình chỉnh sửa mà nó đặt thành currentonly. Ví dụ: nếu thêm nhận xét này vào một tệp dự án tập lệnh của tiện ích bổ sung Google Trang tính, thì bạn đang chỉ định rằng tiện ích bổ sung chỉ cần có quyền hoạt động trên Trang tính hiện đang mở, chứ không cần có quyền hoạt động trên bất kỳ Trang tính nào khác mà người dùng có thể có trong Google Drive. Ngược lại, bạn không nên sử dụng nhận xét này nếu tiện ích bổ sung Trang tính của bạn cần đọc hoặc ghi dữ liệu trong một Trang tính mà người dùng hiện chưa mở.