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

يساعدك هذا المستند في نقل بيانات تطبيقك من واجهة برمجة التطبيقات لإعدادات البريد الإلكتروني المتوقّفة نهائيًا إلى Gmail 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

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

لا تتوفّر إعدادات مقاطع الويب في واجهة برمجة التطبيقات 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.