Di chuyển từ Email Settings API

Tài liệu này giúp bạn di chuyển ứng dụng của mình từ Email Settings API (API Cài đặt email) không dùng nữa sang Gmail API.

Cấp phép cho yêu cầu

Giống như Email Settings API, Gmail API 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 của Gmail API được giới hạn cho từng người dùng, thay vì cho 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 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ụ tiêu chuẩn có quyền trên toàn miền được thêm vào danh sách cho phép trong Bảng điều khiển dành cho quản trị viên của Google để tạo mã thông báo xác thực phù hợp.

Email Settings API 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 Gmail API 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. Gmail API sử dụng JSON. Vì chế độ cài đặt chủ yếu bao gồm các cặp khoá-giá trị, nên tải trọng về cơ bản là tương tự nhau giữa các phiên bản.

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"
}

Hãy sử dụng thư viện ứng dụng được cung cấp thay vì triển khai trực tiếp giao thức.

Quản lý nhãn

Để quản lý nhãn trong Gmail API, hãy sử dụng tài nguyên labels.

Chế độ cài đặt cũ Chế độ cài đặt mới Ghi chú
labelId id
nhãn tên
unreadCount messagesUnread
khả năng hiển thị labelListVisibility SHOW nay có giá labelShow
HIDE nay có giá labelHide

Thay đổi khác

  • Khi cập nhật hoặc xoá nhãn, Gmail API sẽ tham chiếu đến 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 Gmail API, hãy sử dụng tài nguyên settings.filters.

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ã 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 nhãn người dùng mà bạn muốn thêm chưa tồn tại, 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ý bí danh gửi dưới tên người khác

Để quản lý các bí danh gửi dưới tên khác trong API Gmail, hãy sử dụng tài nguyên settings.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

Chế độ cài đặt đoạn trích trên web không có trong Gmail API.

Quản lý tính năng tự động chuyển tiếp

Để quản lý tính năng chuyển tiếp tự động trong API Gmail, hãy sử dụng tài nguyên settings.

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 nay có giá leaveInInbox
ARCHIVE nay có giá archive
DELETE nay có giá trash
MARK_READ nay có giá 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.
  • Để quản lý địa chỉ chuyển tiếp, hãy sử dụng tài nguyên settings.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 settings.

Chế độ cài đặt cũ Chế độ cài đặt mới Ghi chú
bật accessWindow Bị tắt khi đặt thành disabled
enableFor accessWindow ALL_MAIL nay có giá allMail
MAIL_FROM_NOW_ON nay có giá fromNowOn
hành động disposition KEEP nay có giá leaveInInbox
ARCHIVE nay có giá archive
DELETE nay có giá trash
MARK_READ nay có giá 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 settings.

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 đi vắng

Để quản lý tính năng trả lời tự động khi đi vắng trong API Gmail, hãy dùng tài nguyên settings.

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 settings.sendAs.

Chế độ cài đặt cũ Chế độ cài đặt mới
Chữ ký Chữ ký

Thay đổi khác

  • Giờ đây, bạn có thể quản lý chữ ký theo từng địa chỉ email đại diện.

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 settings.

Chế độ cài đặt cũ Chế độ cài đặt mới
language displayLanguage

Để biết thêm thông tin, hãy xem bài viết Quản lý chế độ cài đặt ngôn ngữ.

Quản lý chế độ cài đặt uỷ quyền

Để quản lý việc uỷ quyền trong API Gmail, hãy dùng tài nguyên settings.delegates.

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 (kể cả settings.delegates.create), người dùng uỷ quyền phải được bật Gmail. Điều đó có nghĩa là, chẳng hạn như người dùng uỷ quyền không thể bị tạm ngưng trong Google Workspace.
    • Bạn không thể sử dụng email đại diện làm thông tin đầu vào email của người được uỷ quyền cho bất kỳ phương thức mới nào. Bạn phải tham chiếu đến một người dùng được uỷ quyền bằng địa chỉ email chính của họ.
  • settings.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 settings.delegates trong nội dung phản hồi, thay vì một nội dung phản hồi trống.
    • Nếu người 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ẽ gặp lỗi HTTP 4XX thay vì lỗi HTTP 500.
  • settings.delegates.delete
    • Giờ đây, bạn có thể sử dụng phương thức này để xoá người được uỷ quyền bằng VerificationStatus bất kỳ, thay vì chỉ những người được uỷ quyền là accepted hoặc expired.
  • settings.delegates.get
    • Đây là một phương thức mới và có thể được ưu tiên hơn phương thức settings.delegates.list tuỳ theo nhu cầu.

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

Chế độ cài đặt chung không có trong Gmail API.