Kính ngắm

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 hành động thay mặt cho họ. Khi người dùng chạy tiện ích bổ sung lần đầu tiên, giao diện người dùng của tiện ích bổ sung 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 cho người dùng biết ứng dụng muốn gì quyền làm những gì. Ví dụ: một tiện ích bổ sung có thể muốn có quyền đọc nội dung 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 tệp kê khai 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 Google Workspace có thể sử dụng thông báo "Đọc tin nhắn hiện tại" được viết trong tệp kê khai dưới dạng https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Trong quy trình ủy 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 cho: Xem email của bạn khi tiện ích bổ sung đang chạy.

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 đang yêu cầu bằng cách thực hiện 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 info_outline.
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 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 oauthScopes mà chỉ khi bạn đặt một cách rõ ràng các phạm vi đó.

Đặt phạm vi rõ ràng

Apps Script tự động xác định phạm vi mà một tập lệnh cần bằng cách quét mã cho các lệnh gọi hàm cần đến chúng. Đố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ụ: Apps Script có thể cho phép dự án tập lệnh tiện ích bổ sung không bắt buộc phạm vi https://mail.google.com 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 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 có giới hạn bao gồm nhu cầu của các tiện ích bổ sung và không hơn nữa.

Bạn có thể đặt rõ phạm vi mà dự án tập lệnh của mình sẽ sử dụng bằng cách chỉnh sửa tệp kê khai. 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 thực hiện 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 các phạm vi mà bạn muốn nó dùng. Ví dụ: đối với một Tiện ích bổ sung của Google Workspace mở rộng Gmail, bạn có thể có các thông tin sau:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

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:

• Xác minh ứng dụng OAuth cho Apps Script
• Ứng dụng chưa được xác minh
• Câu hỏi thường gặp về quy trình xác minh OAuth
• Dịch vụ API của Google: Chính sách dữ liệu người dùng

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 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 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.

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 lịch

Dưới đây là các phạm vi thường dùng cho các tiện ích bổ sung của Google Workspace mở rộng Lịch Google.

Phạm vi trên Drive

Dưới đây là các phạm vi thường dùng cho các tiện ích bổ sung của Google Workspace mở rộng Google Drive.

Phạm vi tiện ích bổ sung dành cho Gmail

Có một vài phạm vi được tạo riêng cho Tiện ích bổ sung của Google Workspace giúp bảo vệ Gmail của người dùng . Bạn phải thêm rõ ràng các phạm vi này vào tệp kê khai tiện ích bổ sung, cùng với mọi phạm vi khác mà mã tiện ích bổ sung yêu cầu.

Dưới đây là các phạm vi thường dùng cho Tiện ích bổ sung Google Workspace mở rộng Gmail; bạn phải thêm các phạm vi có nhãn Bắt buộc vào tệp kê khai Tiện ích bổ sung Google Workspace nếu tiện ích bổ sung của bạn mở rộng Gmail.

Ngoài ra, hãy nhớ thay thế phạm vi https://mail.google.com rất rộng trong tiện ích bổ sung bằng một nhóm phạm vi hẹp hơn cho phép các lượt tương tác mà tiện ích bổ sung cần và không hơn thế.

Mã truy cập

Để bảo vệ dữ liệu người dùng, các phạm vi Gmail được sử dụng trong Chỉ cấp quyền truy cập vào các tiện ích bổ sung của Google Workspace quyền truy cập tạm thời vào dữ liệu người dùng. Để bật quyền truy cập tạm thời, bạn phải gọi hàm hàm GmailApp.setCurrentMessageAccessToken(accessToken) sử dụng mã truy cập làm đối số. Bạn phải lấy mã truy cập từ đối tượng sự kiện hành động.

Sau đây là ví dụ về cách thiết lập mã truy cập để cho phép truy cập vào siêu dữ liệu của thư. Phạm vi duy nhất cần thiết cho ví dụ này là https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Phạm vi của trình chỉnh sửa

Dưới đây là các phạm vi thường được dùng cho các Tiện ích bổ sung của Google Workspace mở rộng Tài liệu, Trang tính, và Trang trình bày.

Các phạm vi khác

Tiện ích bổ sung của bạn có thể yêu cầu thêm phạm vi nếu sử dụng các dịch vụ Apps Script khác. Trong hầu hết trường hợp, bạn có thể cho phép Apps Script phát hiện các phạm vi này và cập nhật tệp kê khai tự động. Khi chỉnh sửa danh sách phạm vi của tệp kê khai, không xoá bất kỳ phạm vi nào trừ phi bạn đang thay thế chúng bằng một phạm vi phù hợp hơn, chẳng hạn như phạm vi hẹp hơn.

Để bạn tham khảo khi cần, sau đây là danh sách các phạm vi Apps Script thường được sử dụng cùng với Tiện ích bổ sung của Google Workspace: