Di chuyển từ API cài đặt email

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ể sử dụng 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à quyền đối với API Gmail chỉ dành cho một người dùng riêng lẻ, thay vì toàn bộ miền. Điều này có nghĩa là việc uỷ quyền cho tài khoản quản trị viên miền sẽ 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 tài khoản dịch vụ chuẩn có quyền trên toàn miền 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ã thông báo xác thực thích hợp.

API Cài đặt email đã sử dụng phạm vi:

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 về giao thức

Email Settings API sử dụng giao thức GDATA dựa trên XML. API Gmail sử dụng định dạng JSON. Vì các chế độ cài đặt chủ yếu bao gồm các cặp khoá/giá trị, nên tải trọng giữa các phiên bản có khái niệm tương tự nhau.

Ví dụ về cách tạo nhãn:

Email Settings API

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 Labels (Nhãn).

Chế độ cài đặt cũ Chế độ cài đặt mới Ghi chú
labelId id
nhãn tên
unreadCount messagesUnread
mức hiển thị labelListVisibility SHOW hiện là labelShow
HIDE hiện là 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ý 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
shouldMarkAsRead action.removeLabelIds Sử dụng UNREAD làm mã nhãn
shouldStar action.addLabelIds Sử dụng STARRED làm mã nhãn
nhãn 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
neverSpam action.removeLabelIds Sử dụng SPAM làm mã nhãn

Thay đổi khác

  • Nếu chưa có nhãn người dùng, bạn phải tạo nhãn đó một cách rõ ràng bằng cách sử dụng phương thức labels.create.

Quản lý bí danh gửi dưới dạng

Để quản lý bí danh gửi dưới dạng 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 Tên hiển thị
xử lý sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Quản lý đoạn video trên web

Bạn không thể sử dụng chế độ cài đặt của tính năng Đoạn trích trên web thông qua API 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ú
bật đang bật
forwardTo emailAddress
hành động disposition KEEP hiện là leaveInInbox
ARCHIVE hiện là archive
DELETE hiện là trash
MARK_READ hiện là markRead

Thay đổi khác

  • Bạn phải tạo và xác minh địa chỉ chuyển tiếp 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ú
bật accessWindow Tắt khi được đặt thành disabled
enableFor accessWindow ALL_MAIL hiện là allMail
MAIL_FROM_NOW_ON hiện là fromNowOn
hành động disposition KEEP hiện là leaveInInbox
ARCHIVE hiện là archive
DELETE hiện là trash
MARK_READ hiện là 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
bật đang bật

Quản lý chế độ cài đặt thư trả lời tự động khi nghỉ

Để quản lý tính năng tự động trả lời khi vắng mặt 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
bật enableAutoReply
endDate endTime
tin nhắn responseBodyHtml
responseBodyPlainText
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 uỷ quyền

Để quản lý việc 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
trạng thái 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 uỷ quyền phải được bật cho Gmail. Điều đó có nghĩa là, ví dụ: người dùng uỷ quyền không thể bị tạm ngưng trongGoogle Workspace.
    • Bạn không thể dùng email đại diện làm dữ liệu đầu vào email 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 tham chiếu bằng địa chỉ email chính của họ.
  • delegates.create
    • Giờ đây, bạn có thể sử dụng phương thức này để tạo mối quan hệ uỷ quyền trên nhiều miền thuộc cùng một tổ chức Google Workspace.
    • Giờ đây, bạn có thể sử dụng phương thức này cho những người dùng cần 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 phần nội dung phản hồi, thay vì một phần nội dung phản hồi trống.
    • Nếu một trong hai người uỷ quyền hoặc người đượ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ể sử dụng phương thức này để xoá các đại diện có bất kỳ verificationStatus nào, thay vì chỉ các đại diện là accepted hoặc expired.
  • delegates.get
    • Đây là một phương thức mới, có thể được ưu tiên hơn phương thức delegates.list tuỳ thuộc vào nhu cầu.

Quản lý chế độ cài đặt chung

Bạn không thể sử dụng chế độ cài đặt chung thông qua API nữa.