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

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

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

規格

針對每項相關規格，Google 的 CalDAV 支援如下：

• rfc4918：適用於網路分散式編寫和版本管理 (WebDAV) 的 HTTP 擴充功能
  • 支援 HTTP 方法 GET、PUT、HEAD、DELETE、POST、OPTIONS、PROPFIND 和 PROPPATCH。
  • 不支援 HTTP 方法 LOCK、UNLOCK、COPY、MOVE 或 MKCOL，或是 If* 標頭 (If-Match 除外)。
  • 不支援任意 (使用者定義) WebDAV 屬性。
  • 不支援 WebDAV 存取控制 (rfc3744)。
• rfc4791： Calendaring Extensions (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 裝置提升日曆同步處理效能，使用 calendar-proxy-read-for 或 calendar-proxy-write-for 屬性搭配 iOS UserAgent 會失敗。

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

注意：為維護帳戶安全並防範濫用行為，Google 可能會在透過 CalDAV 存取資料的用戶端應用程式中設定 Cookie。

建立用戶端 ID

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

將要求傳送至 CalDAV API 之前，您必須先建立專案，透過 Google API 控制台註冊用戶端。

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

下一步是啟用 CalDAV API。

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

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

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

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

1. 選取現有的 OAuth 2.0 憑證或開啟「憑證」頁面。
2. 如果您尚未建立專案的 OAuth 2.0 憑證，請按一下「Create credentials」(建立憑證) >「OAuth client ID」(OAuth 用戶端 ID)，然後提供建立憑證所需的資訊。
3. 在「OAuth 2.0 用戶端 ID」部分中找出「用戶端 ID」。詳情請按一下用戶端 ID。

連線至 Google 的 CalDAV 伺服器

為了使用 CalDAV 介面，用戶端程式會在兩個起點的其中之一，初次連線至日曆伺服器。無論是哪種情況，都必須透過 HTTPS 連線，且必須使用 OAuth 2.0 驗證配置。CalDAV 伺服器會拒絕驗證要求，除非是透過含有 Google 帳戶 OAuth 2.0 驗證的 HTTPS 傳送要求。如果嘗試透過 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. 的商標。