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:
- rfc2518: Tiện ích HTTP cho hoạt động soạn thảo phân tán (WebDAV)
- Hỗ trợ các phương thức HTTP
GET
,PUT
,DELETE
,OPTIONS
vàPROPFIND
. - Không hỗ trợ các phương thức HTTP
LOCK
,UNLOCK
,COPY
,MOVE
hoặcMKCOL
. - 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).
- Hỗ trợ các phương thức HTTP
- rfc5995: Sử dụng POST để thêm thành viên vào Bộ sưu tập WebDAV
- Hỗ trợ tạo người liên hệ mới mà không cần chỉ định mã nhận dạng.
- rfc6352: CardDAV: Tiện ích vCard để soạn thảo nội dung phân phối trên web và
Tạo phiên bản (WebDAV)
- Hỗ trợ phương thức HTTP
REPORT
, nhưng không phải báo cáo đã xác định nào cũng triển khai. - Hỗ trợ cung cấp một bộ sưu tập chính và một bộ sưu tập danh bạ.
- Hỗ trợ phương thức HTTP
- rfc6578: Đồng bộ hoá bộ sưu tập cho WebDAV
- Ứng dụng khách phải chuyển sang chế độ hoạt động này sau đồng bộ hoá ban đầu.
- rfc6749: Khung uỷ quyền OAuth 2.0 và
rfc6750: Khung uỷ quyền OAuth 2.0: Sử dụng mã thông báo mang mã
- Hỗ trợ xác thực các chương trình ứng dụng CardDAV bằng giao thức HTTP OAuth 2.0 Xác thực. Google không hỗ trợ bất kỳ phương pháp xác thực nào khác. Để bảo mật dữ liệu liên hệ, chúng tôi yêu cầu bạn phải sử dụng kết nối CardDAV HTTPS.
- rfc6764: Định vị dịch vụ cho các tiện ích lên lịch cho WebDAV (CalDAV) và tiện ích vCard với WebDAV (CardDAV)
- Quá trình tự khởi động đối với URL CardDAV phải diễn ra theo mục 6 của rfc6764.
- Hỗ trợ
caldav-ctag-02: Thẻ thực thể bộ sưu tập lịch (CTag) trong CalDAV,
Mã này được dùng chung giữa các thông số kỹ thuật CardDAV và CalDAV. Danh bạ
ctag
giống như một tài nguyênETag
; khi bất cứ nội dung nào trong danh bạ đó thay đổi sổ địa chỉ đã thay đổi. Điều này cho phép chương trình khách hàng nhanh chóng xác định rằng nó không cần đồng bộ hoá bất kỳ danh bạ đã thay đổi nào. - Google sử dụng VCard 3.0 làm định dạng mã hoá địa chỉ liên hệ. Hãy xem: rfc6350: VCard 3.0.
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.
- Hiệu trưởng
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Bộ nhà riêng
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Sổ địa chỉ
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Thông tin liên hệ
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Đ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 khisync-token
không hợp lệ. Thăm dò định kỳ Thuộc tínhgetctag
sẽ dẫn đến tình trạng điều tiết.
- Các chương trình khách hàng sử dụng yêu cầu
- 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ấysync-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ànhsync-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ấtsync-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ứasync-token
mới.
- Các chương trình khách hàng sử dụng yêu cầu
- 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ằngDEPTH_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 đổiETag
.
- Ứng dụng khách đưa ra yêu cầu
- 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ồmETag
cho địa chỉ 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
- 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ác ứng dụng đưa ra yêu cầu
- 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ốiPUT
yêu cầu (vớiHTTP 412
) nếuETag
hiện tại trên máy chủ là khác vớiETag
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.
- Ứng dụng đưa ra yêu cầu
- 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ệ.
- Ứng dụng xoá một người liên hệ bằng cách gửi một yêu cầu