CalDAV API 開發人員指南#

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

規範

針對這些相關規格,Google 的 CalDAV 支援如下:

  • rfc4918:網路分散式編寫和版本的 HTTP 擴充功能 (WebDAV)
    • 支援 HTTP 方法 GETPUTHEADDELETEPOSTOPTIONSPROPFINDPROPPATCH
    • 不支援 HTTP 方法 LOCKUNLOCKCOPYMOVEMKCOL,或 If* 標頭 (If-Match 除外)。
    • 不支援任意 (使用者定義的) WebDAV 屬性。
    • 不支援 WebDAV Access Control (rfc3744)。
  • rfc4791:日曆擴充功能到 WebDAV (CalDAV)
    • 支援 HTTP 方法 REPORT。實作除了有空/忙碌查詢以外的所有報表。
    • 不支援 HTTP 方法 MKCALENDAR
    • 不支援 AUDIO 動作。
  • rfc5545: iCalendar
    • CalDAV 介面中公開的資料會根據 iCalendar 規格格式化。
    • 目前不支援VTODOVJOURNAL資料。
    • 不支援 Apple iCal® 擴充功能,讓使用者可以設定網址屬性。
  • rfc6578:WebDAV 的集合同步處理
    • 在初次同步處理後,用戶端應用程式必須切換至這個操作模式。
  • rfc6638:將擴充功能安排至 CalDAV
    • 支援一般的「收件匣」,其內容永遠空白。
    • 您收到的邀請會自動傳送給您的「活動」集合,而不是放入「收件匣」中。
    • 不支援有空/忙碌狀態查詢作業。
  • caldav-ctag-02:CalDAV 的日曆集合實體標記 (CTag)
    • 日曆 ctag 類似 etag 資源,當日曆中的任何活動發生變更時,都會隨之改變。這樣一來,用戶端應用程式就能快速判斷它不需要同步處理任何已變更的事件。
  • calendar-proxy: CalDAV 中的日曆使用者 Proxy 功能
    • 針對不支援委派功能的 iOS 裝置,為提升日曆同步處理作業的效能,將 calendar-proxy-read-forcalendar-proxy-write-for 屬性與 iOS UserAgent 搭配使用時將失敗。

我們尚未提供所有相關規格的完整實作。不過,對許多用戶端 (例如 Apple iCal) 來說,CalDAV 通訊協定應該能夠正確互通。

注意:為維護帳戶安全並防止濫用情形,Google 可能會在透過 CalDAV 存取資料的用戶端應用程式設定 Cookie。

建立用戶端 ID

如要使用 CalDAV API,您必須擁有 Google 帳戶。如果您已經有可用的帳戶,就大功告成了。

您必須先向專案使用 Google API 控制台註冊用戶端,才能傳送要求至 CalDAV API。

前往 Google API 控制台。按一下 [Create project] (建立專案) 並輸入名稱,然後按一下 [Create] (建立)

下一步是啟用 CalDAV API

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

  1. 在 Google API 控制台中開啟 API 程式庫。如果出現系統提示,請選取專案或建立新專案。API 程式庫會列出所有可用的 API,並按產品系列和熱門程度分組。
  2. 如果清單裡找不到您想啟用的 API,請用搜尋功能尋找。
  3. 選取您要啟用的 API,然後按一下 [啟用] 按鈕。
  4. 如果系統顯示提示,請啟用帳單。
  5. 看到系統提示時,請接受 API 的《服務條款》。
若要執行 CalDAV API 要求,您需要 Client IDClient Secret

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

  1. 選取現有的 OAuth 2.0 憑證或開啟憑證頁面
  2. 如果您尚未建立專案的 OAuth 2.0 憑證,請按一下 [建立憑證] > [OAuth 用戶端 ID],然後提供建立憑證所需的資訊。
  3. 在「OAuth 2.0 用戶端 ID」部分找出「Client ID」(用戶端 ID)。按一下用戶端 ID 即可查看詳細資訊。

連線至 Google 的 CalDAV 伺服器

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

如果用戶端程式 (例如 Apple iCal) 需要主要集合當做起點,要連線的 URI 如下:

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

其中 calid 應替換為待存取日曆的「日曆 ID」。您可以使用 Google 日曆網頁介面尋找日曆,方法如下:在日曆名稱旁邊的下拉式選單中,選取 [Calendar Settings]。在結果頁面上,日曆 ID 會顯示在標示「日曆位址」的區段中。使用者的主要日曆的日曆 ID 與使用者的電子郵件地址相同。

如果用戶端程式 (例如 Mozilla Sunbird) 需要將日曆集合當做起點,那麼要連結的 URI 如下:

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

舊的端點 https://www.google.com/calendar/dav 已遭淘汰,不再支援。您必須自行承擔使用風險。建議您轉換至上述的新端點格式。

iCal 是 Apple Inc. 的註冊商標。