Hướng dẫn dành cho nhà phát triển API CalDAV

CalDAV là một tiện ích của WebDAV, cung cấp một tiêu chuẩn cho ứng dụng truy cập vào thông tin trên lịch trên một máy chủ từ xa.

Google cung cấp giao diện CalDAV mà bạn có thể dùng để xem và quản lý lịch bằng giao thức CalDAV.

Thông số kỹ thuật

Đối với từng thông số kỹ thuật có liên quan, dịch vụ hỗ trợ của CalDAV của Google như sau:

  • rfc4918: Tiện ích HTTP dành cho tác giả và phiên bản phân tán trên web (WebDAV)
    • Hỗ trợ các phương thức HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFINDPROPPATCH.
    • Không hỗ trợ các phương thức HTTP LOCK, UNLOCK, COPY, MOVE hoặc MKCOL hoặc tiêu đề If* (ngoại trừ If-Match).
    • Không hỗ trợ các thuộc tính WebDAV (do người dùng xác định) tuỳ ý.
    • Không hỗ trợ Kiểm soát quyền truy cập WebDAV (rfc3744).
  • rfc4791: Tiện ích lên lịch cho WebDAV (CalDAV)
    • Hỗ trợ phương thức HTTP REPORT. Tất cả báo cáo ngoại trừ truy vấn rảnh-bận được triển khai.
    • Không hỗ trợ phương thức HTTP MKCALENDAR.
    • Không hỗ trợ hành động AUDIO.
  • rfc5545: iCalendar
    • Dữ liệu hiển thị trong giao diện CalDAV được định dạng theo thông số kỹ thuật của Lịch.
    • Hiện không hỗ trợ dữ liệu VTODO hoặc VJOURNAL.
    • Không hỗ trợ tiện ích Apple iCal® để cho phép các thuộc tính URL do người dùng đặt.
  • rfc6578: Đồng bộ hoá bộ sưu tập cho WebDAV
    • Các ứng dụng khách phải chuyển sang chế độ hoạt động này sau lần đồng bộ hoá ban đầu.
  • rfc6638: Lên lịch hiển thị phần mở rộng cho CalDAV
    • Hỗ trợ một "hộp thư đến" tầm thường. Nội dung này luôn trống.
    • Lời mời bạn nhận được sẽ tự động được gửi vào bộ sưu tập "sự kiện" của bạn thay vì được đưa vào "hộp thư đến".
    • Không hỗ trợ tra cứu rảnh-bận.
  • caldav-ctag-02: Thẻ thực thể thu thập lịch (CTag) trong CalDAV
    • Lịch ctag giống như một tài nguyên etag; lịch này thay đổi khi bất kỳ mục nào trong lịch thay đổi. Điều này cho phép ứng dụng khách nhanh chóng xác định rằng ứng dụng không cần đồng bộ hoá bất kỳ sự kiện nào đã thay đổi.
  • calendar-Proxy: Chức năng Proxy Người dùng Lịch trong CalDAV
    • Để cải thiện hiệu suất của quá trình đồng bộ hoá lịch trên các thiết bị iOS không hỗ trợ tính năng uỷ quyền, việc sử dụng các thuộc tính calendar-proxy-read-for hoặc calendar-proxy-write-for với Tác nhân người dùng iOS sẽ không thành công.

Chúng tôi chưa cung cấp triển khai đầy đủ tất cả thông số kỹ thuật có liên quan. Tuy nhiên, đối với nhiều ứng dụng như Apple iCal, giao thức CalDAV sẽ hoạt động đúng cách.

Lưu ý: Để bảo mật tài khoản và ngăn chặn hành vi sai trái, Google có thể đặt cookie trên các ứng dụng khách truy cập dữ liệu thông qua CalDAV.

Tạo mã ứng dụng khách

Để sử dụng API CalDAV, bạn cần có một Tài khoản Google. Nếu đã có tài khoản để sử dụng thì bạn đã hoàn tất.

Trước khi có thể gửi yêu cầu đến API CalDAV, bạn phải đăng ký ứng dụng với Google API Console bằng cách tạo một dự án.

Chuyển đến Google API Console. Nhấp vào mục Tạo dự án, nhập tên rồi nhấp vào Tạo.

Bước tiếp theo là kích hoạt API CalDAV.

Để bật API cho dự án, hãy làm như sau:

  1. Mở Thư viện API trong Google API Console. Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới. Thư viện API liệt kê tất cả những API có sẵn, được nhóm theo nhóm sản phẩm và mức độ phổ biến.
  2. Nếu API bạn muốn chọn không hiển thị trong danh sách, hãy sử dụng chức năng tìm kiếm để tìm API đó.
  3. Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
  4. Nếu bạn nhận được một lời nhắc, hãy bật tính năng thanh toán.
  5. Nếu bạn nhận được một lời nhắc, vui lòng chấp nhận Điều khoản dịch vụ của API.
Để thực hiện các yêu cầu API CalDAV, bạn cần có Mã ứng dụngMã bí mật của ứng dụng.

Để tìm mã ứng dụng khách và mật khẩu ứng dụng khách của dự án, hãy làm như sau:

  1. Chọn thông tin xác thực OAuth 2.0 hiện có hoặc mở trang Thông tin xác thực.
  2. Nếu bạn chưa thực hiện việc này, hãy tạo thông tin xác thực OAuth 2.0 của dự án bằng cách nhấp vào Tạo thông tin xác thực > Mã ứng dụng khách OAuth, rồi cung cấp thông tin cần thiết để tạo thông tin xác thực.
  3. Tìm Mã ứng dụng khách trong phần Mã ứng dụng OAuth 2.0. Để biết chi tiết, hãy nhấp vào mã ứng dụng khách.

Kết nối với máy chủ CalDAV của Google

Để sử dụng giao diện CalDAV, trước tiên, một chương trình máy khách sẽ kết nối với máy chủ lịch tại một trong hai điểm bắt đầu. Trong cả hai trường hợp, kết nối phải được thực hiện qua HTTPS và phải sử dụng lược đồ xác thực OAuth 2.0. Máy chủ CalDAV sẽ từ chối yêu cầu xác thực trừ khi nhận được yêu cầu qua HTTPS bằng phương thức xác thực OAuth 2.0 của Tài khoản Google. Việc cố gắng kết nối qua HTTP hoặc sử dụng kết quả Xác thực cơ bản trong mã trạng thái HTTP 401 Unauthorized.

Nếu chương trình khách (chẳng hạn như Apple iCal) yêu cầu tập hợp chính làm điểm xuất phát, thì URI để kết nối là:

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

Trong đó bạn nên thay thế calid bằng "mã lịch" của lịch cần truy cập. Bạn có thể tìm thấy thông tin này thông qua giao diện web của Lịch Google như sau: trong trình đơn kéo xuống bên cạnh tên lịch, hãy chọn Cài đặt lịch. Trên trang kết quả, mã lịch được hiển thị trong một phần có gắn nhãn Địa chỉ lịch. Mã lịch cho lịch chính của người dùng giống với địa chỉ email của người dùng đó.

Nếu một chương trình máy khách (chẳng hạn như Kotlin Sunbird) yêu cầu thu thập lịch làm điểm xuất phát, thì URI để kết nối là:

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

Điểm cuối cũ https://www.google.com/calendar/dav không còn được dùng nữa và không còn được hỗ trợ; hãy tự chịu rủi ro khi sử dụng điểm cuối này. Bạn nên chuyển sang định dạng điểm cuối mới theo mô tả ở trên.

iCal là một nhãn hiệu của Apple Inc.