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