راهنمای برنامه نویس CalDAV API

CalDAV یک افزونه از WebDAV است که استانداردی را برای کلاینت‌ها فراهم می‌کند تا به اطلاعات تقویم روی یک سرور از راه دور دسترسی داشته باشند.

گوگل یک رابط CalDAV ارائه می‌دهد که می‌توانید از آن برای مشاهده و مدیریت تقویم‌ها با استفاده از پروتکل CalDAV استفاده کنید.

مشخصات

برای هر یک از مشخصات مربوطه، پشتیبانی CalDAV گوگل به شرح زیر است:

• rfc4918: افزونه‌های HTTP برای نوشتن و نسخه‌بندی توزیع‌شده وب (WebDAV)
  • از متدهای HTTP GET ، PUT ، HEAD ، DELETE ، POST ، OPTIONS ، PROPFIND و PROPPATCH پشتیبانی می‌کند.
  • از متدهای HTTP LOCK ، UNLOCK ، COPY ، MOVE یا MKCOL یا هدر If* (به جز If-Match ) پشتیبانی نمی‌کند.
  • از ویژگی‌های WebDAV دلخواه (تعریف‌شده توسط کاربر) پشتیبانی نمی‌کند.
  • از کنترل دسترسی WebDAV (rfc3744) پشتیبانی نمی‌کند.
• rfc4791: افزونه‌های تقویم‌سازی برای WebDAV (CalDAV)
  • از روش HTTP REPORT پشتیبانی می‌کند. همه گزارش‌ها به جز free-busy-query پیاده‌سازی شده‌اند.
  • از متد HTTP یعنی MKCALENDAR پشتیبانی نمی‌کند.
  • از عملکرد AUDIO پشتیبانی نمی‌کند.
• rfc5545: آی‌کلندر
  • داده‌های نمایش داده شده در رابط CalDAV طبق مشخصات iCalendar قالب‌بندی می‌شوند.
  • در حال حاضر از داده‌های VTODO یا VJOURNAL پشتیبانی نمی‌کند.
  • از افزونه Apple iCal® برای تنظیم ویژگی‌های URL توسط کاربر پشتیبانی نمی‌کند.
• rfc6578: همگام‌سازی مجموعه برای WebDAV
  • برنامه‌های کلاینت باید پس از همگام‌سازی اولیه به این حالت عملیاتی تغییر حالت دهند.
• rfc6638: زمان‌بندی افزونه‌ها در CalDAV
  • از یک «صندوق ورودی» ساده پشتیبانی می‌کند که همیشه خالی است.
  • دعوت‌نامه‌هایی که دریافت می‌کنید به جای اینکه در «صندوق ورودی» شما قرار بگیرند، به طور خودکار به مجموعه «رویدادها»ی شما ارسال می‌شوند.
  • از جستجوی آزاد-مشغول پشتیبانی نمی‌کند.
• caldav-ctag-02: برچسب موجودیت مجموعه تقویم (CTag) در CalDAV
  • ctag تقویم مانند etag منبع است؛ وقتی هر چیزی در تقویم تغییر کند، تغییر می‌کند. این به برنامه‌ی کلاینت اجازه می‌دهد تا به سرعت تشخیص دهد که نیازی به همگام‌سازی هیچ رویداد تغییر یافته‌ای ندارد.
• calendar-proxy: عملکرد پروکسی کاربر تقویم در CalDAV
  • برای بهبود عملکرد همگام‌سازی تقویم از دستگاه‌های iOS که از واگذاری اختیار پشتیبانی نمی‌کنند، استفاده از ویژگی‌های calendar-proxy-read-for یا calendar-proxy-write-for با یک UserAgent iOS با شکست مواجه خواهد شد.

ما هنوز پیاده‌سازی کاملی از تمام مشخصات مربوطه ارائه نکرده‌ایم. با این حال، برای بسیاری از کلاینت‌ها مانند برنامه تقویم اپل، پروتکل CalDAV باید به درستی با یکدیگر تعامل داشته باشد.

توجه: برای امنیت حساب و جلوگیری از سوءاستفاده، گوگل ممکن است کوکی‌هایی را روی برنامه‌های کلاینت که از طریق CalDAV به داده‌ها دسترسی دارند، تنظیم کند.

ایجاد شناسه مشتری شما

برای استفاده از رابط برنامه‌نویسی کاربردی CalDAV، باید یک حساب کاربری گوگل داشته باشید. اگر از قبل حسابی دارید که می‌توانید از آن استفاده کنید، همه چیز آماده است.

قبل از اینکه بتوانید درخواست‌هایی را به CalDAV API ارسال کنید، باید کلاینت خود را با ایجاد یک پروژه در کنسول Google API ثبت کنید.

به کنسول API گوگل بروید. روی ایجاد پروژه کلیک کنید، یک نام وارد کنید و روی ایجاد کلیک کنید.

مرحله بعدی فعال کردن CalDAV API است.

برای فعال کردن API برای پروژه خود، مراحل زیر را انجام دهید:

1. کتابخانه API را در کنسول API گوگل باز کنید . در صورت درخواست، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید. کتابخانه API تمام API های موجود را که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند، فهرست می کند.
2. اگر API مورد نظر برای فعال‌سازی در لیست قابل مشاهده نیست، از جستجو برای یافتن آن استفاده کنید.
3. API مورد نظر خود را انتخاب کنید و سپس روی دکمه‌ی فعال‌سازی کلیک کنید.
4. در صورت درخواست، صورتحساب را فعال کنید.
5. در صورت درخواست، شرایط خدمات API را بپذیرید.

برای انجام درخواست‌های CalDAV API به Client ID و Client Secret نیاز دارید.

برای پیدا کردن شناسه کلاینت و رمز کلاینت پروژه خود، موارد زیر را انجام دهید:

1. یک اعتبارنامه OAuth 2.0 موجود را انتخاب کنید یا صفحه اعتبارنامه‌ها را باز کنید.
2. اگر قبلاً این کار را نکرده‌اید، با کلیک روی Create credentials > OAuth client ID و ارائه اطلاعات مورد نیاز برای ایجاد اعتبارنامه‌ها، اعتبارنامه‌های OAuth 2.0 پروژه خود را ایجاد کنید.
3. در بخش شناسه‌های کلاینت OAuth 2.0، شناسه کلاینت را جستجو کنید. برای جزئیات، روی شناسه کلاینت کلیک کنید.

اتصال به سرور CalDAV گوگل

برای استفاده از رابط CalDAV، یک برنامه کلاینت ابتدا در یکی از دو نقطه شروع به سرور تقویم متصل می‌شود. در هر صورت، اتصال باید از طریق HTTPS برقرار شود و باید از طرح احراز هویت OAuth 2.0 استفاده کند. سرور CalDAV از احراز هویت درخواست خودداری می‌کند مگر اینکه از طریق HTTPS با احراز هویت OAuth 2.0 یک حساب گوگل دریافت شود. تلاش برای اتصال از طریق HTTP یا استفاده از احراز هویت پایه منجر به کد وضعیت HTTP 401 Unauthorized می‌شود.

اگر برنامه‌ی کلاینت (مانند برنامه‌ی تقویم اپل) به یک مجموعه‌ی اصلی به عنوان نقطه‌ی شروع نیاز داشته باشد، URI مورد نیاز برای اتصال عبارت است از:

https://apidata.googleusercontent.com/caldav/v2/calid/user

که در آن باید به جای calid از "شناسه تقویم" تقویم مورد نظر استفاده شود. این را می‌توان از طریق رابط وب تقویم گوگل به صورت زیر پیدا کرد: در منوی کشویی کنار نام تقویم، تنظیمات تقویم را انتخاب کنید. در صفحه نتیجه، شناسه تقویم در بخشی با عنوان آدرس تقویم نشان داده می‌شود. شناسه تقویم برای تقویم اصلی کاربر همان آدرس ایمیل آن کاربر است.

اگر یک برنامه‌ی کلاینت (مانند Mozilla Sunbird ) به مجموعه‌ای از تقویم‌ها به عنوان نقطه‌ی شروع نیاز داشته باشد، URI مورد نیاز برای اتصال عبارت است از:

https://apidata.googleusercontent.com/caldav/v2/calid/events

نقطه پایانی قدیمی https://www.google.com/calendar/dav منسوخ شده و دیگر پشتیبانی نمی‌شود؛ استفاده از آن با مسئولیت خودتان است. توصیه می‌کنیم به قالب نقطه پایانی جدید که در بالا توضیح داده شد، تغییر دهید.

iCal® علامت تجاری شرکت اپل است.