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

يتناول هذا المستند الاختلافات الرئيسية بين 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 تنسيق 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، استخدِم مورد التصنيفات.

الإعداد القديم الإعداد الجديد ملاحظات
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

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

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

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

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

الإعداد القديم الإعداد الجديد ملاحظات
تفعيل مفعّلة
forwardTo emailAddress
إجراء disposition ‫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
إجراء disposition ‫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 لحساب المستخدم المفوِّض. وهذا يعني، على سبيل المثال، أنّه لا يمكن تعليق حساب المستخدم المفوِّض في.
    • لا يمكن استخدام عنوان بريد إلكتروني بديل كعنوان بريد إلكتروني مفوَّض لأي من الطرق الجديدة. يجب الإشارة إلى المستخدم المفوض باستخدام عنوان بريده الإلكتروني الأساسي.
  • delegates.create
    • يمكن الآن استخدام هذه الطريقة لإنشاء علاقات تفويض على مستوى نطاقات متعدّدة تابعة للمؤسسة نفسها.
    • يمكن الآن استخدام هذه الطريقة للمستخدمين الذين يحتاجون إلى تغيير كلمة المرور عند تسجيل الدخول في المرة التالية.
    • في حال نجاح العملية، تعرض هذه الطريقة Users.settings.delegates resource في نص الاستجابة، بدلاً من نص استجابة فارغ.
    • إذا تم إيقاف حساب أي من المستخدمين المفوِّض أو المفوض إليه (على سبيل المثال، تم تعليق الحساب في )، ستتعذّر هذه الطريقة وسيظهر خطأ HTTP 4XX بدلاً من خطأ HTTP 500.
  • delegates.delete
    • يمكن الآن استخدام هذه الطريقة لحذف المستخدمين المفوضين الذين لديهم أي verificationStatus، بدلاً من المستخدمين المفوضين الذين لديهم accepted أو expired فقط.
  • delegates.get
    • هذه طريقة جديدة قد تكون مفضّلة على طريقة delegates.list حسب الحاجة.

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

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