จัดการรายชื่อติดต่อด้วยโปรโตคอล CardDAV

คุณสามารถดูและจัดการรายชื่อติดต่อโดยใช้โปรโตคอล CardDAV ของ Google

รายชื่อติดต่อจะจัดเก็บไว้ในบัญชี Google ของผู้ใช้ บริการส่วนใหญ่ของ Google มีสิทธิ์เข้าถึงรายชื่อติดต่อ แอปพลิเคชันไคลเอ็นต์ของคุณสามารถใช้ CardDAV API เพื่อสร้างรายชื่อติดต่อใหม่ แก้ไขหรือลบรายชื่อติดต่อที่มีอยู่ และค้นหารายชื่อติดต่อที่ตรงกับเกณฑ์ที่ต้องการได้

ข้อกำหนดเฉพาะ

ไม่ได้ใช้ข้อกําหนดทั้งหมด แต่ไคลเอ็นต์จํานวนมาก เช่น Apple iOSTM Contacts และ macOS ควรทํางานร่วมกันได้อย่างถูกต้อง

สําหรับข้อกําหนดที่เกี่ยวข้องแต่ละรายการ การรองรับ CardDAV ของ Google มีดังต่อไปนี้

• rfc2518: ส่วนขยาย HTTP สําหรับการเขียนแบบกระจาย (WebDAV)
  • รองรับเมธอด HTTP GET, PUT, DELETE, OPTIONS และ PROPFIND
  • ไม่รองรับเมธอด HTTP LOCK, UNLOCK, COPY, MOVE หรือ MKCOL
  • ไม่รองรับพร็อพเพอร์ตี้ WebDAV ที่กําหนดเอง (ผู้ใช้กําหนด)
  • ไม่รองรับการควบคุมการเข้าถึง WebDAV (rfc3744)
• rfc5995: การใช้ POST เพื่อเพิ่มสมาชิกไปยังคอลเล็กชัน WebDAV
  • รองรับการสร้างรายชื่อติดต่อใหม่โดยไม่ต้องระบุรหัส
• rfc6352: CardDAV: vCard เป็นส่วนขยายสําหรับการเผยแพร่และเผยแพร่เวอร์ชันบนเว็บ (WebDAV)
  • รองรับเมธอด HTTP REPORT แต่ไม่ได้ใช้รายงานที่กําหนดไว้บางรายการ
  • รองรับการรวบรวมคอลเล็กชันหลักและคอลเล็กชันรายชื่อติดต่อ
• rfc6578: การซิงค์คอลเล็กชันสําหรับ WebDAV
  • แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนเป็นโหมดนี้หลังจากการซิงค์เริ่มต้น
• rfc6749: เฟรมเวิร์กการให้สิทธิ์ OAuth 2.0 และ rfc6750: กรอบการให้สิทธิ์ OAuth 2.0: การใช้โทเค็น Bearer
  • รองรับการตรวจสอบสิทธิ์โปรแกรมไคลเอ็นต์ CardDAV โดยใช้การตรวจสอบสิทธิ์ HTTP 2.0 ของ OAuth Google ไม่รองรับการตรวจสอบสิทธิ์ด้วยวิธีอื่นๆ เราต้องใช้การเชื่อมต่อ CardDAV เพื่อใช้ HTTPS เพื่อความปลอดภัยของข้อมูลติดต่อ
• rfc6764: ค้นหาบริการสําหรับส่วนขยายปฏิทินไปยัง WebDAV (CalDAV) และส่วนขยาย vCard ไปยัง WebDAV (CardDAV)
  • การเปิดเครื่อง URL ของ CardDAV ต้องเป็นไปตามส่วนที่ 6 ของ rfc6764
• รองรับ caldav-ctag-02: Calendar Collection Entity Tag (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 API

• การใช้ OAuth 2.0 เพื่อเข้าถึง Google API
• การใช้ OAuth 2.0 สําหรับแอปพลิเคชันที่ติดตั้งไว้

การเชื่อมต่อกับเซิร์ฟเวอร์ 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) อุปกรณ์ควรลองเรียกใช้ Discovery ที่มีชื่อเสียงอีกครั้งเป็นระยะๆ เพื่อตรวจสอบว่าเส้นทางที่แคชไว้ยังคงเป็นปัจจุบันหรือไม่ และซิงค์อีกครั้งหากเส้นทางมีการเปลี่ยนแปลง Google ขอแนะนําให้ใช้อัตราทุกๆ 2-4 สัปดาห์

ทรัพยากร

CardDAV ใช้แนวคิด REST แอปพลิเคชันไคลเอ็นต์จะดําเนินการกับทรัพยากรที่กําหนดโดย URI ของผู้ใช้ เราระบุโครงสร้าง URI ปัจจุบันไว้ที่นี่เพื่อช่วยให้นักพัฒนาแอปเข้าใจแนวคิดในส่วนต่อไปนี้ โครงสร้างอาจมีการเปลี่ยนแปลงและต้องฮาร์ดโค้ด แต่ควรสํารวจทรัพยากรตาม RFC

1. ครูใหญ่
   • https://www.googleapis.com/carddav/v1/Princips/userEmail
2. ชุดอยู่บ้าน
   • https://www.googleapis.com/carddav/v1/Princips/userEmail/lists
3. สมุดที่อยู่
   • https://www.googleapis.com/carddav/v1/Princips/userEmail/lists/default
4. ข้อมูลติดต่อ
   • https://www.googleapis.com/carddav/v1/Princips/userEmail/lists/default/contactId

การซิงค์รายชื่อติดต่อ

ต่อไปนี้เป็นคําอธิบายทั่วไปเกี่ยวกับการดําเนินการที่รองรับ นักพัฒนาซอฟต์แวร์ควรดูรายละเอียดใน RFC ที่เกี่ยวข้อง คําขอและการตอบกลับจะเข้ารหัสใน XML เป็นส่วนใหญ่ การดําเนินการหลักที่แอปพลิเคชันไคลเอ็นต์ใช้ในการซิงค์มีดังนี้

• การใช้ CTag
  • โปรแกรมไคลเอ็นต์จะใช้คําขอ getctag PROPFIND ในทรัพยากรสมุดที่อยู่เพื่อระบุว่ารายชื่อติดต่อใดมีการเปลี่ยนแปลงในเซิร์ฟเวอร์หรือไม่ และต้องมีการซิงค์หรือไม่ ค่าของพร็อพเพอร์ตี้นี้รับประกันว่าจะเปลี่ยนแปลงได้หากมีรายชื่อติดต่อมีการเปลี่ยนแปลง แอปพลิเคชันไคลเอ็นต์ควรเก็บค่านี้ไว้ และใช้เฉพาะในการซิงค์ครั้งแรกเท่านั้น และใช้เป็นตัวเลือกสํารองเมื่อ 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 รายชื่อติดต่อ