نقل البيانات من واجهة برمجة تطبيقات إعدادات البريد الإلكتروني

يتناول هذا المستند الاختلافات الرئيسية بين Email Settings API وGmail API. يمكنك استخدام هذا الدليل للمساعدة في نقل بيانات تطبيقك إلى Gmail API.

تفويض الطلبات

مثل واجهة برمجة التطبيقات Email Settings API، تستخدم واجهة برمجة التطبيقات Gmail API بروتوكول OAuth 2.0 للقيام بعمليات تفويض الطلبات. يتمثل أحد الاختلافات الرئيسية في أنّ أذونات Gmail API محدودة بمستخدم فردي، بدلاً من النطاق بأكمله. وهذا يعني أنّ منح الإذن لحساب مشرف نطاق لا يسمح لك بنقل رسائل البريد الإلكتروني للمستخدمين الآخرين في النطاق. بدلاً من ذلك، عليك استخدام حسابات الخدمة العادية التي تملك تفويضًا على مستوى النطاق والمُدرَجة في القائمة البيضاء في وحدة تحكُّم المشرف ل إنشاء رمز المصادقة المناسب.

استخدمت واجهة برمجة التطبيقات Email Settings API النطاق التالي:

https://apps-apis.google.com/a/feeds/emailsettings/2.0/

في ما يلي النطاقات المكافئة في Gmail API:

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

تغييرات البروتوكول

تستخدم واجهة برمجة التطبيقات Email Settings API بروتوكول GDATA المستنِد إلى XML. تستخدم واجهة برمجة التطبيقات Gmail API تنسيق ملف برمجي JSON. بما أنّ الإعدادات تتألف في الغالب من أزواج مفتاح/قيمة، فإنّ حِزم البيانات المرسَلة متشابهة من الناحية المفهومية بين الإصدارات.

مثال على إنشاء تصنيف:

واجهة برمجة التطبيقات 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>

Gmail API

POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
}

استخدِم مكتبات العملاء المقدَّمة بدلاً من تنفيذ البروتوكول مباشرةً.

إدارة التصنيفات

لإدارة التصنيفات في Gmail API، استخدِم المورد Labels.

الإعداد القديم الإعداد الجديد ملاحظات
labelId id
التصنيف الاسم
unreadCount messagesUnread
الظهور labelListVisibility ‫SHOW أصبح الآن labelShow
HIDE أصبح الآن labelHide

التغييرات الأخرى:

  • عند تعديل التصنيفات أو حذفها، تشير واجهة برمجة التطبيقات Gmail API إلى التصنيفات حسب رقم التعريف بدلاً من الاسم.

إدارة الفلاتر

لإدارة الفلاتر في Gmail API، استخدِم مرجع الفلاتر.

الإعداد القديم الإعداد الجديد ملاحظات
من criteria.from
إلى criteria.to
الموضوع criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds استخدام INBOX كرقم تعريف التصنيف
shouldMarkAsRead action.removeLabelIds استخدام UNREAD كرقم تعريف التصنيف
shouldStar action.addLabelIds استخدام STARRED كرقم تعريف التصنيف
التصنيف action.addLabelIds استخدِم رقم تعريف التصنيف لإضافته.
forwardTo action.forward
shouldTrash action.addLabelIds استخدام TRASH كرقم تعريف التصنيف
neverSpam action.removeLabelIds استخدام SPAM كرقم تعريف التصنيف

التغييرات الأخرى:

  • في حال إضافة تصنيف مستخدم غير متوفّر، يجب إنشاؤه صراحةً باستخدام الأسلوب labels.create.

إدارة الأسماء البديلة للبريد الإلكتروني

لإدارة الأسماء المستعارة للبريد الإلكتروني في Gmail API، استخدِم المورد SendAs.

الإعداد القديم الإعداد الجديد
الاسم displayName
معالجة sendAsEmail
replyTo replyToAddress
makeDefault isDefault

إدارة المقاطع على الويب

لم تعُد إعدادات "المقتطف من الويب" متاحة من خلال واجهة برمجة التطبيقات.

إدارة إعدادات إعادة التوجيه التلقائي

لإدارة إعادة التوجيه التلقائي في Gmail API، استخدِم مرجع الإعدادات.

الإعداد القديم الإعداد الجديد ملاحظات
تفعيل مفعّلة
forwardTo emailAddress
إجراء التصرف ‫KEEP أصبح الآن leaveInInbox
ARCHIVE أصبح الآن archive
DELETE أصبح الآن trash
MARK_READ أصبح الآن markRead

التغييرات الأخرى:

  • يجب إنشاء عناوين إعادة التوجيه وإثبات ملكيتها قبل استخدامها.
  • يمكن إدارة عناوين إعادة التوجيه من خلال مورد ForwardingAddresses.

إدارة إعدادات بروتوكول مكتب البريد (POP)

لإدارة إمكانية الوصول إلى بروتوكول POP في Gmail API، استخدِم مرجع الإعدادات.

الإعداد القديم الإعداد الجديد ملاحظات
تفعيل accessWindow يتم إيقافه عند ضبطه على disabled
enableFor accessWindow ‫ALL_MAIL أصبح الآن allMail
MAIL_FROM_NOW_ON أصبح الآن fromNowOn
إجراء التصرف ‫KEEP أصبح الآن leaveInInbox
ARCHIVE أصبح الآن archive
DELETE أصبح الآن trash
MARK_READ أصبح الآن markRead

إدارة إعدادات بروتوكول IMAP

لإدارة الوصول إلى بروتوكول IMAP في Gmail API، استخدِم مرجع الإعدادات.

الإعداد القديم الإعداد الجديد
تفعيل مفعّلة

إدارة إعدادات الردّ التلقائي في وضع "الإجازة"

لإدارة الردّ التلقائي في وضع "الإجازة" في Gmail API، استخدِم مرجع الإعدادات.

الإعداد القديم الإعداد الجديد
contactsOnly restrictToContacts
domainOnly restrictToDomain
تفعيل enableAutoReply
endDate endTime
رسالة responseBodyHtml
responseBodyPlainText
startDate startTime
الموضوع responseSubject

إدارة إعدادات التوقيع

لإدارة التوقيعات الإلكترونية في Gmail API، استخدِم المورد SendAs.

الإعداد القديم الإعداد الجديد
توقيع توقيع

التغييرات الأخرى:

  • تتم الآن إدارة التوقيعات لكل عنوان بديل.

إدارة إعدادات اللغة

لإدارة إعدادات اللغة في Gmail API، استخدِم مرجع الإعدادات.

الإعداد القديم الإعداد الجديد
language displayLanguage

يُرجى الرجوع إلى دليل إدارة إعدادات اللغة للحصول على مزيد من المعلومات.

إدارة إعدادات التفويض

لإدارة التفويض في Gmail API، استخدِم المرجع المفوّضون.

الإعداد القديم الإعداد الجديد
معالجة delegateEmail
status verificationStatus

التغييرات الأخرى:

  • معلومات عامة
    • لاستخدام أي من طرق التفويض (بما في ذلك delegates.create) ، يجب تفعيل حساب المستخدم المفوِّض في Gmail. وهذا يعني، على سبيل المثال، أنّه لا يمكن تعليق المستخدم المفوّض في Google Workspace.
    • لا يمكن استخدام عنوان بريد إلكتروني بديل كمدخل لعنوان البريد الإلكتروني المفوَّض لأي من ال methods الجديدة. يجب الإشارة إلى المستخدم المفوَّض من خلال عنوان بريده الإلكتروني الأساسي.
  • delegates.create
    • يمكن الآن استخدام هذه الطريقة لإنشاء علاقات تفويض على مستوى عدة نطاقات تنتمي إلى Google Workspace المؤسسة نفسها.
    • يمكن الآن استخدام هذه الطريقة للمستخدمين الذين يطلبون تغيير كلمة المرور عند تسجيل دخولهم التالي.
    • في حال نجاح هذه الطريقة، تعرض مورد Users.settings.delegates في نص الاستجابة بدلاً من نص استجابة فارغ.
    • إذا تم إيقاف أيّ من المستخدمَين المفوّضَين أو المفوَّض لهم (مثلاً، تم تعليقهما في Google Workspace)، ستتعذّر تنفيذ هذه الطريقة بظهور خطأ HTTP 4XX بدلاً من خطأ HTTP 500.
  • delegates.delete
    • يمكن الآن استخدام هذه الطريقة لحذف المفوَّضين الذين لديهم أي قيمة verificationStatus، بدلاً من المفوَّضين الذين لديهم القيمة accepted أو expired فقط.
  • delegates.get
    • هذه طريقة جديدة، وقد تكون مفضّلة على طريقة delegates.list حسب الحاجة.

إدارة الإعدادات العامة

لم تعُد الإعدادات العامة متاحة من خلال واجهة برمجة التطبيقات.