مخاطبین را با پروتکل CardDAV مدیریت کنید
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
با استفاده از پروتکل CardDAV Google می توانید مخاطبین خود را مشاهده و مدیریت کنید.
مخاطبین در حساب Google کاربر ذخیره می شوند. اکثر سرویس های Google به لیست مخاطبین دسترسی دارند. برنامه سرویس گیرنده شما می تواند از CardDAV API برای ایجاد مخاطبین جدید، ویرایش یا حذف مخاطبین موجود و پرس و جو برای مخاطبینی که با معیارهای خاصی مطابقت دارند استفاده کند.
مشخصات
مشخصات کامل اجرا نشده است، اما بسیاری از مشتریان مانند Apple iOS™ Contacts و macOS باید به درستی کار کنند.
برای هر مشخصات مربوطه، پشتیبانی CardDAV Google به شرح زیر است:
CardDAV Google به OAuth 2.0 نیاز دارد
رابط CardDAV Google به OAuth 2.0 نیاز دارد. برای اطلاعات در مورد استفاده از OAuth 2.0 برای دسترسی به Google API به اسناد پیوندی زیر مراجعه کنید:
اتصال به سرور CardDAV Google
پروتکل CardDAV امکان کشف URIهای دفترچه آدرس و منابع تماس را فراهم می کند. شما نباید هیچ یک از URI ها را کدگذاری کنید زیرا ممکن است در هر زمان تغییر کنند.
برنامه های مشتری باید از HTTPS استفاده کنند و احراز هویت OAuth 2.0 باید برای حساب Google کاربر ارائه شود. سرور CardDAV درخواستی را احراز هویت نمی کند مگر اینکه از طریق HTTPS با احراز هویت OAuth 2.0 یک حساب Google دریافت کند و برنامه شما در DevConsole ثبت شده باشد. هر گونه تلاش برای اتصال از طریق HTTP با احراز هویت اولیه یا با ایمیل/گذرواژه‌ای که با حساب Google مطابقت ندارد منجر به کد پاسخ 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 شناخته شده را دوباره امتحان کنند تا بررسی کنند آیا مسیر ذخیره‌شده در حافظه پنهان هنوز به‌روز است یا خیر، و اگر مسیر تغییر کرد، دوباره همگام‌سازی شود. گوگل نرخ هر 2 تا 4 هفته را توصیه می کند.
منابع
CardDAV از مفاهیم REST استفاده می کند. برنامه های کاربردی مشتری بر روی منابعی عمل می کنند که توسط URI آنها تعیین شده اند. ساختار URI فعلی در اینجا مشخص شده است تا به توسعه دهندگان در درک مفاهیم در بخش زیر کمک کند. ساختار ممکن است تغییر کند و نباید کدگذاری شده باشد. در عوض، منابع باید طبق RFC کشف شوند.
- اصلی
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- مجموعه خانه
- 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 در منبع Address Book استفاده می کنند تا تعیین کنند که آیا هر مخاطبی در سرور تغییر کرده است یا خیر و بنابراین آیا نیاز به همگام سازی است یا خیر. ارزش این ملک تضمین می شود که در صورت تغییر هر تماسی تغییر کند. برنامه های سرویس گیرنده باید این مقدار را ذخیره کنند و فقط در همگام سازی اولیه و زمانی که یک sync-token باطل می شود، به عنوان بازگشتی استفاده کنند. نظرسنجی دوره ای برای ویژگی getctag منجر به throttling می شود.
- استفاده از رمز همگام سازی
- برنامه های سرویس گیرنده از درخواست
PROPFIND sync-token در دفترچه آدرس برای به دست آوردن sync-token نشان دهنده وضعیت فعلی آن استفاده می کنند. برنامه های سرویس گیرنده باید این مقدار را ذخیره کنند و درخواست های REPORT sync-collection دوره ای را برای تعیین تغییرات از آخرین sync-token صادر شده صادر کنند. نشانه‌های صادر شده به مدت 29 روز معتبر هستند و پاسخ REPORT حاوی یک sync-token جدید است.
- استفاده از ETags
- برنامه های مشتری یک درخواست
getetag PROPFIND در منبع دفترچه آدرس (با سرصفحه DEPTH برابر با DEPTH_1 ) صادر می کنند. با حفظ مقدار ETag هر مخاطب، یک برنامه مشتری می تواند مقدار مخاطبینی را که ETag آنها تغییر کرده است درخواست کند.
- در حال بازیابی مخاطبین
- برنامه های مشتری با صدور یک درخواست
REPORT addressbook-multiget مخاطبین را بازیابی می کنند. با توجه به فهرستی از URI های مخاطب، گزارش تمام مخاطبین درخواستی را به عنوان مقادیر VCard 3.0 برمی گرداند. هر ورودی شامل یک ETag برای مخاطب است.
- درج یک مخاطب
- برنامه های مشتری درخواست
POST را با مخاطب جدید در قالب VCard 3.0 صادر می کنند. پاسخ شامل شناسه مخاطب جدید خواهد بود.
- به روز رسانی یک مخاطب
- برنامه های مشتری یک درخواست
PUT با مخاطب به روز شده در قالب VCard 3.0 صادر می کنند. اگر مخاطب قبلاً در دفترچه آدرس وجود داشته باشد، مخاطب به‌روزرسانی می‌شود. - برنامه های سرویس گیرنده باید دارای یک سرصفحه
If-Match با ETag در حال حاضر شناخته شده مخاطب باشند. اگر ETag فعلی روی سرور با ETag ارسال شده توسط برنامه مشتری متفاوت باشد، سرور درخواست PUT (با HTTP 412 ) را رد می کند. این امکان پخش خوشبینانه به روز رسانی ها را فراهم می کند.
- حذف یک مخاطب
- برنامه های مشتری با صدور یک درخواست
DELETE در برابر URI مخاطب، یک مخاطب را حذف می کنند.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین به‌روزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-24 بهوقت ساعت هماهنگ جهانی."],[[["\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,["You 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\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\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\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\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\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."]]
