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 địa chỉ liên hệ mới, chỉnh sửa hoặc xoá địa chỉ liên hệ hiện tại và truy vấn địa chỉ liên hệ phù hợp với tiêu chí cụ thể.

Thông số kỹ thuật

Bản đặc tả đầy đủ không được triển khai, nhưng nhiều ứng dụng khách như Danh bạ Apple iOSTM và macOS phải 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:

Đ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à các tài nguyên liên hệ URI. Bạn không được mã hoá cứng bất kỳ URI nào vì chúng 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. Bất kỳ cố gắng kết nối nào qua HTTP bằng 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 sẽ dẫn đến một HTTP Mã phản hồi 401 Unauthorized.

Để sử dụng CardDAV, chương trình khách của bạn ban đầu phải kết nối với thẻ 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 Tài nguyên sổ địa chỉ, chương trình khách hàng của bạn sau đó có thể thực hiện PROPFIND trên đó để khám phá DAV:current-user-principal, DAV:principal-URL và addressbook-home-set các thuộc tính. 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 thử lại nếu các thiết bị phổ biến Khám phá URI theo định kỳ để xác minh xem đường dẫn được 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. Google đề xuất mức giá 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 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 đó, bạn nên khám phá các tài nguyê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. Thông tin liên hệ
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Đang đồ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 khách hàng sử dụng yêu cầu getctag PROPFIND trên Sổ địa chỉ để xác định xem có bất kỳ địa chỉ liên hệ nào đã thay đổi 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 đảm bảo sẽ thay đổi nếu có bất kỳ thay đổi về thông tin liên hệ. Ứ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 khách hàng sử dụng yêu cầu sync-token PROPFIND trên Địa chỉ Sách để lấy sync-token thể hiện trạng thái hiện tại. Khách hàng ứng dụng phải lưu trữ giá trị này và phát hành sync-collection định kỳ REPORT yêu cầu xác định các thay đổi kể từ lần phát hành gần đây nhất sync-token. Mã thông báo đã phát hành có hiệu lực trong 29 ngày và REPORT phản hồi sẽ chứa sync-token mới.
  • Sử dụng ETag
    • Ứng dụng khách đưa ra yêu cầu getetag PROPFIND trên Địa chỉ Tài nguyên sách (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 hàng có thể yêu cầu giá trị này trong số địa chỉ liên hệ đã thay đổi ETag.
  • Truy xuất người liên hệ
    • Ứng dụng khách truy xuất danh bạ bằng cách cấp một 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ột mục nhập bao gồm ETag cho địa chỉ liên hệ.
  • Chèn một 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ệ
    • Ứng dụng đưa ra yêu cầu PUT với người liên hệ được cập nhật trong Định dạng VCard 3.0. Mục liên hệ sẽ được cập nhật nếu mục liên hệ đã tồn tại trong sổ địa chỉ.
    • Ứng dụng phải bao gồm tiêu đề If-Match có phần tử ETag của địa chỉ liên hệ hiện đã biết. Sau đó, máy chủ sẽ từ chối PUT yêu cầu (với HTTP 412) nếu ETag hiện tại trên máy chủ là khác với ETag do chương trình khách hà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ệ
    • Ứng dụng xoá một người liên hệ bằng cách gửi một yêu cầu DELETE dựa trên URI liên hệ.