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.

API CalDAV có cùng hạn mức như Calendar API. Để biết thêm thông tin, hãy xem bài viết Giới hạn sử dụng.

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, 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ả 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ợ 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.
    • 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 mà người dùng có thể đặ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ợ tra cứu free-busy.

  • 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 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, các yêu cầu bao gồm thuộc tính calendar-proxy-read-for hoặc calendar-proxy-write-for sẽ không thành công với UserAgent iOS vì các thiết bị iOS không hỗ trợ uỷ quyền.

Mặc dù chế độ triển khai CalDAV của chúng tôi không bao gồm mọi quy cách, nhưng chế độ này hoạt động chính xác cho nhiều ứng dụng, bao gồm cả Lịch Apple.

Tạo mã ứng dụng

Để sử dụng API CalDAV, bạn cần có một Tài khoản Google.

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 bảng điều khiển Google Cloud 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.

Tiếp theo, bạn cần 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 cần có Client ID và Client Secret.

Để 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 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. 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 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 từ chối xác thực một 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/CALENDAR_ID/user

Thay CALENDAR_ID bằng mã nhận dạng của lịch cần truy cập.

Để tìm mã lịch thông qua giao diện web, hãy chọn **Cài đặt lịch** trong trình đơn thả xuống bên cạnh tên lịch. Mã lịch 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 Thunderbird) yêu cầu một bộ sưu tập lịch làm điểm xuất phát, hãy sử dụng URI sau:

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