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

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

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

CalDAV API 的配額限制與 Calendar API 相同。詳情請參閱「用量限制」。

規格

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。所有報表 (free-busy-query 除外) 都已導入。
  • 不支援 HTTP 方法 MKCALENDAR。
  • 不支援 AUDIO 動作。

• rfc5545：iCalendar

  • CalDAV 介面中顯示的資料格式符合 iCalendar 規格。
  • 不支援 VTODO 或 VJOURNAL 資料。
  • 不支援 Apple iCal 擴充功能，因此使用者無法設定網址屬性。

• rfc6578：WebDAV 的集合同步處理

  • 初始同步完成後，用戶端應用程式必須切換至這個作業模式。

• rfc6638：CalDAV 的排程擴充功能

  • 支援一律為空的微不足道「收件匣」。
  • 您收到的邀請會自動送達「活動」集合，而不是「收件匣」。
  • 不支援 free-busy 查閱。

• caldav-ctag-02：CalDAV 中的日曆集合實體標記 (CTag)

  • 日曆 ctag 就像資源 etag，日曆中的任何內容變更時，日曆也會隨之變更。這樣一來，用戶端應用程式就能快速判斷是否需要同步處理任何變更的事件。

• calendar-proxy：CalDAV 中的日曆使用者 Proxy 功能

  • 為提升日曆同步效能，如果要求包含 calendar-proxy-read-for 或 calendar-proxy-write-for 屬性，就會因 iOS 裝置不支援委派功能而失敗 (使用 iOS UserAgent 時)。

雖然我們的 CalDAV 實作項目並未涵蓋所有規格，但適用於許多用戶端，包括 Apple Calendar。

建立用戶端 ID

如要使用 CalDAV API，您必須擁有 Google 帳戶。

您必須先透過 Google Cloud 控制台建立專案，向 CalDAV API 註冊用戶端，才能對 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 憑證，請依序點選「建立憑證」>「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/CALENDAR_ID/user

將 CALENDAR_ID 替換為要存取的日曆 ID。

如要透過網頁介面找出日曆 ID，請在日曆名稱旁邊的下拉式選單中選取「日曆設定」。日曆 ID 會顯示在標示為「日曆地址」的部分。使用者主要日曆的日曆 ID 與該使用者的電子郵件地址相同。

如果用戶端程式 (例如 Mozilla Thunderbird) 需要以日曆集合做為起點，請使用下列 URI：

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