نقل البيانات من Email Settings API

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

السماح بالطلبات

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

استخدمت واجهة برمجة التطبيقات 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، استخدِم مورد labels.

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

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

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

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

لإدارة الفلاتر في Gmail API، استخدِم مورد settings.filters.

الإعداد القديم الإعداد الجديد ملاحظات
من 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، استخدِم مورد settings.sendAs.

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

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

لا تتوفّر إعدادات Web Clip في Gmail API.

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

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

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

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

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

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

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

الإعداد القديم الإعداد الجديد ملاحظات
تفعيل 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، استخدِم مورد settings.

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

إدارة إعدادات الرد التلقائي أثناء العطلة

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

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

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

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

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

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

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

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على إدارة إعدادات اللغة.

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

لإدارة التفويض في Gmail API، استخدِم مورد settings.delegates.

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

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

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

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

لا تتوفّر الإعدادات العامة في واجهة برمجة التطبيقات Gmail API.