ניתן להציג ולנהל את אנשי הקשר באמצעות פרוטוקול 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).
- יש תמיכה בשיטות HTTP
- rfc5995: שימוש ב-POST כדי להוסיף חברים לאוספים של WebDAV
- תומך ביצירת אנשי קשר חדשים ללא ציון מזהה.
- rfc6352: CardDAV: תוספי vCard לכתיבה ולגרסה שמופצת באינטרנט (WebDAV)
- יש תמיכה בשיטת ה-HTTP
REPORT
, אבל לא כל הדוחות המוגדרים מיושמים. - תומך באספקת אוסף חשבונות ואיסוף אנשי קשר.
- יש תמיכה בשיטת ה-HTTP
- 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:
מתחבר לשרת 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.
- חשבון משתמש
- 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
- תוכנות הלקוח משתמשות בבקשת
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 של איש הקשר.
- אפליקציות לקוח מוחקים איש קשר על ידי שליחת בקשת