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 hành động thay mặt họ. Khi người dùng chạy một tập lệnh yêu cầu uỷ quyền lần đầu, giao diện người dùng sẽ hiển thị 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 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 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 các quyền riêng lẻ 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 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 manifest bằng cách sử dụng chuỗi URL. Đôi khi, bạn cần phải đặt phạm vi một cách rõ ràng cho một số ứng dụng như tiện ích bổ sung, vì các ứng dụng đã phát hành 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 nội dung mô tả mà người dùng có thể đọc đượ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ó thể đọ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 luồng 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 Google Trang tính của bạn".
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 quyền đọc và ghi vào bảng tính.
Đối với một số nền tảng nơi 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ả quyền cùng một lúc. Bạn cần thiết kế tập lệnh để xử lý các quyền OAuth chi tiết.
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:
- Mở dự án tập lệnh.
- Ở bên trái, hãy nhấp vào biểu tượng Tổng quan .
- Xem các phạm vi trong phần Phạm vi OAuth của dự án.
Đặt phạm vi rõ ràng
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, ứng dụng web, ứng dụng Google Chat và lệnh gọi đến API Google Chat, bạn phải kiểm soát trực tiếp hơn các phạm vi.
Đôi khi, Apps Script tự động chỉ định các dự án có phạm vi rất cởi mở. Đ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 cung cấp nhiều thông tin hơn mức cần thiết, đây là một phương pháp không tốt. Đối với các tập lệnh đã xuất bản, bạn phải thay thế phạm vi rộng bằng một tập hợp hạn chế hơn, chỉ bao gồm các nhu cầu của tập lệnh và không hơn thế.
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à dự án sử dụng. Để đặt phạm vi của dự án, hãy làm như sau:
- Mở dự án tập lệnh.
- Ở bên trái, hãy nhấp vào biểu tượng Cài đặt dự án .
- Chọn hộp đánh dấu Hiện tệp kê khai "appsscript.json" trong trình chỉnh sửa.
- Ở bên trái, hãy nhấp vào biểu tượng Trình chỉnh sửa .
- Ở bên trái, hãy nhấp vào tệp
appsscript.json. - 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 đó. - Trường
oauthScopeschỉ đị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ụ:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/spreadsheets.readonly", "https://www.googleapis.com/auth/userinfo.email" ], ... } - Ở 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 phạm vi OAuth riêng lẻ mà họ muốn uỷ quyền. Các 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 đó với Lịch Google, chứ không phải Gmail. Với các quyền OAuth chi tiết, người dùng có thể chọn chỉ cấp quyền cho Lịch chứ không phải Gmail.
Các phần sau đây mô tả các cách chính để xử lý các 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 quyền cho 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 luồ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. Nếu chưa, tập lệnh sẽ tự động yêu cầu người dùng 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 bị 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ả phạm vi mà tập lệnh của bạn sử dụng.requireAllScopes(authMode): Hãy sử dụng phương thức này nếu 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("dana@example.com", "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("dana@example.com", "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ế một 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 hiển thị một hộp thoại tuỳ chỉnh giải thích về các quyền bị thiếu. Các phương thức sau đây sẽ lấy 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 bị thiếu:
getAuthorizationInfo(authMode, oAuthScopes): Sử dụng phương thức này để kiểm tra trạng thái quyền cho các phạm vi cụ thể.getAuthorizationInfo(authMode): Sử dụng phương thức này để kiểm tra trạng thái quyền cho tất cả các phạm vi mà tập lệnh của bạn sử dụng.
Để 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 bị thiếu, hãy sử dụng các phương thức trong lớp AuthorizationInfo.
Ví dụ:
Ví dụ sau đây cho thấy cách gọi phương thức getAuthorizationInfo(authMode, oAuthScopes) để bỏ qua các tính năng cụ thể trong luồng thực thi mà các phạm vi bắt buộc chưa được cấp. Thao tác này cho phép phần còn lại của luồng 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 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("dana@example.com", "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...
}
Xác minh OAuth
Một số phạm vi OAuth nhất định là nhạy cảm vì 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 khách OAuth trước khi bạn có thể phát hành công khai 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:
- 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 nhất định được phân loại là 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 ứ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ế đã 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 ứng dụng 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.