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 tiêu chuẩn để các ứ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 từng quy cách có liên quan, dịch vụ hỗ trợ CalDAV của Google như sau:

  • rfc4918: HTTP Extensions for 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: Calendaring Extensions to WebDAV (CalDAV)
    • Hỗ trợ phương thức HTTP REPORT. Tất cả các báo cáo đều được triển khai, ngoại trừ báo cáo free-busy-query.
    • Không hỗ trợ phương thức HTTP MKCALENDAR.
    • Không hỗ trợ thao tác AUDIO.
  • rfc5545: iCalendar
    • Dữ liệu được 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 các thuộc tính URL do người dùng đặt.
  • 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" không quan trọng, luôn trống.
    • Lời mời bạn nhận được sẽ tự động được chuyển vào bộ sưu tập "sự kiện" thay vì được chuyển vào "hộp thư đến".
    • Không hỗ trợ tính năng tra cứu trạng thái rảnh/bận.
  • caldav-ctag-02: Thẻ thực thể bộ sưu tập lịch (CTag) trong CalDAV
    • Lịch ctag giống như một tài nguyên etag; lịch 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 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 uỷ quyền cho người dùng Lịch trong CalDAV
    • Để cải thiện hiệu suất đồng bộ hoá lịch trên các thiết bị iOS không hỗ trợ 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 quy cách 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 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 để sử dụng thì bạn có thể bỏ qua bước này.

Trước khi có thể gửi yêu cầu đến CalDAV API, bạn phải đăng ký ứng dụng của mình 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 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 CalDAV API, bạn sẽ cần Mã ứng dụng khách và Khoá bí mật của ứng dụng khách.

Để tìm mã ứng dụng khách và khoá bí mật của ứng dụng khách 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 việc này, 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 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, 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, bạn phải thiết lập kết nối 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 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 bắt đầu, thì URI để kết nối là:

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

Trong đó, 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 địa chỉ 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ã 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ộ lịch làm điểm bắt đầu, 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 đã ngừng hoạt động và không còn được hỗ trợ; bạn tự chịu trách nhiệm 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.