Tài liệu này trình bày những điểm khác biệt chính giữa API cài đặt email và API Gmail. Bạn có thể tham khảo hướng dẫn này để di chuyển ứng dụng sang API Gmail.
Ủy quyền yêu cầu
Giống như API cài đặt email, API Gmail sử dụng giao thức OAuth 2.0 để uỷ quyền cho các yêu cầu. Một điểm khác biệt chính là các quyền đối với API của Gmail chỉ dành cho một người dùng cá nhân, thay vì toàn bộ miền. Điều này có nghĩa là việc cấp quyền cho một tài khoản quản trị viên miền không cho phép bạn di chuyển thư cho những người dùng khác trong miền. Thay vào đó, bạn phải sử dụng các tài khoản dịch vụ chuẩn có quyền trên toàn miền. Những tài khoản này có trong danh sách cho phép trong Bảng điều khiển dành cho quản trị viên để tạo mã xác thực phù hợp.
API cài đặt email dùng phạm vi này:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Các phạm vi tương đương trong API Gmail là:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Thay đổi giao thức
API cài đặt email sử dụng giao thức GDATA dựa trên XML. API Gmail sử dụng JSON. Vì chế độ cài đặt chủ yếu bao gồm các cặp khoá/giá trị, nên các phiên bản tải trọng sẽ tương tự nhau về mặt khái niệm.
Ví dụ về cách tạo nhãn:
API cài đặt email
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
API Gmail
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Sử dụng Thư viện ứng dụng được cung cấp thay vì trực tiếp triển khai giao thức.
Quản lý nhãn
Để quản lý nhãn trong API Gmail, hãy sử dụng tài nguyên Nhãn.
Chế độ cài đặt cũ | Chế độ cài đặt mới | Ghi chú |
---|---|---|
labelId | id | |
label | tên | |
unreadCount | messagesUnread | |
mức hiển thị | labelListVisibility | SHOW đổi tên thành labelShow HIDE đổi tên thành labelHide |
Thay đổi khác
- Khi cập nhật hoặc xoá nhãn, API Gmail sẽ tham chiếu nhãn theo mã nhận dạng thay vì theo tên.
Quản lý bộ lọc
Để quản lý các bộ lọc trong API Gmail, hãy sử dụng tài nguyên Bộ lọc.
Chế độ cài đặt cũ | Chế độ cài đặt mới | Ghi chú |
---|---|---|
từ | criteria.from | |
tới | criteria.to | |
chủ đề | criteria.subject | |
hasTheWord | criteria.query | |
doesNotHaveTheWord | criteria.negatedQuery | |
hasAttachment | criteria.hasAttachment | |
shouldArchive | action.removeLabelIds | Sử dụng INBOX làm mã nhận dạng nhãn |
shouldMarkAsRead | action.removeLabelIds | Sử dụng UNREAD làm mã nhận dạng nhãn |
shouldStar | action.addLabelIds | Sử dụng STARRED làm mã nhận dạng nhãn |
label | action.addLabelIds | Sử dụng mã nhận dạng của nhãn để thêm |
forwardTo | action.forward | |
shouldTrash | action.addLabelIds | Sử dụng TRASH làm mã nhận dạng nhãn |
neverSpam | action.removeLabelIds | Sử dụng SPAM làm mã nhận dạng nhãn |
Thay đổi khác
- Nếu bạn chưa thêm nhãn người dùng, bạn phải tạo nhãn đó một cách rõ ràng bằng phương thức labels.create.
Quản lý email đại diện gửi bằng địa chỉ
Để quản lý các email đại diện gửi bằng địa chỉ trong API Gmail, hãy sử dụng tài nguyên SendAs.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
tên | displayName |
xử lý | sendAsEmail |
replyTo | replyToAddress |
makeDefault | isDefault |
Quản lý các đoạn nội dung trên web
Chế độ cài đặt Đoạn video trên web không còn hoạt động thông qua API này nữa.
Quản lý chế độ cài đặt tự động chuyển tiếp
Để quản lý tính năng tự động chuyển tiếp trong API Gmail, hãy sử dụng tài nguyên Cài đặt.
Chế độ cài đặt cũ | Chế độ cài đặt mới | Ghi chú |
---|---|---|
enable | đang bật | |
forwardTo | emailAddress | |
hành động | bố trí | KEEP đổi tên thành leaveInInbox ARCHIVE đổi thành archive DELETE đổi tên thành trash MARK_READ đổi tên thành markRead |
Thay đổi khác
- Địa chỉ chuyển tiếp phải được tạo và xác minh trước khi sử dụng
- Bạn có thể quản lý địa chỉ chuyển tiếp thông qua tài nguyên ForwardingAddresses.
Quản lý chế độ cài đặt POP
Để quản lý quyền truy cập POP trong API Gmail, hãy sử dụng tài nguyên Cài đặt.
Chế độ cài đặt cũ | Chế độ cài đặt mới | Ghi chú |
---|---|---|
enable | accessWindow | Đã tắt khi đặt thành disabled |
enableFor | accessWindow | ALL_MAIL đổi tên thành allMail MAIL_FROM_NOW_ON đổi tên thành fromNowOn |
hành động | bố trí | KEEP đổi tên thành leaveInInbox ARCHIVE đổi thành archive DELETE đổi tên thành trash MARK_READ đổi tên thành markRead |
Quản lý chế độ cài đặt IMAP
Để quản lý quyền truy cập IMAP trong API Gmail, hãy sử dụng tài nguyên Cài đặt.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
enable | đang bật |
Quản lý cài đặt thư trả lời tự động khi đi nghỉ
Để quản lý thư trả lời tự động cho kỳ nghỉ trong API Gmail, hãy sử dụng tài nguyên Cài đặt.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
contactsOnly | restrictToContacts |
domainOnly | restrictToDomain |
enable | enableAutoReply |
endDate | endTime |
tin nhắn | phản hồiBodyhtml phản hồiBodyBodyText |
startDate | startTime |
chủ đề | responseSubject |
Quản lý chế độ cài đặt chữ ký
Để quản lý chữ ký email trong API Gmail, hãy sử dụng tài nguyên SendAs.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
Chữ ký | Chữ ký |
Thay đổi khác
- Giờ đây, chữ ký được quản lý theo từng bí danh.
Quản lý chế độ cài đặt ngôn ngữ
Để quản lý chế độ cài đặt ngôn ngữ trong API Gmail, hãy sử dụng tài nguyên Cài đặt.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
language | displayLanguage |
Vui lòng tham khảo hướng dẫn Quản lý chế độ cài đặt ngôn ngữ để biết thêm thông tin.
Quản lý chế độ cài đặt về việc uỷ quyền
Để quản lý tính năng uỷ quyền trong API Gmail, hãy sử dụng tài nguyên Người được uỷ quyền.
Chế độ cài đặt cũ | Chế độ cài đặt mới |
---|---|
xử lý | delegateEmail |
status | verificationStatus |
Thay đổi khác
- Chung
- Để sử dụng bất kỳ phương thức uỷ quyền nào (bao gồm cả delegates.create), người dùng đó phải được bật trong Gmail. Ví dụ: điều đó có nghĩa là người dùng uỷ quyền không thể bị tạm ngưng trongGoogle Workspace.
- Không thể sử dụng bí danh email làm email nhập uỷ quyền cho bất kỳ phương thức mới nào. Người dùng được uỷ quyền phải được giới thiệu theo địa chỉ email chính của họ.
- delegates.create
- Phương thức này hiện có thể được dùng để tạo mối quan hệ uỷ quyền trên nhiều miền thuộc cùng một Google Workspace tổ chức.
- Phương thức này hiện có thể được sử dụng cho những người dùng yêu cầu thay đổi mật khẩu vào lần đăng nhập tiếp theo.
- Nếu thành công, phương thức này sẽ trả về một tài nguyên Users.settings.Delegates trong nội dung phản hồi thay vì nội dung phản hồi trống.
- Nếu một trong hai người dùng uỷ quyền hoặc người dùng được uỷ quyền bị vô hiệu hoá (ví dụ: bị tạm ngưng trong Google Workspace), thì phương thức này sẽ không thành công với lỗi HTTP 4XX thay vì lỗi HTTP 500.
- delegates.delete
- Giờ đây, bạn có thể dùng phương thức này để xoá những uỷ quyền có
verificationStatus,
thay vì chỉ xoá những uỷ quyền là
accepted
hoặcexpired
.
- Giờ đây, bạn có thể dùng phương thức này để xoá những uỷ quyền có
verificationStatus,
thay vì chỉ xoá những uỷ quyền là
- delegates.get
- Đây là một phương thức mới, có thể phù hợp hơn phương thức delegates.list tuỳ theo nhu cầu.
Quản lý chế độ cài đặt chung
Các chế độ cài đặt chung không còn hoạt động thông qua API nữa.