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

از اول ماه مه ۲۰۲۶ ، محدودیت‌های استفاده برای این API به‌روزرسانی شد. پروژه‌های Google Cloud که بین نوامبر ۲۰۲۵ و آوریل ۲۰۲۶ از این API استفاده کرده‌اند، با سهمیه‌های استفاده تعیین‌شده قبلی خود ادامه خواهند داد. پروژه‌های ابری که در تاریخ ۱ مه ۲۰۲۶ یا بعد از آن ایجاد شده‌اند، مشمول سهمیه‌های جدید API هستند.

برای اطلاعات بیشتر، از جمله جدول زمانی، به مدل استاندارد Google Workspace برای ابزارهای عامل و APIها مراجعه کنید.

برای مشاهده‌ی اطلاعیه‌ی کامل، به ابزارهای عامل و به‌روزرسانی‌های امنیتی برای توسعه‌دهندگان Google Workspace مراجعه کنید.

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

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

API مربوط به CalDAV همان محدودیت‌های سهمیه‌بندی مربوط به API مربوط به تقویم را دارد. برای اطلاعات بیشتر، به محدودیت‌های استفاده مراجعه کنید.

مشخصات

برای هر یک از مشخصات مربوطه، پشتیبانی 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

  • از یک «صندوق ورودی» ساده پشتیبانی می‌کند که همیشه خالی است.
  • دعوت‌نامه‌هایی که دریافت می‌کنید به جای اینکه در «صندوق ورودی» شما قرار بگیرند، به طور خودکار به مجموعه «رویدادها»ی شما ارسال می‌شوند.
  • از جستجوی free-busy پشتیبانی نمی‌کند.

• caldav-ctag-02: برچسب موجودیت مجموعه تقویم (CTag) در CalDAV

  • ctag تقویم مانند etag منبع است؛ وقتی هر چیزی در تقویم تغییر کند، تغییر می‌کند. این به برنامه‌ی کلاینت اجازه می‌دهد تا به سرعت تشخیص دهد که نیازی به همگام‌سازی هیچ رویداد تغییر یافته‌ای ندارد.

• calendar-proxy: عملکرد پروکسی کاربر تقویم در CalDAV

  • برای بهبود عملکرد همگام‌سازی تقویم، درخواست‌هایی که شامل ویژگی‌های calendar-proxy-read-for یا calendar-proxy-write-for هستند، با یک UserAgent iOS با شکست مواجه می‌شوند زیرا دستگاه‌های iOS از واگذاری اختیار پشتیبانی نمی‌کنند.

اگرچه پیاده‌سازی CalDAV ما همه مشخصات را پوشش نمی‌دهد، اما برای بسیاری از کلاینت‌ها، از جمله Apple Calendar، به درستی کار می‌کند.

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

شناسه مشتری خود را ایجاد کنید

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

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

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

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

برای فعال کردن 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 یک حساب Google دریافت شود. تلاش برای اتصال از طریق HTTP یا استفاده از احراز هویت پایه منجر به کد وضعیت HTTP 401 Unauthorized می‌شود.

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

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

به جای CALENDAR_ID ، شناسه تقویمی که قرار است به آن دسترسی داشته باشید را وارد کنید.

برای یافتن شناسه تقویم از طریق رابط وب، **تنظیمات تقویم** را در منوی کشویی کنار نام تقویم انتخاب کنید. شناسه تقویم در بخشی با عنوان آدرس تقویم نشان داده می‌شود. شناسه تقویم برای تقویم اصلی کاربر همان آدرس ایمیل آن کاربر است.

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

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

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