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

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

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

مشخصات

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

  • 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: iCalendar
    • داده هایی که در رابط 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 باید به درستی کار کند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

iCal® یک علامت تجاری Apple Inc است.