Tài liệu này chứa thông tin uỷ quyền và xác thực dành riêng cho Gmail API. Trước khi đọc tài liệu này, hãy nhớ đọc thông tin chung về quy trình xác thực và uỷ quyền của Google Workspace tại Tìm hiểu về quy trình xác thực và uỷ quyền.
Định cấu hình OAuth 2.0 để uỷ quyền
Định cấu hình màn hình đồng ý OAuth và chọn phạm vi để xác định thông tin sẽ hiển thị cho người dùng và người đánh giá ứng dụng, đồng thời đăng ký ứng dụng để bạn có thể xuất bản ứng dụng sau này.
Phạm vi API Gmail
Để xác định cấp truy cập được cấp cho ứng dụng của bạn, bạn cần xác định và khai báo phạm vi uỷ quyền. Phạm vi uỷ quyền là một chuỗi URI OAuth 2.0 chứa tên ứng dụng Google Workspace, loại dữ liệu mà ứng dụng đó truy cập và cấp độ truy cập. Phạm vi là các yêu cầu của ứng dụng để xử lý dữ liệu trên Google Workspace, bao gồm cả dữ liệu Tài khoản Google của người dùng.
Khi ứng dụng của bạn được cài đặt, người dùng sẽ được yêu cầu xác thực các phạm vi mà ứng dụng sử dụng. Nói chung, bạn nên chọn phạm vi tập trung hẹp nhất có thể và tránh yêu cầu các phạm vi mà ứng dụng của bạn không cần. Người dùng sẵn sàng cấp quyền truy cập vào các phạm vi có giới hạn và được mô tả rõ ràng.
Bất cứ khi nào có thể, hãy sử dụng các phạm vi không nhạy cảm để thu hẹp quyền truy cập chỉ vào những tính năng cụ thể mà ứng dụng cần.
Phạm vi không nhạy cảm
Bạn nên dùng các phạm vi Gmail API sau đây cho hầu hết các trường hợp sử dụng:
| Mã phạm vi | Mô tả |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.action.compose |
Quản lý thư nháp và gửi email khi bạn tương tác với tiện ích bổ sung. |
https://www.googleapis.com/auth/gmail.addons.current.message.action |
Xem thư email của bạn khi bạn tương tác với tiện ích bổ sung. |
https://www.googleapis.com/auth/gmail.labels |
Xem và chỉnh sửa nhãn email. |
Phạm vi nhạy cảm
| Mã phạm vi | Mô tả |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.message.metadata |
Xem siêu dữ liệu nội dung email của bạn khi tiện ích bổ sung đang chạy. |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
Xem thư email của bạn khi tiện ích bổ sung đang chạy. |
https://www.googleapis.com/auth/gmail.send |
Gửi email thay mặt bạn. |
Phạm vi bị hạn chế
| Mã phạm vi | Mô tả |
|---|---|
https://mail.google.com/ |
Đọc, soạn thư, gửi và xoá vĩnh viễn tất cả email của bạn khỏi Gmail.
Lưu ý: Chỉ yêu cầu phạm vi này nếu ứng dụng của bạn cần xoá vĩnh viễn và ngay lập tức các luồng và thư, bỏ qua thùng rác. Bạn có thể thực hiện tất cả các thao tác khác bằng cách sử dụng các phạm vi ít hạn chế hơn. |
https://www.googleapis.com/auth/gmail.readonly |
Xem cài đặt và thông báo email của bạn. |
https://www.googleapis.com/auth/gmail.compose |
Quản lý thư nháp và gửi email. |
https://www.googleapis.com/auth/gmail.insert |
Thêm email vào hộp thư của bạn trên Gmail. |
https://www.googleapis.com/auth/gmail.modify |
Đọc, soạn thư và gửi email từ Tài khoản Gmail. Phạm vi này không cho phép xoá vĩnh viễn ngay lập tức các chuỗi tin nhắn và tin nhắn, bỏ qua thùng rác. |
https://www.googleapis.com/auth/gmail.metadata |
Xem siêu dữ liệu email của bạn như nhãn và tiêu đề chứ không phải nội dung email. |
https://www.googleapis.com/auth/gmail.settings.basic |
Xem, chỉnh sửa, tạo hoặc thay đổi chế độ cài đặt email và các bộ lọc của bạn trong Gmail. |
https://www.googleapis.com/auth/gmail.settings.sharing |
Quản lý chế độ cài đặt thư nhạy cảm của bạn, bao gồm cả những người có thể quản lý thư của bạn.
Lưu ý: Các thao tác được bảo vệ bằng phạm vi này chỉ được phép sử dụng cho mục đích quản trị. Các tiện ích này chỉ dành cho khách hàng Google Workspace sử dụng tài khoản dịch vụ có cơ chế uỷ quyền trên toàn miền. |
Các phạm vi trong bảng trước cho biết mức độ nhạy cảm của chúng, theo các định nghĩa sau:
Không nhạy cảm: Các phạm vi này cung cấp phạm vi uỷ quyền nhỏ nhất và chỉ yêu cầu Xác minh ứng dụng OAuth cơ bản. Để biết thêm thông tin, hãy xem Các yêu cầu về quy trình xác minh.
Nhạy cảm: Các phạm vi này cho phép truy cập vào dữ liệu người dùng cụ thể trên Google mà người dùng cho phép ứng dụng của bạn truy cập. Các phạm vi này yêu cầu thêm bước Xác minh ứng dụng OAuth. Để biết thêm thông tin, hãy xem Các yêu cầu về phạm vi nhạy cảm và bị hạn chế.
Bị hạn chế: Các phạm vi này cung cấp quyền truy cập rộng rãi vào dữ liệu người dùng trên Google và yêu cầu Xác minh ứng dụng OAuth có phạm vi bị hạn chế. Để biết thêm thông tin, hãy xem Chính sách dữ liệu người dùng của dịch vụ API của Google và Các yêu cầu bổ sung đối với các phạm vi API cụ thể.
Nếu lưu trữ dữ liệu có phạm vi bị hạn chế trên máy chủ (hoặc truyền dữ liệu), thì bạn phải trải qua quy trình đánh giá bảo mật.
Bạn có thể xem thêm thông tin chi phối việc sử dụng và truy cập vào các API của Gmail khi yêu cầu truy cập vào dữ liệu người dùng trong Chính sách dữ liệu người dùng và nhà phát triển của API Google Workspace.
Nếu ứng dụng của bạn cần quyền truy cập vào bất kỳ API nào khác của Google, bạn cũng có thể thêm các phạm vi đó. Để biết thêm thông tin về các phạm vi API của Google, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.
Để biết thêm thông tin về các phạm vi OAuth 2.0 cụ thể, hãy xem Phạm vi OAuth 2.0 cho các API của Google.
Xác minh OAuth
Để sử dụng một số phạm vi OAuth nhạy cảm, ứng dụng của bạn có thể phải hoàn tất quy trình xác minh OAuth của Google. Câu hỏi thường gặp về quy trình xác minh ứng dụng OAuth có thể giúp bạn xác định xem quy trình này có cần thiết hay không và loại xác minh nào là bắt buộc.