คุณสามารถดูและจัดการรายชื่อติดต่อได้โดยใช้โปรโตคอล CardDAV ของ Google
รายชื่อติดต่อจะเก็บไว้ในบัญชี Google ของผู้ใช้ บริการส่วนใหญ่ของ Google เข้าถึงรายชื่อผู้ติดต่อ แอปพลิเคชันไคลเอ็นต์ของคุณสามารถใช้ CardDAV API เพื่อ สร้างรายชื่อติดต่อใหม่ แก้ไขหรือลบรายชื่อติดต่อที่มีอยู่ และค้นหารายชื่อติดต่อ ที่ตรงกับเกณฑ์หนึ่งๆ
ข้อกำหนดเฉพาะ
ยังไม่มีการนำข้อกำหนดทั้งหมดมาใช้ แต่มีการใช้ไคลเอ็นต์จำนวนมาก เช่น รายชื่อติดต่อของ Apple iOSTM และ macOS ควรทำงานร่วมกันได้อย่างถูกต้อง
สำหรับข้อกำหนดเฉพาะที่เกี่ยวข้องแต่ละรายการ การรองรับ CardDAV ของ Google มีดังนี้
- rfc2518: ส่วนขยาย HTTP สำหรับการเขียนแบบกระจาย (WebDAV)
- รองรับเมธอด HTTP
GET
,PUT
,DELETE
,OPTIONS
และPROPFIND
- ไม่รองรับเมธอด HTTP
LOCK
,UNLOCK
,COPY
,MOVE
หรือMKCOL
- ไม่รองรับพร็อพเพอร์ตี้ WebDAV ที่กำหนดเอง (กำหนดโดยผู้ใช้)
- ไม่รองรับการควบคุมการเข้าถึง WebDAV (rfc3744)
- รองรับเมธอด HTTP
- rfc5995: การใช้ "โพสต์" เพื่อเพิ่มสมาชิกไปยังคอลเล็กชัน WebDAV
- รองรับการสร้างรายชื่อติดต่อใหม่โดยไม่ต้องระบุรหัส
- rfc6352: CardDAV: ส่วนขยาย vCard ไปยังการเขียนที่เผยแพร่บนเว็บและ
การกำหนดเวอร์ชัน (WebDAV)
- รองรับเมธอด HTTP
REPORT
แต่รายงานที่กำหนดไว้บางส่วนอาจไม่ได้รับ ที่มีการนำไปใช้ - รองรับการจัดหาคอลเล็กชันหลักและคอลเล็กชันรายชื่อติดต่อ
- รองรับเมธอด HTTP
- rfc6578: การซิงค์คอลเล็กชันสำหรับ WebDAV
- แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนเป็นโหมดนี้หลังจาก การซิงค์ครั้งแรก
- rfc6749: กรอบการให้สิทธิ์ OAuth 2.0 และ
rfc6750: เฟรมเวิร์กการให้สิทธิ์ OAuth 2.0: การใช้โทเค็นของผู้ถือ
- รองรับการตรวจสอบสิทธิ์โปรแกรมไคลเอ็นต์ CardDAV โดยใช้ OAuth 2.0 HTTP การตรวจสอบสิทธิ์ Google ไม่รองรับวิธีการตรวจสอบสิทธิ์วิธีอื่น เพื่อความปลอดภัยของข้อมูลรายชื่อติดต่อ เรากำหนดให้ใช้การเชื่อมต่อ CardDAV เพื่อใช้งาน HTTPS
- rfc6764: บริการค้นหาสำหรับส่วนขยายปฏิทินไปยัง WebDAV (CalDAV) และส่วนขยาย vCard ไปยัง WebDAV (CardDAV)
- การเปิดเครื่อง URL ของ CardDAV ต้องดำเนินการตามส่วนที่ 6 ของ rfc6764
- รองรับ
caldav-ctag-02: แท็กเอนทิตีคอลเล็กชันปฏิทิน (CTag) ใน CalDAV
ซึ่งใช้ร่วมกันระหว่างข้อกำหนดของ CardDAV และ CalDAV รายชื่อติดต่อ
ctag
เป็นเหมือนทรัพยากรETag
จะมีการเปลี่ยนแปลงเมื่อมีอะไรในรายชื่อติดต่อ สมุดที่อยู่มีการเปลี่ยนแปลง วิธีนี้ทำให้โปรแกรมไคลเอ็นต์ตรวจสอบ ว่าไม่จำเป็นต้องซิงค์ข้อมูลรายชื่อติดต่อที่เปลี่ยนแปลง - Google จะใช้ VCard 3.0 เป็นรูปแบบการเข้ารหัสรายชื่อติดต่อ โปรดดูหัวข้อต่อไปนี้ rfc6350: VCard 3.0
CardDAV ของ Google ต้องใช้ OAuth 2.0
อินเทอร์เฟซ CardDAV ของ Google ต้องการ OAuth 2.0 ดูข้อมูลที่ลิงก์ เอกสารด้านล่างนี้สำหรับข้อมูลเกี่ยวกับการใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs
กำลังเชื่อมต่อกับเซิร์ฟเวอร์ CardDAV ของ Google
โปรโตคอล CardDAV จะช่วยให้ค้นพบสมุดที่อยู่และทรัพยากรสำหรับการติดต่อ URI คุณต้องไม่ฮาร์ดโค้ด URI ใดๆ เนื่องจากอาจเปลี่ยนแปลงได้ตลอดเวลา
แอปพลิเคชันไคลเอ็นต์ต้องใช้ HTTPS และการตรวจสอบสิทธิ์ OAuth 2.0
ต้องใช้
สำหรับบัญชี Google ของผู้ใช้ เซิร์ฟเวอร์ CardDAV จะไม่
ตรวจสอบสิทธิ์คำขอยกเว้นคำขอจะมาถึง HTTPS ที่มี OAuth 2.0
บัญชี Google ของคุณ และแอปพลิเคชันของคุณมีการลงทะเบียนใน
DevConsole ความพยายามใดๆ ในการเชื่อมต่อผ่าน HTTP ด้วยการตรวจสอบสิทธิ์ขั้นพื้นฐานหรือกับ
อีเมล/รหัสผ่านที่ไม่ตรงกับบัญชี Google จะส่งผลให้เกิด HTTP
โค้ดตอบกลับ 401 Unauthorized
หากต้องการใช้ CardDAV โปรแกรมไคลเอ็นต์ของคุณต้องเชื่อมต่อกับหน้า Canonical ตั้งแต่แรก
เส้นทางการค้นพบโดยใช้ HTTP PROPFIND
ใน:
https://www.googleapis.com/.well-known/carddav
เมื่อเปลี่ยนเส้นทาง (HTTP 301
) ไปยังทรัพยากรของสมุดที่อยู่ โปรแกรมไคลเอ็นต์
สามารถดำเนินการ PROPFIND
บนส่วนขยายเพื่อค้นหา
DAV:current-user-principal
DAV:principal-URL
และ addressbook-home-set
พร็อพเพอร์ตี้ จากนั้น โปรแกรมลูกค้าของคุณสามารถค้นหาสมุดที่อยู่หลักได้โดย
แสดง PROPFIND
ใน addressbook-home-set
และกำลังค้นหา
ทรัพยากร addressbook
และ collection
คำอธิบายกระบวนการนี้แบบเต็ม
อยู่นอกเหนือขอบเขตของเอกสารนี้ โปรดดู
rfc6352 สำหรับรายละเอียดเพิ่มเติม
แสดงเส้นทางการเปลี่ยนเส้นทางในการตอบกลับ HTTP 301
ผ่าน PROPFIND
เมื่อ
URI ที่รู้จักกันดีต้องไม่ถูกแคชไว้อย่างถาวร (ตาม
rfc6764) อุปกรณ์ควรเป็นที่รู้จักกันดีอีกครั้ง
การค้นพบ URI เป็นระยะเพื่อยืนยันว่าเส้นทางที่แคชไว้ยังเป็นข้อมูลล่าสุดอยู่หรือไม่ และ
ซิงค์ใหม่หากเส้นทางเปลี่ยนแปลง Google ขอแนะนำให้คิดค่าบริการทุก 2-4 สัปดาห์
แหล่งข้อมูล
CardDAV ใช้แนวคิด REST แอปพลิเคชันไคลเอ็นต์จะดำเนินการกับทรัพยากรที่ ที่กำหนดโดย URI ของตัวเอง มีการระบุโครงสร้าง URI ปัจจุบันที่นี่เพื่อช่วย เข้าใจแนวคิดในส่วนต่อไป โครงสร้างอาจ เปลี่ยนแปลงและต้องไม่ถูกฮาร์ดโค้ด แต่ควรค้นพบแหล่งข้อมูล ตาม RFC
- อาจารย์ใหญ่
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- ชุดบ้าน
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- สมุดที่อยู่
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- การติดต่อ
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
การทำข้อมูลรายชื่อติดต่อให้ตรงกัน
ต่อไปนี้เป็นคำอธิบายทั่วไปของการดำเนินการที่สนับสนุน นักพัฒนาซอฟต์แวร์ ให้ดูรายละเอียดใน RFC ที่เกี่ยวข้อง คำขอและการตอบกลับ ซึ่งส่วนใหญ่จะเข้ารหัสในรูปแบบ XML ต่อไปนี้คือการดำเนินการหลักที่ไคลเอ็นต์ใช้ แอปพลิเคชันสำหรับการทำข้อมูลให้ตรงกัน:
- การใช้ CTag
- โปรแกรมไคลเอ็นต์ใช้คำขอ
PROPFIND
getctag
ในสมุดที่อยู่ ในการพิจารณาว่าที่อยู่ติดต่อมีการเปลี่ยนแปลงในเซิร์ฟเวอร์หรือไม่ และ ดังนั้นจึงจำเป็นต้องมีการซิงค์หรือไม่ ค่าของพร็อพเพอร์ตี้นี้ เปลี่ยนแปลงได้เมื่อมีการเปลี่ยนแปลงการติดต่อ แอปพลิเคชันไคลเอ็นต์ ควรจัดเก็บค่านี้และใช้ในการซิงค์ครั้งแรกเท่านั้นและ ใช้ทางเลือกสำรองเมื่อsync-token
ใช้งานไม่ได้ ทำการสำรวจเป็นระยะๆ เพื่อหา พร็อพเพอร์ตี้getctag
รายการจะส่งผลให้มีการควบคุม
- โปรแกรมไคลเอ็นต์ใช้คำขอ
- การใช้โทเค็นการซิงค์
- โปรแกรมไคลเอ็นต์ใช้คำขอ
sync-token
PROPFIND
กับที่อยู่ หนังสือเพื่อรับsync-token
ที่แสดงถึงสถานะปัจจุบันของหนังสือ ลูกค้า แอปพลิเคชันต้องเก็บค่านี้และออกsync-collection
เป็นระยะREPORT
คำขอเพื่อระบุการเปลี่ยนแปลงนับตั้งแต่ที่ออกครั้งล่าสุดsync-token
โทเค็นที่ออกแล้วจะใช้ได้เป็นเวลา 29 วัน และREPORT
การตอบกลับจะมีsync-token
ใหม่
- โปรแกรมไคลเอ็นต์ใช้คำขอ
- การใช้ ETag
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
getetag
PROPFIND
ในที่อยู่ แหล่งข้อมูลหนังสือ (ที่มีส่วนหัวDEPTH
เท่ากับDEPTH_1
) โดยการรักษา ค่าETag
ของรายชื่อติดต่อแต่ละรายการ โปรแกรมของไคลเอ็นต์สามารถขอมูลค่าได้ ของรายชื่อติดต่อที่ETag
มีการเปลี่ยนแปลง
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
- กำลังดึงข้อมูลรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะเรียกข้อมูลที่อยู่ติดต่อด้วยการออก
คำขอ
REPORT
addressbook-multiget
รายการ ได้รายการ URI รายชื่อติดต่อ รายงานจะแสดงรายชื่อติดต่อที่ขอทั้งหมดเป็นค่า VCard 3.0 ชิ้น รายการมีETag
สำหรับรายชื่อติดต่อนั้น
- แอปพลิเคชันไคลเอ็นต์จะเรียกข้อมูลที่อยู่ติดต่อด้วยการออก
คำขอ
- การแทรกรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
POST
กับผู้ติดต่อใหม่ใน VCard 3.0 การตอบกลับจะมีรหัสของรายชื่อติดต่อใหม่
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
- การอัปเดตรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
PUT
ให้กับรายชื่อติดต่อที่อัปเดตแล้วใน รูปแบบ VCard 3.0 ผู้ติดต่อจะอัปเดตหากมีอยู่แล้ว ในสมุดที่อยู่ - แอปพลิเคชันไคลเอ็นต์ควรมีส่วนหัว
If-Match
ที่มีเมธอด ขณะนี้รายชื่อติดต่อดังกล่าวรู้จักETag
จากนั้นเซิร์ฟเวอร์จะปฏิเสธPUT
(ที่มีHTTP 412
) ถ้าETag
ปัจจุบันบนเซิร์ฟเวอร์คือ แตกต่างจากETag
ที่โปรแกรมลูกค้าส่งมา ซึ่งช่วยให้ การเรียงลำดับการอัปเดตอย่างเหมาะสม
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
- การลบรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะลบรายชื่อติดต่อโดยการส่งคำขอ
DELETE
เทียบกับ URI รายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะลบรายชื่อติดต่อโดยการส่งคำขอ