Phạm vi uỷ quyền

Người dùng phải uỷ quyền cho các dự án tập lệnh 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 tập lệnh yêu cầu uỷ quyền lần đầu tiên, giao diện người dùng sẽ đưa ra lời nhắc để bắt đầu quy trình uỷ quyền.

Trong quy trình này, giao diện người dùng sẽ cho người dùng biết những quyền mà tập lệnh yêu cầu. Ví dụ: một tập lệnh có thể yêu cầu quyền đọc thư email hoặc tạo sự kiện trên lịch. Dự án tập lệnh xác định từng quyền này là phạm vi OAuth.

Đối với hầu hết các tập lệnh, Apps Script sẽ tự động phát hiện các phạm vi bắt buộc. Bạn có thể xem các phạm vi mà một tập lệnh sử dụng bất cứ lúc nào. Bạn cũng có thể đặt phạm vi một cách rõ ràng trong tệp kê khai bằng cách sử dụng chuỗi URL. Các ứng dụng đã xuất bản, chẳng hạn như tiện ích bổ sung, phải sử dụng phạm vi hẹp nhất có thể.

Trong quy trình uỷ quyền, Apps Script trình bày nội dung mô tả dễ đọc về các phạm vi bắt buộc. Ví dụ: nếu tập lệnh của bạn cần quyền chỉ đọc đối với bảng tính, thì tệp kê khai có thể bao gồm phạm vi https://www.googleapis.com/auth/spreadsheets.readonly. Lời nhắc uỷ quyền yêu cầu người dùng "Xem bảng tính của bạn trên Google".

Một số phạm vi bao gồm các phạm vi khác. Ví dụ: quyền truy cập được uỷ quyền vào https://www.googleapis.com/auth/spreadsheets cho phép truy cập đọc và ghi vào bảng tính.

Đối với một số nền tảng, chẳng hạn như IDE của Apps Script, người dùng sẽ thấy màn hình xin phép bằng OAuth chi tiết. Màn hình này cho phép người dùng chọn các quyền cụ thể để cấp thay vì cấp tất cả các quyền cùng một lúc. Thiết kế tập lệnh để xử lý các quyền OAuth chi tiết.

Xem các phạm vi

Cách xem các phạm vi mà dự án tập lệnh của bạn yêu cầu:

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 Phạm vi OAuth của dự án.

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

Apps Script tự động xác định các phạm vi bắt buộc bằng cách quét mã để tìm các lệnh gọi hàm. Mặc dù điều này là đủ cho hầu hết các tập lệnh, nhưng bạn phải thực hiện kiểm soát trực tiếp hơn đối với các tiện ích bổ sung đã xuất bản, ứng dụng web, ứng dụng Chat và các lệnh gọi đến Chat API.

Đôi khi, Apps Script tự động chỉ định các phạm vi cho phép. Điều này có thể có nghĩa là tập lệnh của bạn yêu cầu người dùng cấp nhiều quyền truy cập hơn mức cần thiết. Đối với các tập lệnh đã xuất bản, hãy thay thế các phạm vi rộng bằng một tập hợp hạn chế đáp ứng nhu cầu của tập lệnh.

Cảnh báo: Luôn sử dụng chế độ cài đặt phạm vi ít hạn chế nhất có thể. Để bảo vệ thông tin người dùng, các tiện ích bổ sung và ứng dụng đã xuất bản khác không được yêu cầu quyền trên phạm vi rộng hơn mức cần thiết.

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 oauthScopes trong tệp kê khai là một mảng các phạm vi mà dự án sử dụng. Cách đặt phạm vi cho dự án:

1. Mở dự án tập lệnh.
2. Ở bên trái, hãy nhấp vào Cài đặt dự án .
3. Chọn hộp đánh dấu Hiển thị tệp kê khai "appsscript.json" trong trình chỉnh sửa.
4. Ở bên trái, hãy nhấp vào Trình chỉnh sửa .
5. Ở bên trái, hãy nhấp vào tệp appsscript.json.
6. Tìm trường cấp cao nhất có nhãn oauthScopes. Nếu không có, bạn có thể thêm thông tin này.
7. Thay thế nội dung của mảng oauthScopes bằng các phạm vi mà bạn muốn dự án sử dụng. Ví dụ:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. Ở trên cùng, hãy nhấp vào Lưu .

Xử lý các quyền OAuth chi tiết

Màn hình xin phép bằng OAuth chi tiết được ra mắt lần đầu tiên trong IDE Apps Script cho những người dùng thực thi tập lệnh trực tiếp. Màn hình xin phép sẽ được phát hành dần cho các nền tảng khác, chẳng hạn như macro, điều kiện kích hoạt và tiện ích bổ sung theo thời gian. Để biết thêm thông tin, hãy xem phần Sự đồng ý OAuth chi tiết trong quá trình thực thi IDE của Google Apps Script.

Màn hình xin phép bằng OAuth chi tiết cho phép người dùng chỉ định từng phạm vi OAuth riêng lẻ cần uỷ quyền. Nhờ đó, người dùng có thể kiểm soát chặt chẽ những dữ liệu tài khoản mà họ chia sẻ với từng tập lệnh. Ví dụ: nếu một tập lệnh yêu cầu các phạm vi email và lịch, thì người dùng có thể chọn cấp quyền truy cập vào Lịch nhưng không cấp quyền truy cập vào Gmail.

Các phần sau đây mô tả cách xử lý quyền OAuth chi tiết.

Tự động yêu cầu cấp quyền cho các phạm vi cần thiết

Nếu một quy trình thực thi yêu cầu các phạm vi cụ thể, bạn có thể yêu cầu người dùng cấp các quyền đó. Tập lệnh của bạn có thể kiểm tra các quyền và tự động yêu cầu các quyền đó nếu thiếu.

Các phương thức sau đây trong lớp ScriptApp sẽ xác thực các quyền và hiển thị lời nhắc uỷ quyền:

• requireScopes(authMode, oAuthScopes): Sử dụng phương thức này cho những luồng dựa vào các phạm vi cụ thể.
• requireAllScopes(authMode): Sử dụng phương thức này nếu một luồng thực thi phụ thuộc vào tất cả các phạm vi dự án.

Ví dụ:

Ví dụ sau đây trình bày cách gọi requireScopes() và requireAllScopes(). Tập lệnh này sử dụng các phạm vi cho Gmail, Trang tính và Lịch. Hàm sendEmail() chỉ yêu cầu các phạm vi cho Gmail và Trang tính, trong khi hàm createEventSendEmail() yêu cầu tất cả các phạm vi mà tập lệnh sử dụng.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Tạo trải nghiệm tuỳ chỉnh cho các phạm vi bị thiếu

Bạn có thể truy xuất trạng thái quyền của người dùng và thiết kế trải nghiệm tuỳ chỉnh. Ví dụ: bạn có thể tắt các tính năng yêu cầu quyền bị thiếu hoặc hiển thị một hộp thoại giải thích yêu cầu. Các phương thức sau đây truy xuất một đối tượng có thông tin về quyền của người dùng, bao gồm cả những phạm vi mà người dùng đã uỷ quyền và một URL để yêu cầu mọi phạm vi còn thiếu:

• getAuthorizationInfo(authMode, oAuthScopes): Kiểm tra trạng thái quyền cho các phạm vi cụ thể.
• getAuthorizationInfo(authMode): Kiểm tra trạng thái quyền cho tất cả các phạm vi dự án.

Để lấy thông tin chi tiết về quyền từ đối tượng thông tin uỷ quyền, chẳng hạn như danh sách các phạm vi được uỷ quyền và URL để yêu cầu các quyền còn thiếu, hãy sử dụng các phương thức từ lớp AuthorizationInfo.

Ví dụ:

Ví dụ sau đây cho thấy cách sử dụng getAuthorizationInfo() để bỏ qua các tính năng mà người dùng chưa cấp phạm vi bắt buộc. Điều này cho phép phần còn lại của quy trình thực thi tiếp tục mà không cần nhắc nhở về việc uỷ quyền cho các phạm vi bị thiếu.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("[e-mail]", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

Đảm bảo rằng các lần thực thi điều kiện kích hoạt có quyền

Các hàm liên kết với điều kiện kích hoạt sẽ chạy tự động và người dùng có thể không có mặt để cấp quyền. Bạn nên sử dụng requireScopes(authMode, oAuthScopes) trước khi cài đặt điều kiện kích hoạt. Thao tác này nhắc người dùng cấp các quyền còn thiếu và không cho phép cài đặt điều kiện kích hoạt nếu không có các quyền đó.

Ví dụ:

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}

function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

Xác minh OAuth

Một số phạm vi OAuth là nhạy cảm vì chúng cho phép truy cập vào Dữ liệu người dùng của Google. Nếu dự án tập lệnh của bạn sử dụng các phạm vi cho phép truy cập vào dữ liệu người dùng, thì dự án đó phải trải qua quy trình xác minh ứng dụng sử dụng giao thức OAuth trước khi bạn có thể xuất bản công khai dự án đó dưới dạng một ứng dụng web hoặc tiện ích bổ sung. Để biết thêm thông tin, hãy xem các hướng dẫn sau:

• 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ế

Ngoài các phạm vi nhạy cảm, một số phạm vi được phân loại là 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 xuất bản một ứng dụng sử dụng các phạm vi bị hạn chế, thì ứng dụng đó phải tuân thủ tất cả các quy cách.

Hãy xem danh sách đầy đủ các phạm vi bị hạn chế trước khi xuất bản. Các ứng dụng tuân thủ phải tuân theo Các yêu cầu bổ sung đối với các phạm vi API cụ thể.

Tránh sử dụng các phạm vi bị hạn chế nếu có thể để đơn giản hoá quy trình xem xét. Bạn có thể thoải mái sử dụng các phạm vi bị hạn chế cho các ứng dụng không công khai.