مخاطبین را با پروتکل CardDAV مدیریت کنید

با استفاده از پروتکل CardDAV Google می توانید مخاطبین خود را مشاهده و مدیریت کنید.

مخاطبین در حساب Google کاربر ذخیره می شوند. اکثر سرویس های Google به لیست مخاطبین دسترسی دارند. برنامه سرویس گیرنده شما می تواند از CardDAV API برای ایجاد مخاطبین جدید، ویرایش یا حذف مخاطبین موجود و پرس و جو برای مخاطبینی که با معیارهای خاصی مطابقت دارند استفاده کند.

مشخصات فنی

مشخصات کامل اجرا نشده است، اما بسیاری از مشتریان مانند Apple iOS™ Contacts و macOS باید به درستی کار کنند.

برای هر مشخصات مربوطه، پشتیبانی CardDAV Google به شرح زیر است:

• rfc2518: برنامه های افزودنی HTTP برای نوشتن توزیع شده (WebDAV)
  • از روش های HTTP GET , PUT , DELETE , OPTIONS و PROPFIND پشتیبانی می کند.
  • از روش های HTTP LOCK , UNLOCK , COPY , MOVE یا MKCOL پشتیبانی نمی کند.
  • ویژگی های WebDAV دلخواه (تعریف شده توسط کاربر) را پشتیبانی نمی کند.
  • از کنترل دسترسی WebDAV (rfc3744) پشتیبانی نمی کند.
• rfc5995: استفاده از POST برای افزودن اعضا به مجموعه های WebDAV
  • از ایجاد مخاطبین جدید بدون تعیین شناسه پشتیبانی می کند.
• rfc6352: CardDAV: برنامه‌های افزودنی کارت مجازی برای نگارش و نسخه‌سازی توزیع‌شده وب (WebDAV)
  • از روش HTTP REPORT پشتیبانی می کند، اما همه گزارش های تعریف شده پیاده سازی نمی شوند.
  • از ارائه یک مجموعه اصلی و یک مجموعه مخاطبین پشتیبانی می کند.
• rfc6578: همگام سازی مجموعه برای WebDAV
  • برنامه های سرویس گیرنده باید پس از همگام سازی اولیه به این حالت عملکرد تغییر کنند.
• rfc6749: چارچوب مجوز OAuth 2.0 و rfc6750: چارچوب مجوز OAuth 2.0: استفاده از توکن حامل
  • از احراز هویت برنامه های مشتری CardDAV با استفاده از تأیید اعتبار HTTP OAuth 2.0 پشتیبانی می کند. گوگل از هیچ روش احراز هویت دیگری پشتیبانی نمی کند. برای امنیت اطلاعات تماس، ما به اتصالات CardDAV برای استفاده از HTTPS نیاز داریم.
• rfc6764: مکان یابی خدمات برای تقویم برنامه های افزودنی به WebDAV (CalDAV) و برنامه های افزودنی کارت مجازی به 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 API به اسناد پیوندی زیر مراجعه کنید:

• استفاده از OAuth 2.0 برای دسترسی به Google API
• استفاده از OAuth 2.0 برای برنامه های نصب شده

اتصال به سرور 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 کشف شوند.

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
  • برنامه های کلاینت از درخواست 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 مخاطب، یک مخاطب را حذف می کنند.