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

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

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

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

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

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

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

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