ניהול אנשי קשר באמצעות פרוטוקול CardDAV

ניתן להציג ולנהל את אנשי הקשר באמצעות פרוטוקול CardDAV של Google.

אנשי הקשר נשמרים בחשבון Google של המשתמש; ברוב שירותי Google יש גישה לרשימת אנשי הקשר. אפליקציית הלקוח שלך יכולה להשתמש ב-CardDAV API כדי ליצור אנשי קשר חדשים, לערוך או למחוק אנשי קשר קיימים, ולשלוח שאילתות על אנשי קשר שתואמים לקריטריונים מסוימים.

מפרטים

המפרט המלא לא מיושם, אבל לקוחות רבים כמו אנשי קשר של Apple iOSTM ו-macOS אמורים לפעול באופן הדדי באופן תקין.

התמיכה של Google ב-CardDAV עבור כל מפרט רלוונטי היא:

• rfc2518: תוספי HTTP להרשמה מבוזרת (WebDAV)
  • תמיכה ב-methods GET, PUT, DELETE, OPTIONS ו- PROPFIND
  • לא תומך בשיטות ה-HTTP LOCK, UNLOCK, COPY, MOVE או MKCOL.
  • לא תומכת בנכסי WebDAV שרירותיים (בהגדרת המשתמש).
  • לא תומכת ב-WebDAV Access Control (rfc3744).
• rfc5995: שימוש ב-POST כדי להוסיף חברים לאוספים של WebDAV
  • תומך ביצירת אנשי קשר חדשים ללא ציון מזהה.
• rfc6352: CardDAV: תוספי vCard לרשתות בהפצה באינטרנט וגם ניהול גרסאות (WebDAV)
  • תומכת בשיטת ה-HTTP REPORT, אך לא כל הדוחות המוגדרים .
  • תומכת בהעלאת אוסף של חשבון משתמש ואוסף אנשי קשר.
• 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 של rfc6764.
• תמיכה 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 APIs:

• שימוש ב-OAuth 2.0 כדי לגשת ל-Google APIs
• שימוש ב-OAuth 2.0 לאפליקציות מותקנות

התחברות לשרת CardDAV של Google

פרוטוקול CardDAV מאפשר גילוי של פנקס הכתובות ומשאבים ליצירת קשר מזהי URI. אין לכתוב בתוך הקוד URI כלשהו, כיוון שהוא עשוי להשתנות בכל שלב.

אפליקציות לקוח חייבות להשתמש ב-HTTPS, ואימות OAuth 2.0 חייב להיות סופקו לחשבון Google של המשתמש. שרת CardDAV לא לאמת בקשה, אלא אם היא מגיעה דרך HTTPS עם OAuth 2.0 של חשבון Google, והאפליקציה שלך רשומה ב- ב-DevConsole. כל ניסיון להתחבר באמצעות HTTP באמצעות אימות בסיסי או עם כתובת אימייל/סיסמה שלא תואמים לחשבון Google גורמת ל-HTTP קוד תגובה 401 Unauthorized.

כדי להשתמש ב-CardDAV, תוכנת הלקוח צריכה תחילה להתחבר אל הדף הקנוני נתיב הגילוי על ידי ביצוע HTTP PROPFIND ב:

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.

1. חשבון משתמש
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. מערכת בית
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. פנקס הכתובות
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. יצירת קשר
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

סנכרון אנשי קשר

ריכזנו כאן תיאור כללי של הפעולות הנתמכות. מפתחים לחפש את הפרטים ב-RFC הרלוונטי. הבקשות והתשובות הן מקודדות בעיקר ב-XML. אלו הפעולות העיקריות שבהן משתמש הלקוח אפליקציות לסנכרון:

• שימוש ב-CTag
  • תוכניות לקוח משתמשות בבקשה getctag PROPFIND בפנקס הכתובות כדי לקבוע אם איש קשר כלשהו השתנה בשרת ולכן אם נדרש סנכרון. הערך של הנכס הזה ישתנה אם איש הקשר ישתנה. אפליקציות לקוח לאחסן את הערך הזה ולהשתמש בו רק בסנכרון הראשוני חלופה כאשר sync-token לא תקף. עורכים מדי פעם סקרים לצורך נכס getctag יגרום לויסות נתונים (throttle).
• שימוש באסימון הסנכרון
  • תוכנות לקוח משתמשות בבקשת PROPFIND sync-token בכתובת מזמינים עד לקבלת sync-token שמייצג את המצב הנוכחי. לקוח/ה אפליקציות חייבות לאחסן את הערך הזה ולהנפיק sync-collection לפרקים REPORT בקשות לקביעת שינויים מאז ההנפקה האחרונה sync-token. אסימונים שהונפקו תקפים למשך 29 ימים. REPORT התשובה תכיל sync-token חדש.
• שימוש ב-ETags
  • אפליקציות לקוח מנפיקות בקשת 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 של איש הקשר.