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 cho người dùng biết tập lệnh muốn có quyền làm gì. Ví dụ: một tập lệnh 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 xác định từng quyền này dưới dạng 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 những phạm vi bạn cần; 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. Đôi khi, bạn cần đặt phạm vi một cách rõ ràng cho một số ứng dụng nhất định, chẳng hạn như tiện ích bổ sung, vì các ứng dụng đã xuất bản phải luôn sử dụng phạm vi hẹp nhất có thể.

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ề 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ể có phạm vi https://www.googleapis.com/auth/spreadsheets.readonly. Trong quy trình uỷ quyền, một tập lệnh có phạm vi này sẽ yêu cầu người dùng cho phép ứng dụng này "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ụ: khi được uỷ quyền, phạm vi 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 mà tập lệnh chạy, chẳng hạn như chạy tập lệnh trực tiếp từ IDE Apps Script, người dùng sẽ thấy màn hình đồng ý OAuth chi tiết. Điều 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. Bạn cần thiết kế tập lệnh để xử lý quyền OAuth chi tiết.

Xem các phạm vi

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

Đặ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, ứng dụng web, ứng dụng Google Chat và các lệnh gọi đến Google Chat API, bạn phải thực hiện kiểm soát trực tiếp hơn đối với các phạm vi.

Đôi khi, Apps Script tự động chỉ định cho các dự án những phạm vi rất cho phép. Điều này có nghĩa là tập lệnh của bạn yêu cầu người dùng cung cấp nhiều thông tin hơn mức cần thiết, đây là một hành vi không nên làm. Đối với các tập lệnh đã xuất bản, bạn phải thay thế các phạm vi rộng bằng một tập hợp hạn chế hơn để đáp ứng nhu cầu của tập lệnh 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à dự án sử dụng. Để đặt phạm vi cho dự án, hãy làm như sau:

  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. 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ụ: 
          {         ...         "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 biểu tượng Lưu .

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

Màn hình đồng ý OAuth chi tiết cho phép người dùng chỉ định từng phạm vi OAuth mà họ muốn uỷ quyền. Quyền OAuth chi tiết giúp người dùng kiểm soát chi tiết hơn đối với dữ liệu tài khoản mà họ chọn chia sẻ với từng tập lệnh. Ví dụ: giả sử bạn phát triển một tập lệnh yêu cầu quyền cho cả phạm vi email và lịch. Người dùng có thể chỉ muốn sử dụng tập lệnh của bạn cho các chức năng của tập lệnh này với Lịch Google, chứ không phải Gmail. Với quyền OAuth chi tiết, người dùng có thể chọn chỉ cấp quyền cho Lịch mà không cấp quyền cho Gmail.

Các phần sau đây mô tả những cách chính để 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 luồng thực thi cần có quyền đối với các phạm vi để hoạt động, bạn có thể yêu cầu người dùng cấp các quyền đó trước khi họ có thể sử dụng. Tập lệnh của bạn có thể kiểm tra xem người dùng đã cấp quyền hay chưa và nếu chưa, hãy tự động yêu cầu họ cấp quyền.

Các phương thức sau đây trong lớp ScriptApp cho phép bạn xác thực quyền cho các phạm vi bắt buộc và tự động hiển thị lời nhắc uỷ quyền để yêu cầu mọi quyền còn thiếu:

  • requireScopes(authMode, oAuthScopes): Sử dụng phương thức này cho các luồng thực thi dựa trên một hoặc nhiều phạm vi, nhưng không phải tất cả các phạm vi mà tập lệnh của bạn sử dụng.
  • requireAllScopes(authMode): Sử dụng phương thức này nếu một luồng thực thi dựa vào tất cả các phạm vi mà tập lệnh của bạn sử dụng.

Ví dụ:

Ví dụ sau đây cho thấy cách gọi các phương thức requireScopes(authMode, oAuthScopes) và requireAllScopes(authMode). 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("[email protected]", "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("[email protected]", "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ể lấy thông tin chi tiết về quyền của người dùng đang chạy tập lệnh và thiết kế trải nghiệm tuỳ chỉnh dựa trên trạng thái quyền của họ. Ví dụ: bạn có thể quyết định tắt các tính năng cụ thể của tập lệnh yêu cầu quyền mà người dùng chưa cấp hoặc trình bày một hộp thoại tuỳ chỉnh giải thích về các quyền còn thiếu. Các phương thức sau đây sẽ nhận được 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 cho phép bạn yêu cầu mọi phạm vi còn thiếu:

Để 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 trong lớp AuthorizationInfo.

Ví dụ:

Ví dụ sau đây minh hoạ cách gọi phương thức getAuthorizationInfo(authMode, oAuthScopes) để bỏ qua các tính năng cụ thể trong một quy trình thực thi mà các phạm vi bắt buộc chưa được cấp. Đ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 phải nhắc cấp quyền cho các phạm vi còn 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("[email protected]", "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 có thể tự động chạy trên một số sự kiện nhất định và người dùng có thể không có mặt để cấp thêm quyền. Bạn nên sử dụng requireScopes(authMode, oAuthScopes) trước khi cài đặt mộ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 OAuth trước khi bạn có thể xuất bản công khai dự án đó dưới dạng ứng dụng web hoặc 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ế

Ngoài các phạm vi nhạy cảm, một số phạm vi nhất định đượ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 bạn dự định xuất bản một ứng dụng web hoặc tiện ích bổ sung sử dụng một hoặc nhiều phạm vi bị hạn chế, thì ứng dụng đó 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 ứng dụng của bạn sử dụng bất kỳ API 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 các phạm vi API cụ thể trước khi xuất bản.