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 các 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 người liên hệ mới, chỉnh sửa hoặc xoá người liên hệ hiện có và truy vấn người liên hệ khớp với các tiêu chí cụ thể.

Thông số kỹ thuật

Không triển khai toàn bộ thông số kỹ thuật, nhưng nhiều ứng dụng như Danh bạ Apple iOS™ và macOS sẽ tương tác chính xác.

Đối với mỗi 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 OAuth 2.0. Tham khảo tài liệu bên dưới để biết thông tin về cách sử dụng OAuth 2.0 để truy cập Google API:

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.

Ứng dụng phải sử dụng HTTPS và phải xác thực OAuth 2.0 đượ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 một yêu cầu trừ khi yêu cầu đó đến qua HTTPS bằng OAuth 2.0 xác thực Tài khoản Google và đăng ký ứng dụng trên Bảng điều khiển dành cho nhà phát triển. 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 bằng email/mật khẩu không khớp với Tài khoản Google đều dẫn đến mã phản hồi HTTP 401 Unauthorized.

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

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

Sau khi được chuyển hướng (HTTP 301) đến một Tài nguyên sổ địa chỉ, chương trình ứng dụng của bạn có thể thực hiện PROPFIND trên tài nguyê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 khách hàng của bạn có thể khám phá sổ địa chỉ chính bằng cách biểu diễn PROPFIND trên addressbook-home-set và tìm Các tài nguyên addressbook và collection. Thông tin mô tả đầy đủ về quy trình này nằm ngoài phạm vi của tài liệu này. Xem 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 PROPFIND trên URI phổ biến không được lưu vào bộ nhớ đệm vĩnh viễn (theo mỗi rfc6764). Thiết bị nên định kỳ thử lại việc khám phá URI phổ biến để xác minh xem đường dẫn được lưu vào bộ nhớ đệm có còn mới nhất hay không và đồng bộ hoá lại nếu đường dẫn đó thay đổi. Google đề xuất bạn nên thay đổi giá trong khoảng từ 2 đến 4 tuần.

Tài nguyên

CardDAV sử dụng các khái niệm REST. Ứng dụng khách hành động trên các tài nguyên được chỉ định bởi URI của họ. Cấu trúc URI hiện tại được chỉ định tại đâ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 phải được phát hiện theo RFC.

  1. Hiệu trưởng
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Bộ nhà riêng
    • 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. Yêu cầu và phản hồi chủ yếu được mã hoá dưới dạng XML. Đây là những thao tác chính mà khách hàng 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 Danh bạ để xác định xem có thay đổi nào đối với danh bạ trên máy chủ hay không và do đó, liệu có cần đồng bộ hoá hay không. Giá trị của thuộc tính này chắc chắn sẽ thay đổi nếu có bất kỳ thông tin liên hệ nào thay đổi. Ứng dụng nên lưu trữ giá trị này và chỉ sử dụng nó trong lần đồng bộ hoá ban đầu và dưới dạng dự phòng khi sync-token không hợp lệ. Thăm dò định kỳ 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á
    • Các chương trình ứng dụng sử dụng yêu cầu sync-token PROPFIND trên Address Book để lấy sync-token thể hiện 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à phát hành các yêu cầu sync-collection REPORT định kỳ để xác định các thay đổi kể từ lần phát hành sync-token gần đây nhất. Mã thông báo đã phát hành có hiệu lực trong 29 ngày và phản hồi REPORT sẽ chứa một sync-token mới.
  • Sử dụng ETag
    • Ứng dụng khách đưa ra yêu cầu getetag PROPFIND trên tài nguyên Danh bạ (có tiêu đề DEPTH bằng DEPTH_1). Bằng cách duy trì giá trị ETag của mỗi người liên hệ, chương trình khách có thể yêu cầu giá trị của những người liên hệ đã thay đổi ETag.
  • Truy xuất danh bạ
    • Ứng dụng khách truy xuất thông tin liên hệ bằng cách đưa ra yêu cầu addressbook-multiget REPORT. Khi cung cấp một danh sách URI liên hệ, báo cáo trả về tất cả các địa chỉ 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 người liên hệ.
  • Chèn người liên hệ
    • Các ứng dụng đưa ra yêu cầu POST với địa chỉ liên hệ mới trong VCard Định dạng 3.0. Phản hồi sẽ chứa mã nhận dạng của người liên hệ mới.
  • Cập nhật một người liên hệ
    • Các ứng dụng khách đưa ra yêu cầu PUT với thông tin liên hệ đã cập nhật ở định dạng VCard 3.0. Người liên hệ sẽ được cập nhật nếu người 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 với ETag hiện có của người liên hệ. Sau đó, máy chủ sẽ từ chối yêu cầu PUT (bằng 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. Điều 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ệ
    • Các ứng dụng khách xoá một người liên hệ bằng cách đưa ra yêu cầu DELETE đối với URI liên hệ.