Phạm vi uỷ quyền cho Tiện ích bổ sung dành cho trình chỉnh sửa

Người dùng phải cho phép 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ọ thực hiện 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ẽ hiển thị 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 sẽ cho người dùng biết ứng dụng muốn được phép làm gì. Ví dụ: một tiện ích bổ sung có thể muốn được phép đọc 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 các quyền riêng lẻ này là phạm vi OAuth.

Bạn khai báo phạm vi trong manifest bằng cách sử dụng chuỗi URL. Trong quy trình uỷ quyền, Apps Script sẽ hiển thị cho người dùng nội dung mô tả phạm vi mà con người có thể đọc được. 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 ghi trong tệp kê khai dưới dạng https://www.googleapis.com/auth/documents.currentonly. Trong luồng 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.

Xem phạm vi

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

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

Bạn cũng có thể xem 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 phạm vi mà 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 kiểm soát trực tiếp hơn các phạm vi.

Ví dụ: theo mặc định, Apps Script có thể cấp cho dự án tập lệnh bổ sung phạm vi rất cởi mở https://mail.google.com. 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 đã phát hành, bạn phải thay thế phạm vi này bằng một tập hợp hạn chế hơn, chỉ bao gồm các nhu cầu của tiện ích bổ sung và không được vượt quá phạm vi đó.

Bạn có thể thiết lập rõ ràng các phạm vi mà dự án tập lệnh sử dụng bằng cách chỉnh sửa tệp manifest. 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 của 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 chuỗi. Để đặt 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 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 dành cho trình chỉnh sửa mở rộng Trang tính, bạn có thể có các thành phần 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 thì bạn mới có thể phát hành tiện ích bổ sung đó. Để 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 nhất định bị hạn chế và phải tuân thủ 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 phát hành một tiện ích bổ sung cho Gmail hoặc Trình chỉnh sửa 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ế đã chỉ định thì mới có thể phát hành.

Hãy xem danh sách đầy đủ các phạm vi bị hạn chế trước khi bạn cố gắng xuất bản. Nếu tiện ích bổ sung của bạn sử dụng bất kỳ API nào trong số này, 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 phát hành.

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ụ Apps Script và các phương thức 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 Google Trang tính.

Apps Script sẽ tự động xác định các phạm vi mà các 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 Tiện ích bổ sung của Trình chỉnh sửa, bạn thường chỉ có thể dựa vào tính năng thu thập phạm vi tự động này thay vì tự xác định phạm vi và đặt phạm vi 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 cho trình chỉnh sửa 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:

  /**
   * @OnlyCurrentDoc
   */

Nhận xét này yêu cầu Apps Script thu hẹp phạm vi tệp trình chỉnh sửa mà ứng dụng này đặt thành currentonly. Ví dụ: nếu thêm nhận xét này vào tệp dự án tập lệnh của tiện ích bổ sung Google Trang tính, bạn đang chỉ định rằng tiện ích bổ sung chỉ cần quyền hoạt động trên Trang tính đang mở chứ không phải 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ần đọc hoặc ghi dữ liệu trong một Trang tính mà người dùng hiện chưa mở.