ניהול אנשי קשר באמצעות פרוטוקול CardDAV
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
ניתן להציג ולנהל את אנשי הקשר באמצעות פרוטוקול CardDAV של Google.
אנשי הקשר נשמרים בחשבון Google של המשתמש; ברוב שירותי Google יש
גישה לרשימת אנשי הקשר. אפליקציית הלקוח שלך יכולה להשתמש ב-CardDAV API כדי
ליצור אנשי קשר חדשים, לערוך או למחוק אנשי קשר קיימים, ולשלוח שאילתות על אנשי קשר
שתואמים לקריטריונים מסוימים.
מפרטים
המפרט המלא לא מיושם, אבל לקוחות רבים כמו
אנשי קשר של Apple iOSTM
ו-macOS אמורים לפעול באופן הדדי באופן תקין.
התמיכה של Google ב-CardDAV בכל מפרט רלוונטי היא:
ב-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.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- פנקס הכתובות
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- יצירת קשר
- 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 של איש הקשר.
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-07-25 (שעון UTC).
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-07-25 (שעון UTC)."],[[["\u003cp\u003eGoogle Contacts can be accessed and managed using the CardDAV protocol, enabling client applications to create, edit, delete, and query contacts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV implementation requires OAuth 2.0 for authentication and HTTPS for secure connections.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should discover resource URIs dynamically instead of hardcoding them, as they are subject to change.\u003c/p\u003e\n"],["\u003cp\u003eContact synchronization can be achieved using CTag, sync-token, or ETags to efficiently track and update changes.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV utilizes VCard 3.0 for encoding contact data.\u003c/p\u003e\n"]]],["Google's CardDAV protocol allows managing contacts stored in a Google Account. Client applications can create, edit, delete, and query contacts using the CardDAV API. Key actions include using `PROPFIND` for discovery and obtaining `sync-token` and `getctag` for synchronization. Retrieving contacts is done with `addressbook-multiget REPORT`, while inserting, updating, and deleting contacts utilize `POST`, `PUT` (with `If-Match`), and `DELETE` requests, respectively. Authentication requires HTTPS and OAuth 2.0, and VCard 3.0 is the contact encoding format.\n"],null,["# Manage contacts with the CardDAV protocol\n\nYou can view and manage your contacts using Google's CardDAV protocol.\n\nContacts are stored in the user's Google Account; most Google services have\naccess to the contact list. Your client application can use the CardDAV API to\ncreate new contacts, edit or delete existing contacts, and query for contacts\nthat match particular criteria.\n\nSpecifications\n--------------\n\nThe full specification is not implemented, but many clients such as\n[Apple iOS™ Contacts](https://support.google.com/contacts/answer/2753077?co=GENIE.Platform%3DiOS)\nand macOS should interoperate correctly.\n\nFor each relevant specification, Google's CardDAV support is as follows:\n\n- [rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)](https://tools.ietf.org/html/rfc2518)\n - Supports the HTTP methods `GET`, `PUT`, `DELETE`, `OPTIONS`, and `PROPFIND`.\n - Does *not* support the HTTP methods `LOCK`, `UNLOCK`, `COPY`, `MOVE`, or `MKCOL`.\n - Does *not* support arbitrary (user-defined) WebDAV properties.\n - Does *not* support WebDAV Access Control (rfc3744).\n- [rfc5995: Using POST to Add Members to WebDAV Collections](https://tools.ietf.org/html/rfc5995)\n - Supports creating new contacts without specifying an ID.\n- [rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and\n Versioning (WebDAV)](https://tools.ietf.org/html/rfc6352)\n - Supports the HTTP method `REPORT`, but not all defined reports are implemented.\n - Supports providing a principal collection and a contacts collection.\n- [rfc6578: Collection Synchronization for WebDAV](https://tools.ietf.org/html/rfc6578)\n - Client applications must switch to this mode of operation after the initial sync.\n- [rfc6749: The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)\n - Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use [HTTPS](https://en.wikipedia.org/wiki/HTTPS).\n- [rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)](https://tools.ietf.org/html/rfc6764)\n - Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.\n- Supports [caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV](https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt), which is shared between the CardDAV and CalDAV specifications. The contacts `ctag` is like a resource `ETag`; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.\n- Google uses VCard 3.0 as the contact encoding format. See: [rfc6350: VCard 3.0](https://tools.ietf.org/html/rfc6350).\n\nGoogle's CardDAV requires OAuth 2.0\n-----------------------------------\n\nGoogle's CardDAV interface requires OAuth 2.0. Refer to the linked\ndocumentation below for information on using OAuth 2.0 to access Google APIs:\n\n- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)\n- [Using OAuth 2.0 for Installed Applications](https://developers.google.com/identity/protocols/oauth2/native-app)\n\nConnecting to Google's CardDAV server\n-------------------------------------\n\nThe CardDAV protocol allows discovery of the address book and contact resources\nURIs. You must not hardcode any URI as they could change at any time.\n\nClient applications must use HTTPS, and `OAuth 2.0` authentication must be\nprovided for the user's Google account. The CardDAV server will not\nauthenticate a request unless it arrives over HTTPS with OAuth 2.0\nauthentication of a Google account, and your application is registered on\nDevConsole. Any attempt to connect over HTTP with Basic authentication or with\nan email/password that doesn't match a Google account results in an HTTP\n`401 Unauthorized` response code.\n\nTo use CardDAV, your client program must initially connect to the canonical\ndiscovery path by performing an HTTP `PROPFIND` on: \n\n https://www.googleapis.com/.well-known/carddav\n\nOnce redirected (`HTTP 301`) to an Address Book Resource, your client program\ncan then perform a `PROPFIND` on it to discover the\n`DAV:current-user-principal`, `DAV:principal-URL`, and `addressbook-home-set`\nproperties. Your client program can then discover the principal address book by\nperforming a `PROPFIND` on the `addressbook-home-set` and looking for the\n`addressbook` and `collection` resources. A full description of this process\nis beyond the scope of this document. See\n[rfc6352](https://tools.ietf.org/html/rfc6352) for more details.\n\nThe redirect path returned in the `HTTP 301` response through a `PROPFIND` on\nthe well-known URI must **not** be permanently cached (as per\n[rfc6764](https://tools.ietf.org/html/rfc6764)). Devices should retry well-known\nURI discovery periodically to verify if the cached path is still up to date and\nresync if the path ever changes. Google recommends a rate of every 2-4 weeks.\n\nResources\n---------\n\nCardDAV uses REST concepts. Client applications act on resources that are\ndesignated by their URIs. The current URI structure is specified here to help\ndevelopers understand the concepts in the following section. The structure may\nchange and must not be hardcoded. Rather, the resources should be discovered\naccording to the RFC.\n\n1. **Principal**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e\n2. **Home Set**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists\n3. **Address Book**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default\n4. **Contact**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default/\u003cvar class=\"apiparam\" translate=\"no\"\u003econtactId\u003c/var\u003e\n\nSynchronizing Contacts\n----------------------\n\nThe following is a general description of the operations supported. Developers\nshould look for the details in the relevant RFC. Requests and responses are\nmostly encoded in XML. These are the main operations used by client\napplications for synchronization:\n\n- **Using CTag**\n - Client programs use the `getctag` `PROPFIND` request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a `sync-token` is invalidated. Periodically polling for the `getctag` property will result in throttling.\n- **Using sync-token**\n - Client programs use the `sync-token` `PROPFIND` request on the Address Book to obtain the `sync-token` representing its current state. Client applications must store this value and issue periodic `sync-collection` `REPORT` requests to determine changes since the last issued `sync-token`. Issued tokens are valid for 29 days, and the `REPORT` response will contain a new `sync-token`.\n- **Using ETags**\n - Client applications issue a `getetag` `PROPFIND` request on the Address Book resource (with `DEPTH` header equal to `DEPTH_1`). By maintaining the `ETag` value of each contact, a client program can request the value of contacts that had their `ETag` changed.\n- **Retrieving contacts**\n - Client applications retrieve contacts by issuing an `addressbook-multiget` `REPORT` request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an `ETag` for the contact.\n- **Inserting a contact**\n - Client applications issue a `POST` request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.\n- **Updating a contact**\n - Client applications issue a `PUT` request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.\n - Client applications should include an `If-Match` header with the contact's currently known `ETag`. The server will then reject the `PUT` request (with `HTTP 412`) if the current `ETag` on the server is different from the `ETag` sent by the client program. This allows for optimistic serialization of updates.\n- **Deleting a contact**\n - Client applications delete a contact by issuing a `DELETE` request against the contact URI."]]
