CalDAV API 開發人員指南's 指南

CalDAV 是 WebDAV 的擴充功能，可提供標準，讓用戶端存取遠端伺服器上的日曆資訊。

Google 提供 CalDAV 介面，您可以使用 CalDAV 通訊協定查看及管理日曆。

規格

Google 的 CalDAV 支援服務適用於下列相關規格：

• rfc4918：HTTP Extensions for Web Distributed Authoring and Versioning (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。除了忙碌時間查詢，所有報表都已實作。
  • 不支援 HTTP 方法 MKCALENDAR。
  • 不支援 AUDIO 動作。
• rfc5545：iCalendar
  • CalDAV 介面中顯示的資料會根據 iCalendar 規格格式化。
  • 目前不支援 VTODO 或 VJOURNAL 資料。
  • 不支援 Apple iCal® 擴充功能，因此使用者無法設定網址屬性。
• rfc6578：WebDAV 的集合同步處理
  • 初始同步完成後，用戶端應用程式必須切換至這個作業模式。
• rfc6638：CalDAV 的排程擴充功能
  • 支援一律為空的微不足道「收件匣」。
  • 您收到的邀請會自動傳送到「活動」集合，而不是「收件匣」。
  • 不支援查詢空閒/忙碌狀態。
• caldav-ctag-02：CalDAV 中的日曆集合實體標記 (CTag)
  • 日曆 ctag 類似於資源 etag，只要日曆中的任何內容有變更，就會隨之變更。這樣一來，用戶端應用程式就能快速判斷是否需要同步處理任何變更的事件。
• calendar-proxy：CalDAV 中的日曆使用者 Proxy 功能
  • 為提升 iOS 裝置的日曆同步效能 (iOS 裝置不支援委派)，使用 calendar-proxy-read-for 或 calendar-proxy-write-for 屬性搭配 iOS UserAgent 會失敗。

我們尚未完整實作所有相關規格。不過，對於許多用戶端 (例如 Apple 的「日曆」應用程式)，CalDAV 協定應可正確互通。

注意：為確保帳戶安全及防止濫用，Google 可能會在透過 CalDAV 存取資料的用戶端應用程式上設定 Cookie。

建立用戶端 ID

如要使用 CalDAV API，您必須擁有 Google 帳戶。如果已有帳戶，就可以開始使用了。

您必須先透過 Google API 控制台建立專案，向該控制台註冊用戶端，才能對 CalDAV API 發出要求。

前往 Google API 控制台。按一下「建立專案」， 輸入名稱，然後按一下「建立」。

如果想為專案啟用 API，請按照以下步驟操作：

1. 在 Google API 控制台中開啟 API 程式庫。按照系統說明選取專案，或建立新專案。API 程式庫會列出所有可用的 API，並按照產品系列及熱門程度分組。
2. 如果清單裡找不到您想啟用的 API，請使用搜尋功能。
3. 選取要啟用的 API，然後按一下「Enable」按鈕。
4. 如果系統顯示提示，請啟用帳單功能。
5. 如果系統顯示提示，請接受 API 的服務條款。

如要找出專案的用戶端 ID 和用戶端密鑰，請按照下列步驟操作：

1. 選取現有的 OAuth 2.0 憑證，或開啟「憑證」頁面。
2. 如果尚未建立專案的 OAuth 2.0 憑證，請依序點選「建立憑證」>「OAuth 用戶端 ID」，並提供建立憑證所需的資訊。
3. 在「OAuth 2.0 用戶端 ID」部分中，找出「用戶端 ID」。 如要瞭解詳情，請按一下用戶端 ID。

連線至 Google 的 CalDAV 伺服器

如要使用 CalDAV 介面，用戶端程式一開始會從兩個起點之一連線至日曆伺服器。無論是哪種情況，連線都必須透過 HTTPS 建立，且必須使用 OAuth 2.0 驗證機制。除非要求是透過 HTTPS 傳送，並使用 Google 帳戶的 OAuth 2.0 驗證，否則 CalDAV 伺服器會拒絕驗證要求。嘗試透過 HTTP 連線或使用基本驗證，會導致 HTTP 401 Unauthorized 狀態碼。

如果用戶端程式 (例如 Apple 的「日曆」應用程式) 需要主體集合做為起點，則要連線的 URI 為：

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

請將 calid 換成要存取的日曆「日曆 ID」。如要尋找這項資訊，請透過 Google 日曆網頁介面，在日曆名稱旁的下拉式選單中選取「日曆設定」。在隨即顯示的頁面中，日曆 ID 會顯示在標示為「日曆地址」的部分。使用者主要日曆的日曆 ID 與該使用者的電子郵件地址相同。

如果用戶端程式 (例如 Mozilla Sunbird) 需要以日曆集合做為起點，則連線 URI 為：

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

舊端點 https://www.google.com/calendar/dav 已淘汰，且不再受支援，請自行承擔使用風險。建議您改用上述新端點格式。

iCal® 是 Apple Inc. 的商標。