Quản lý danh bạ bằng giao thức CardDAV

Bạn có thể xem và quản lý danh bạ của mình bằng giao thức CardDAV của Google.

Danh bạ được lưu trữ trong Tài khoản Google của người dùng; hầu hết dịch vụ của Google đều có quyền truy cập vào danh bạ. Ứng dụng khách của bạn có thể sử dụng API CardDAV để tạo liên hệ mới, chỉnh sửa hoặc xoá liên hệ hiện tại và truy vấn các liên hệ phù hợp với các tiêu chí cụ thể.

Thông số kỹ thuật

Thông số kỹ thuật đầy đủ không được triển khai, nhưng nhiều ứng dụng như Danh bạ Apple iOSTM và macOS sẽ tương tác một cách chính xác.

Đối với từng thông số kỹ thuật có liên quan, dịch vụ hỗ trợ CardDAV của Google như sau:

CardDAV của Google yêu cầu OAuth 2.0

Giao diện CardDAV của Google yêu cầu phải có OAuth 2.0. Hãy tham khảo tài liệu được liên kết dưới đây để biết thông tin về cách sử dụng OAuth 2.0 để truy cập API của Google:

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

Giao thức CardDAV cho phép khám phá sổ địa chỉ và URI tài nguyên liên hệ. Bạn không được mã hoá cứng bất kỳ URI nào vì các URI này có thể thay đổi bất cứ lúc nào.

Các ứng dụng phải sử dụng HTTPS và tính năng xác thực OAuth 2.0 phải được cung cấp cho Tài khoản Google của người dùng. Máy chủ CardDAV sẽ không xác thực yêu cầu trừ khi 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 và ứng dụng của bạn được đăng ký trên DevConsole. Mọi nỗ lực kết nối qua HTTP bằng phương thức Xác thực cơ bản hoặc với một email/mật khẩu không khớp với Tài khoản Google sẽ dẫn đến một mã phản hồi HTTP 401 Unauthorized.

Để sử dụng CardDAV, trước tiên, chương trình ứng dụng của bạn phải kết nối với đường dẫn khám phá chuẩn bằng cách thực hiện HTTP PROPFIND trên:

https://www.googleapis.com/.well-known/carddav

Sau khi chuyển hướng (HTTP 301) đến một Tài nguyên Sổ địa chỉ, chương trình ứng dụng khách của bạn có thể thực hiện PROPFIND trên đó để khám phá các thuộc tính DAV:current-user-principal, DAV:principal-URL và addressbook-home-set. Sau đó, chương trình ứng dụng có thể khám phá sổ địa chỉ chính bằng cách thực hiện PROPFIND trên addressbook-home-set, đồng thời tìm kiếm các tài nguyên addressbook và collection. Nội dung mô tả đầy đủ về quy trình này nằm ngoài phạm vi của tài liệu này. Hãy truy cập vào rfc6352 để biết thêm thông tin chi tiết.

Đường dẫn chuyển hướng được trả về trong phản hồi HTTP 301 thông qua một PROPFIND trên URI phổ biến phải không được lưu vào bộ nhớ đệm vĩnh viễn (theo rfc6764). Các thiết bị nên định kỳ thử lại các hoạt động khám phá URI đã biết để xác minh xem đường dẫn đã lưu vào bộ nhớ đệm có còn cập nhật hay không và đồng bộ hoá lại nếu đường dẫn đó thay đổi. Theo Google, bạn nên sử dụng giá từ 2 đến 4 tuần một lần.

Tài nguyên

CardDAV sử dụng các khái niệm REST. Ứng dụng khách hoạt động trên các tài nguyên do URI của chúng chỉ định. Cấu trúc URI hiện tại được chỉ định ở đây để giúp nhà phát triển hiểu các khái niệm trong phần sau. Cấu trúc có thể thay đổi và không được mã hoá cứng. Thay vào đó, các tài nguyên sẽ được tìm thấy theo RFC.

  1. Hiệu trưởng
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Bộ màn hình chính
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. Sổ địa chỉ
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. Liên hệ
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Đồng bộ hoá Danh bạ

Sau đây là nội dung mô tả chung về các thao tác được hỗ trợ. Nhà phát triển nên tìm thông tin chi tiết trong RFC có liên quan. Các yêu cầu và phản hồi chủ yếu được mã hoá trong XML. Dưới đây là các thao tác chính mà các ứng dụng khách sử dụng để đồng bộ hoá:

  • Sử dụng CTag
    • Các chương trình ứng dụng sử dụng yêu cầu getctag PROPFIND trên tài nguyên Sổ địa chỉ để xác định xem có bất kỳ người liên hệ nào đã thay đổi trên máy chủ hay không, do đó có cần đồng bộ hoá hay không. Giá trị của thuộc tính này đảm bảo sẽ thay đổi nếu có bất kỳ người liên hệ nào thay đổi. Các ứng dụng khách nên lưu trữ giá trị này và chỉ sử dụng giá trị này trong lần đồng bộ hoá ban đầu cũng như làm dự phòng khi sync-token không hợp lệ. Việc thăm dò định kỳ cho thuộc tính getctag sẽ dẫn đến tình trạng điều tiết.
  • Sử dụng mã thông báo đồng bộ hoá
    • Chương trình ứng dụng sử dụng yêu cầu sync-token PROPFIND trên Sổ địa chỉ để lấy sync-token biểu thị trạng thái hiện tại của ứng dụng. Ứng dụng khách phải lưu trữ giá trị này và đưa ra yêu cầu sync-collection REPORT định kỳ để xác định các thay đổi kể từ sync-token được đưa ra gần đây nhất. Mã thông báo được cấp có hiệu lực trong 29 ngày và phản hồi của REPORT sẽ chứa một sync-token mới.
  • Sử dụng ETag
    • Ứng dụng khách đưa ra một yêu cầu PROPFIND getetag đối với tài nguyên Sổ địa chỉ (có tiêu đề DEPTH bằng DEPTH_1). Bằng cách duy trì giá trị ETag của mỗi địa chỉ liên hệ, chương trình ứng dụng có thể yêu cầu giá trị của các liên hệ đã thay đổi ETag.
  • Truy xuất người liên hệ
    • Các ứng dụng khách truy xuất danh bạ bằng cách đưa ra yêu cầu addressbook-multiget REPORT. Khi có một danh sách URI liên hệ, báo cáo sẽ trả về tất cả các liên hệ được yêu cầu dưới dạng giá trị VCard 3.0. Mỗi mục nhập bao gồm một ETag cho địa chỉ liên hệ.
  • Chèn một người liên hệ
    • Ứng dụng khách đưa ra một yêu cầu POST với địa chỉ liên hệ mới ở định dạng VCard 3.0. Phản hồi sẽ chứa mã của người liên hệ mới.
  • Cập nhật một người liên hệ
    • Ứng dụng khách đưa ra một yêu cầu PUT với người liên hệ đã cập nhật ở định dạng VCard 3.0. Địa chỉ liên hệ được cập nhật nếu địa chỉ liên hệ đã tồn tại trong sổ địa chỉ.
    • Ứng dụng khách phải bao gồm tiêu đề If-Match có ETag hiện được biết của liên hệ. Sau đó, máy chủ sẽ từ chối yêu cầu PUT (với HTTP 412) nếu ETag hiện tại trên máy chủ khác với ETag do chương trình ứng dụng gửi. Việc này cho phép chuyển đổi tuần tự các bản cập nhật một cách lạc quan.
  • Xoá người liên hệ
    • Ứng dụng khách xoá một mục liên hệ bằng cách đưa ra yêu cầu DELETE đối với URI của mục liên hệ đó.