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ề việc xác thực và uỷ quyền của Google Workspace tại 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 đồ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ể 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à 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.
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 thư 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ỉ 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 tài nguyên đó mà 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 tin nhắn và bản 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ả các thao tác đọc/ghi, ngoại trừ việc xoá vĩnh viễn ngay lập tức các chuỗi và tin nhắn, 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 đề thư email, nhưng không đọc 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ệ bằng phạm vi này chỉ được phép sử dụng cho mục đích quản trị. Các API này chỉ dành cho khách hàng Google Workspace sử dụng tài khoản dịch vụ có tính năng uỷ quyền trên toàn miền. |
Bị hạn chế |
https://mail.google.com/ |
Toàn quyền truy cập 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 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á vĩnh viễn các chuỗi và thư ngay lập tức, 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ác phạm vi ít hạn chế hơn. | Bị hạn chế |
Cột Mức sử dụng trong bảng trên cho biết mức độ nhạy cảm 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 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ị cho quy trình xác minh.
Nhạy cảm – Những 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 Dịch vụ API của Google: Chính sách dữ liệu người dùng. Những 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 trên 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 Các 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 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 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 API 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 Dịch vụ API Gmail.
Nếu ứng dụng của bạn cần có 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.
Xác minh OAuth
Để sử dụng một số phạm vi OAuth nhạy cảm, có thể bạn phải trải qua quy trình xác minh OAuth của Google. Đọ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 trải qua quy trình xác minh và loại xác minh bắt buộc. Xem thêm Dịch vụ API của Google: Chính sách dữ liệu người dùng.