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:
- rfc2518: Tiện ích HTTP cho Quyền tác giả được phân phối (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 danh bạ mới mà không cần chỉ định mã nhận dạng.
- rfc6352: CardDAV: vCard Tiện ích cho việc tạo phiên bản và tạo phiên bản phân phối trên web (WebDAV)
- Hỗ trợ phương thức HTTP
REPORT
, nhưng không phải tất cả các báo cáo đã xác định đều được triển khai. - Hỗ trợ việc 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
- Các ứng dụng khách phải chuyển sang chế độ hoạt động này sau lần đồ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 Bearer
- Hỗ trợ xác thực chương trình máy khách CardDAV bằng Xác thực HTTP OAuth 2.0. 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 của người liên hệ, chúng tôi yêu cầu các kết nối CardDAV phải sử dụng HTTPS.
- rfc6764: Định vị dịch vụ cho Tiện ích lập lịch cho WebDAV (CalDAV) và vCard Tiện ích cho WebDAV (CardDAV)
- Quá trình tự khởi động URL của CardDAV phải diễn ra theo mục 6 của rfc6764.
- Hỗ trợ
caldav-ctag-02: Thẻ thực thể tập hợp lịch (CTag) trong CalDAV,
được chia sẻ giữa thông số kỹ thuật CardDAV và CalDAV. Danh bạ
ctag
giống như một tài nguyênETag
; tài nguyên này thay đổi khi có bất kỳ nội dung nào trong sổ địa chỉ liên hệ thay đổi. Điều này cho phép chương trình ứng dụng nhanh chóng xác định rằng chương trình này không cần đồng bộ hoá bất kỳ danh bạ nào đã thay đổi. - Google sử dụng VCard 3.0 làm định dạng mã hoá địa chỉ liên hệ. Hãy xem bài viết: 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 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.
- Hiệu trưởng
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Bộ màn hình chính
- 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/
- Liên hệ
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Đồ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 khisync-token
không hợp lệ. Việc thăm dò định kỳ cho thuộc tínhgetctag
sẽ dẫn đến tình trạng điều tiết.
- Các chương trình ứng dụng sử dụng yêu cầu
- 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ấysync-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ầusync-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ủaREPORT
sẽ chứa mộtsync-token
mới.
- Chương trình ứng dụng sử dụng yêu cầu
- 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ằngDEPTH_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 đổiETag
.
- Ứng dụng khách đưa ra một yêu cầu
- 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ộtETag
cho địa chỉ 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
- 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.
- Ứng dụng khách đưa ra một yêu cầu
- 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ầuPUT
(vớiHTTP 412
) nếuETag
hiện tại trên máy chủ khác vớiETag
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.
- Ứng dụng khách đưa ra một yêu cầu
- 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ệ đó.
- Ứng dụng khách xoá một mục liên hệ bằng cách đưa ra yêu cầu