يمكنك عرض جهات الاتصال وإدارتها باستخدام بروتوكول CardDAV من Google.
يتم تخزين جهات الاتصال في حساب المستخدم على Google. تتميز معظم خدمات Google الوصول إلى قائمة جهات الاتصال. يمكن لتطبيق العميل استخدام واجهة برمجة التطبيقات CardDAV من أجل إنشاء جهات اتصال جديدة، وتعديل جهات الاتصال الحالية أو حذفها، وطلب البحث عن جهات الاتصال التي تطابق معايير معينة.
المواصفات
لم يتم تنفيذ المواصفات الكاملة، ولكن العديد من العملاء مثل جهات اتصال Apple iOSTM وأن يعمل نظام التشغيل macOS بشكل صحيح.
لكل مواصفات ذات صلة، يتم دعم CardDAV من Google على النحو التالي:
- SUBJECT2518: إضافات HTTP للتأليف الموزَّع (WebDAV)
- تتيح هذه السياسة استخدام طرق HTTP التالية:
GET
وPUT
وDELETE
وOPTIONS
PROPFIND
- لا يتوافق مع طرق HTTP التالية:
LOCK
أوUNLOCK
أوCOPY
أوMOVE
أوMKCOL
- لا يتوافق مع خصائص WebDAV العشوائية (من تحديد المستخدم).
- لا تتوافق مع ميزة "التحكّم في الوصول إلى WebDAV" (mailto3744).
- تتيح هذه السياسة استخدام طرق HTTP التالية:
- RFC5995: استخدام طريقة POST لإضافة أعضاء إلى مجموعات WebDAV
- يتيح إنشاء جهات اتصال جديدة بدون تحديد معرّف.
- height6352: CardDAV: vCard إضافات إلى التأليف الموزَّع على الويب و
تحديد الإصدارات (WebDAV)
- تتيح طريقة HTTP
REPORT
، ولكن لا تتوفر بعض التقارير المحددة تنفيذها. - يتيح توفير المجموعة الرئيسية ومجموعة جهات الاتصال.
- تتيح طريقة HTTP
- RFC6578: مزامنة مجموعات WebDAV
- يجب تبديل تطبيقات العملاء إلى وضع التشغيل هذا بعد المزامنة الأولية.
- RFC6749: إطار عمل التفويض OAuth 2.0
RFC6750: إطار عمل تفويض OAuth 2.0: استخدام رمز الحامل المميز
- إتاحة مصادقة برامج عميل CardDAV باستخدام بروتوكول OAuth 2.0 HTTP المصادقة. لا تتيح Google استخدام أي طريقة أخرى للمصادقة. للحفاظ على أمان بيانات جهات الاتصال، نشترط استخدام اتصالات CardDAV. HTTPS.
- RFC6764: تحديد موقع الخدمات الخاصة بإضافات التقويم في إضافات WebDAV (CalDAV) و vCard مع إضافات WebDAV (CardDAV)
- يجب أن يتم تجميع عينات عشوائية لعناوين URL لـ CardDAV وفقًا للفقرة 6 من mailto6764.
- يدعم
caldav-ctag-02: علامة كيان مجموعة التقويم (CTag) في CalDAV،
والذي تتم مشاركته بين مواصفات CardDAV وCalDAV. جهات الاتصال
تشبه السمة
ctag
الموردETag
. يتغير عندما يكون هناك أي شيء في جهة الاتصال تم تغيير دفتر العناوين. يسمح هذا لبرنامج العميل بالتعرف بسرعة على أنه لا يحتاج إلى مزامنة أي جهات اتصال تم تغييرها. - تستخدم Google VCard 3.0 كتنسيق ترميز جهات الاتصال. يمكنك الاطّلاع على: RFC6350: VCard 3.0.
يتطلب بروتوكول CardDAV من Google OAuth 2.0
تتطلّب واجهة CardDAV من Google توفّر OAuth 2.0. ارجع إلى الروابط الوثائق أدناه للحصول على معلومات عن استخدام OAuth 2.0 للدخول إلى واجهات برمجة تطبيقات Google:
الاتصال بخادم CardDAV من Google
يسمح بروتوكول CardDAV باكتشاف دفتر العناوين وموارد جهات الاتصال معرّفات الموارد المنتظمة (URI). يجب عدم إجراء ترميز ثابت لأي عنوان URI، إذ يمكن أن يتغير في أي وقت.
يجب أن تستخدم تطبيقات العملاء بروتوكول HTTPS، ويجب أن تكون مصادقة OAuth 2.0
متوافقة
المقدمة لحساب المستخدم على Google. لن يتمكن خادم CardDAV
مصادقة أحد الطلبات ما لم يصل عبر HTTPS من خلال OAuth 2.0
مصادقة حساب Google، وتم تسجيل طلبك في
وحدة تحكم مطوّري البرامج أي محاولة للاتصال عبر HTTP باستخدام المصادقة الأساسية أو باستخدام
يؤدي عنوان البريد الإلكتروني/كلمة المرور التي لا تتطابق مع حساب Google إلى HTTP
رمز الاستجابة 401 Unauthorized
لاستخدام CardDAV، يجب أن يتصل برنامج العميل في البداية بموقعك الإلكتروني.
مسار استكشاف المحتوى من خلال تنفيذ PROPFIND
HTTP على:
https://www.googleapis.com/.well-known/carddav
بعد إعادة توجيهك (HTTP 301
) إلى مورد دفتر العناوين، سيستخدم برنامج العميل
يمكننا بعد ذلك تنفيذ PROPFIND
عليه لاكتشاف
DAV:current-user-principal
وDAV:principal-URL
وaddressbook-home-set
المواقع. ويمكن لبرنامج العميل عندئذٍ اكتشاف دفتر العناوين الرئيسي من خلال
إجراء PROPFIND
على addressbook-home-set
والبحث عن
المرجع addressbook
وcollection
وصف كامل لهذه العملية
ليس نطاق هذه الوثيقة. عرض
rfc6352 لمزيد من التفاصيل.
مسار إعادة التوجيه المعروض في استجابة HTTP 301
من خلال PROPFIND
على
يجب ألا يتم تخزين عنوان URI المعروف بشكل مؤقت (وفقًا
rfc6764). يجب إعادة المحاولة على الأجهزة ومعروفة.
اكتشاف معرف الموارد المنتظم (URI) بشكل دوري للتحقق مما إذا كان المسار المخزّن مؤقتًا لا يزال محدثًا
إلا إذا تغير المسار. تنصح Google بتحديد معدّل كل أسبوعين إلى 4 أسابيع.
الموارد
يستخدم CardDAV مفاهيم REST. وتعمل تطبيقات العميل على الموارد التي التي تحددها معرّفات الموارد المنتظمة (URI). تم تحديد بنية URI الحالية هنا لمساعدتك على فهم المفاهيم الواردة في القسم التالي. قد تغييرها ويجب ألا تكون ذات ترميز ثابت. بدلاً من ذلك، يجب اكتشاف الموارد وفقًا لمعيار RFC.
- مدير المدرسة
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- الطقم المنزلي
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- دفتر العناوين
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- التواصل
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
مزامنة جهات الاتصال
في ما يلي وصف عام للعمليات المتوفرة. المطوّرون يجب أن يبحث عن التفاصيل في RFC ذي الصلة. تُعد الطلبات والردود بترميز XML في الغالب. هذه هي العمليات الرئيسية التي يستخدمها العميل تطبيقات للمزامنة:
- استخدام CTag
- تستخدم برامج العملاء طلب
getctag
PROPFIND
في دفتر العناوين لتحديد ما إذا كانت أي جهة اتصال قد تغيرت على الخادم وبالتالي ما إذا كانت هناك حاجة إلى المزامنة. قيمة هذا الموقع مضمون للتغيير إذا تم تغيير أي جهة اتصال. تطبيقات العميل تخزين هذه القيمة واستخدامها فقط في المزامنة الأولية اتخاذ الإجراء الاحتياطي في حال إيقافsync-token
. سيؤدي إجراء استطلاع دوري في ستؤدي السمةgetctag
إلى تقييد البيانات.
- تستخدم برامج العملاء طلب
- استخدام الرمز المميّز للمزامنة
- تستخدم برامج العملاء طلب
sync-token
PROPFIND
في "العنوان" احجز للحصول علىsync-token
الذي يمثل حالته الحالية. عميل يجب أن تخزِّن التطبيقات هذه القيمة وتُصدرsync-collection
بشكل دوري. طلبان (REPORT
) لتحديد التغييرات منذ آخر إصدارsync-token
تكون الرموز المميّزة الصادرة صالحة لمدة 29 يومًا، وREPORT
سيحتوي الرد علىsync-token
جديد.
- تستخدم برامج العملاء طلب
- استخدام علامات ETag
- تصدر تطبيقات العملاء طلب
getetag
PROPFIND
على "العنوان" مرجع الكتاب (عنوانهDEPTH
يساويDEPTH_1
) من خلال الحفاظ علىETag
لكل جهة اتصال، فيمكن لبرنامج العميل طلب القيمة من جهات الاتصال التي تم تغييرETag
لها.
- تصدر تطبيقات العملاء طلب
- استرداد جهات الاتصال
- تسترد تطبيقات العميل جهات الاتصال من خلال إصدار
طلب "
addressbook-multiget
" للحصول علىREPORT
بالنظر إلى قائمة من معرفات الموارد المنتظمة (URI) لجهة الاتصال، سيعرض التقرير جميع جهات الاتصال المطلوبة كقيم VCard 3.0. على كل يتضمن الإدخالETag
لجهة الاتصال.
- تسترد تطبيقات العميل جهات الاتصال من خلال إصدار
طلب "
- إدراج جهة اتصال
- تصدر تطبيقات العميل طلب
POST
مع جهة الاتصال الجديدة في VCard 3.0. سيحتوي الردّ على رقم تعريف جهة الاتصال الجديدة.
- تصدر تطبيقات العميل طلب
- تعديل جهة اتصال
- تصدر تطبيقات العملاء طلب
PUT
مع جهة الاتصال المعدّلة في تنسيق VCard 3.0 يتم تعديل جهة الاتصال إذا كانت متاحة. في دفتر العناوين. - يجب أن تحتوي تطبيقات العملاء على العنوان
If-Match
مع جهة الاتصال المعروفة حاليًاETag
. سيرفض الخادم بعد ذلك "PUT
". (معHTTP 412
) إذا كانت قيمةETag
الحالية على الخادم تختلف عن قيمةETag
التي يرسلها برنامج العميل. هذا يسمح التسلسل المتفائل للتحديثات.
- تصدر تطبيقات العملاء طلب
- حذف جهة اتصال
- تحذف تطبيقات العملاء جهة اتصال من خلال إصدار طلب
DELETE
. مقابل عنوان URI لجهة الاتصال.
- تحذف تطبيقات العملاء جهة اتصال من خلال إصدار طلب