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 một tiêu chuẩn để ứng dụ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 từng thông số kỹ thuật có liên quan, Google hỗ trợ CalDAV như sau:

  • rfc4918: Tiện ích HTTP cho tính năng tạo và tạo 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, 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ợ Kiểm soát quyền truy cập WebDAV (rfc3744).
  • rfc4791: Tiện ích 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 lịch biểu trống-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: iCalendar
    • Dữ liệu hiển thị trong giao diện CalDAV được định dạng theo quy cách iCalendar.
    • 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 người dùng đặt thuộc tính URL.
  • 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á đầu tiên.
  • rfc6638: Tiện ích lên lịch cho CalDAV
    • Hỗ trợ "hộp thư đến" không quan trọng, luôn trố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" thay vì được đưa vào "hộp thư đến".
    • Không hỗ trợ tính năng tra cứu lịch trống.
  • caldav-ctag-02: Thẻ thực thể tập hợp lịch (CTag) trong CalDAV
    • ctag lịch giống như một tài nguyên etag; nó thay đổi khi bất kỳ nội dung 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 của người dùng Lịch trong CalDAV
    • Để cải thiện hiệu suất đồng bộ hoá lịch từ 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 các thuộc tính calendar-proxy-read-for hoặc calendar-proxy-write-for với UserAgent iOS.

Chúng tôi chưa cung cấp đầy đủ cách triển khai tất cả các thông số kỹ thuật liên quan. Tuy nhiên, đối với nhiều ứng dụng 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 dữ liệu thông qua CalDAV.

Tạo mã ứng dụng

Để sử dụng API CalDAV, bạn cần có Tài khoản Google. Nếu đã có tài khoản mà bạn có thể 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 của mình với Bảng điều khiển API của Google 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 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 sẽ cần có Mã ứng dụng và Mật khẩu ứng dụng.

Để tìm mã ứng dụng khách và khoá bí mật của ứng dụng khách, 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 khách OAuth 2.0. Để biết thông tin chi tiết, hãy nhấp vào mã ứng dụng.

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

Để sử dụng giao diện CalDAV, ban đầu, chương trình ứng dụng sẽ kết nối với máy chủ lịch ở 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 yêu cầu trừ phi yêu cầu đó đến qua HTTPS bằng 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 phương thức 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 bộ sưu tậ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 đó, calid sẽ đượ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 chế độ cài đặt này thông qua giao diện web của Lịch Google như sau: trong trình đơn thả 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ã nhận dạng lịch sẽ xuất hiện trong phần có nhãn Địa chỉ lịch. Mã nhận dạng 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 một bộ sưu tậ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 và không được hỗ trợ nữa; bạn có thể sử dụng điểm cuối này theo rủi ro của riêng mình. Bạn nên chuyển sang định dạng điểm cuối mới như mô tả ở trên.

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