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

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

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

מפרטים

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

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

• rfc2518: תוספי HTTP להרשמה מבוזרת (WebDAV)
  • תמיכה בשיטות ה-HTTP GET, PUT, DELETE, OPTIONS ו-PROPFIND.
  • לא תומך בשיטות ה-HTTP LOCK, UNLOCK, COPY, MOVE או MKCOL.
  • לא תומך במאפייני WebDAV שרירותיים (שהוגדרו על ידי משתמשים).
  • לא תומך בבקרת גישה ל-WebDAV (rfc3744).
• rfc5995: Using POST to Add Members to WebDAV Collections
  • תמיכה ביצירת אנשי קשר חדשים בלי לציין מזהה.
• rfc6352: CardDAV: תוספי vCard לרשתות בהפצה באינטרנט וגם ניהול גרסאות (WebDAV)
  • יש תמיכה בשיטת ה-HTTP REPORT, אבל לא כל הדוחות שהוגדרו מוטמעים.
  • תומכת בהעלאת אוסף של חשבון משתמש ואוסף אנשי קשר.
• rfc6578: Collection Synchronization for 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 יגרום לקוד התגובה 401 Unauthorized ב-HTTP.

כדי להשתמש ב-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. Principal
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Home Set
   • 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 יוביל לוויסות הקצב.
• באמצעות sync-token
  • תוכנות לקוח משתמשות בבקשה sync-token PROPFIND בספר הכתובות כדי לקבל את הערך של 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 של איש הקשר.