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

CalDAV là một phần mở rộng của WebDAV cung cấp tiêu chuẩn để khách hàng truy cập vào thông tin lịch trên 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 mỗi thông số kỹ thuật có liên quan, hỗ trợ CalDAV của Google như sau:

  • rfc4918: Tiện ích HTTP dành cho việc tạo phiên bản và tác quyền được phân phối trên web (WebDAV)
    • Hỗ trợ các phương thức HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND và PROPPATCH.
    • 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 tuỳ ý (do người dùng xác định).
    • Không hỗ trợ tính năng Kiểm soát quyền truy cập WebDAV (rfc3744).
  • rfc4791: Tiện ích lập lịch biểu cho WebDAV (CalDAV)
    • Hỗ trợ phương thức HTTP REPORT. Tất cả các báo cáo, ngoại trừ truy vấn rảnh-bận, đều được triển khai.
    • Không hỗ trợ phương thức HTTP MKCALENDAR.
    • Không hỗ trợ thao tác AUDIO.
  • rfc5545: iLịch
    • Dữ liệu hiển thị trong giao diện CalDAV được định dạng theo thông số kỹ thuật iLị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 có thể đặt bởi người dùng.
  • 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ập lịch Tiện ích cho CalDAV
    • Hỗ trợ một "hộp thư đến" bình thường, luôn trống.
    • Những lời mời mà 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 đặt vào "hộp thư đến" của bạn.
    • Không hỗ trợ tra cứu rảnh-bận.
  • caldav-ctag-02: Thẻ thực thể tập hợ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 có 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 đã thay đổi nào.
  • 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 tính năng đồng bộ hoá lịch trên các thiết bị iOS không hỗ trợ tính năng uỷ quyền, bạn sẽ không thể sử dụng thuộc tính calendar-proxy-read-for hoặc calendar-proxy-write-for với một UserAgent iOS.

Chúng tôi chưa cung cấp phương thức 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, chẳng hạn như ứng dụng Lịch của Apple, giao thức CalDAV phải tương tác chính xác.

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 vào dữ liệu qua CalDAV.

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

Để sử dụng API CalDAV, bạn cần có 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 các yêu cầu tới API CalDAV, bạn phải đăng ký ứng dụng khách 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 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 được 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ả 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 Enable (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ó Client-ID và Client Secret.

Để 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 một 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. Tạo thông tin xác thực OAuth 2.0 cho dự án bằng cách nhấp vào Create credentials > OAuth client ID (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 đăng nhập.
  3. Tìm Mã ứng dụng trong mục Mã khách hàng OAuth 2.0. Để biết thông tin chi tiết, hãy nhấp vào mã ứng dụng khách đó.

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

Để sử dụng giao diện CalDAV, ban đầu, một chương trình ứng dụng 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 xác thực một yêu cầu trừ phi yêu cầu đó đến qua HTTPS với phương thức xác thực OAuth 2.0 của một Tài khoản Google. Việc cố gắng kết nối qua HTTP hoặc sử dụng tính năng Xác thực cơ bản sẽ dẫn đến mã trạng thái HTTP 401 Unauthorized.

Nếu chương trình ứng dụng (chẳng hạn như ứng dụng Lịch của Apple) yêu cầu một tập hợp chính làm điểm xuất phát, thì URI cần kết nối sẽ là:

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

Trường hợp calid phải được thay thế 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 sẽ hiển thị trong một phần có 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 ứng dụng (chẳng hạn như Mozilla Sunbird ) yêu cầu thu thập lịch làm điểm xuất phát, thì URI để kết nối sẽ là:

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

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

iCal® là nhãn hiệu của Apple Inc.