راهنمای توسعه‌دهندگان CalDAV API

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

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

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

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

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

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

مشخصات

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

• rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

  • از روش‌های HTTP GET، PUT، HEAD، DELETE، POST، OPTIONS، PROPFIND، و PROPPATCH پشتیبانی می‌کند.
  • از روش‌های اچ‌تی‌تی‌پی 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 برای اجازه دادن به ویژگی‌های نشانی وب قابل تنظیم توسط کاربر پشتیبانی نمی‌کند.

• rfc6578: همگام‌سازی مجموعه برای WebDAV

  • برنامه‌های کارخواه باید پس‌از همگام‌سازی اولیه به این حالت عملیاتی تغییر کنند.

• rfc6638: افزودن زمان‌بندی به CalDAV

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

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

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

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

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

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

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

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

برای استفاده از CalDAV API باید حساب Google داشته باشید.

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

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

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

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

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

برای انجام درخواست‌های CalDAV API به شناسه کارخواه و رمز کارخواه نیاز دارید.

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

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

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

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

اگر برنامه کارخواه (مثل برنامه «تقویم» Apple) به مجموعه اصلی به‌عنوان نقطه شروع نیاز دارد، نشانی وب برای اتصال به این صورت است:

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 منسوخ شده است و دیگر پشتیبانی نمی‌شود؛ با مسئولیت خودتان از آن استفاده کنید. توصیه می‌کنیم به قالب نقطه پایانی جدید انتقال دهید.