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 裝置 (不支援委派) 的 Google 日曆同步處理效能，使用 calendar-proxy-read-for 或 calendar-proxy-write-for 屬性搭配 iOS 使用者代理程式會失敗。

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

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

建立用戶端 ID

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

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

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

接下來，請啟用 CalDAV API。

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

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

如要執行 CalDAV API 要求，您需要用戶端 ID和用戶端密碼。

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

1. 選取現有的 OAuth 2.0 憑證或開啟「憑證」頁面。
2. 如果您尚未建立專案的 OAuth 2.0 憑證，請依序點選「Create credentials」>「OAuth client 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. 的商標。