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

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

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

מפרטים

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

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

• rfc2518: תוספי HTTP עבור הרשאה מבוזרת (WebDAV)
  • יש תמיכה בשיטות HTTP GET, PUT, DELETE, OPTIONS ו-PROPFIND.
  • לא תומך בשיטות HTTP LOCK, UNLOCK, COPY, MOVE או MKCOL.
  • לא תומך בנכסי WebDAV שרירותיים (בהגדרת המשתמש).
  • המדיניות לא תומכת בבקרת גישה מסוג WebDAV (rfc3744).
• rfc5995: שימוש ב-POST כדי להוסיף חברים לאוספים של WebDAV
  • תומך ביצירת אנשי קשר חדשים ללא ציון מזהה.
• rfc6352: CardDAV: תוספי vCard לכתיבה ולגרסה שמופצת באינטרנט (WebDAV)
  • יש תמיכה בשיטת ה-HTTP REPORT, אבל לא כל הדוחות המוגדרים מיושמים.
  • תומך באספקת אוסף חשבונות ואיסוף אנשי קשר.
• rfc6578: סנכרון אוסף של WebDAV
  • אפליקציות לקוח צריכות לעבור למצב הפעולה הזה אחרי הסנכרון הראשוני.
• rfc6749: מסגרת האישור של OAuth 2.0 ו-rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token usage
  • תמיכה באימות תוכניות לקוח של CardDAV באמצעות אימות HTTP 2.0 של OAuth 2.0. 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. חשבון משתמש
   • 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
  • תוכנות הלקוח משתמשות בבקשת PROPFIND getctag במשאב של פנקס הכתובות כדי לקבוע אם איש קשר כלשהו השתנה בשרת, ולכן אם צריך לסנכרן אותו. הערך של הנכס הזה צפוי להשתנות אם יהיה שינוי באנשי הקשר. אפליקציות לקוח צריכות לאחסן את הערך הזה ולהשתמש בו רק בסנכרון הראשוני וכחלופה במקרה של ביטול התוקף של sync-token. דגימה תקופתית של הנכס getctag תגרום לוויסות נתונים (throttle).
• שימוש באסימון סנכרון
  • תוכנות לקוח משתמשות בבקשת 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 של איש הקשר.