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

CalDAV là một tiện ích 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ột máy chủ từ xa.

Google cung cấp một 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, dịch vụ hỗ trợ CalDAV của Google như sau:

  • rfc4918: Tiện ích HTTP cho Web Distributed Authoring and Versioning (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 cho WebDAV (CalDAV)
    • Hỗ trợ phương thức HTTP REPORT. Tất cả các báo cáo ngoại trừ free-busy-query đều đượ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 được hiển thị trong giao diện CalDAV được định dạng theo thông số kỹ thuật 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 các thuộc tính URL do người dùng thiết lập.
  • rfc6578: Collection Synchronization for WebDAV
    • Các ứng dụng phải chuyển sang chế độ hoạt động này sau lần đồng bộ hoá ban đầu.
  • rfc6638: Scheduling Extensions to CalDAV
    • Hỗ trợ một "hộp thư đến" đơn giản, 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" thay vì được đặt vào "hộp thư đến".
    • Không hỗ trợ tính năng tra cứu thời gian rảnh/bận.
  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV
    • ctag lịch giống như etag tài nguyên; giá trị này sẽ thay đổi khi có bất kỳ nội dung nào trong lịch thay đổi. Điều này cho phép ứng dụng 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: Calendar User Proxy Functionality in 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, việc sử dụng các thuộc tính calendar-proxy-read-for hoặc calendar-proxy-write-for với UserAgent iOS sẽ không thành công.

Chúng tôi chưa triển khai đầy đủ tất cả các thông số kỹ thuật có 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 sẽ 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 lạm dụng, Google có thể đặt cookie trên các ứng dụng 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ó một Tài khoản Google. Nếu đã có tài khoản, bạn có thể sử dụng tài khoản đó.

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 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 một 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ụng và Khoá bí mật của ứng dụng.

Để tìm mã ứng dụng và khoá bí mật của ứng dụng cho 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 chưa thực hiện, hãy tạo thông tin xác thực OAuth 2.0 cho dự án bằng cách nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth và 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 trong phần Mã ứng dụng 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, chương trình ứng dụng ban đầu 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 phương thứ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 đó được gửi qua HTTPS với thông tin 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 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/valid/user

Trong đó, bạn cần thay thế valid bằng "mã lịch" của lịch cần truy cập. Bạn có thể tìm thấy mã này thông qua giao diện web 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ẽ xuất hiện 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 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/valid/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 điểm cuối này. 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.