จัดการรายชื่อติดต่อด้วยโปรโตคอล 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 Access Control (rfc3744)
• rfc5995: การใช้ POST เพื่อเพิ่มสมาชิกไปยังคอลเล็กชัน WebDAV
  • รองรับการสร้างรายชื่อติดต่อใหม่โดยไม่ต้องระบุรหัส
• rfc6352: CardDAV: ส่วนขยาย vCard ไปยังการเขียนแบบกระจายและการกำหนดเวอร์ชันแบบเว็บ (WebDAV)
  • รองรับเมธอด HTTP REPORT แต่ไม่ได้นำรายงานที่กำหนดไว้ทั้งหมดมาใช้
  • รองรับการระบุคอลเล็กชันหลักและคอลเล็กชันรายชื่อติดต่อ
• rfc6578: การซิงค์ข้อมูลคอลเล็กชันสำหรับ WebDAV
  • แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนเป็นโหมดนี้หลังจากการซิงค์ครั้งแรก
• rfc6749: เฟรมเวิร์กการให้สิทธิ์ OAuth 2.0 และ rfc6750: เฟรมเวิร์กการให้สิทธิ์ OAuth 2.0: การใช้โทเค็นสำหรับผู้ถือ
  • รองรับการตรวจสอบสิทธิ์โปรแกรมไคลเอ็นต์ CardDAV โดยใช้การตรวจสอบสิทธิ์ HTTP ของ OAuth 2.0 Google ไม่รองรับวิธีการตรวจสอบสิทธิ์อื่นๆ เรากำหนดให้การเชื่อมต่อ CardDAV ต้องใช้ HTTPS เพื่อความปลอดภัยของข้อมูลรายชื่อติดต่อ
• rfc6764: การค้นหาบริการค้นหาส่วนขยายปฏิทินไปยัง WebDAV (CalDAV) และแปลงจาก VDAV เป็น 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 ได้จากเอกสารที่ลิงก์ด้านล่าง

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

แหล่งข้อมูล

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

1. อาจารย์ใหญ่
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. ชุดโฮม
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. สมุดที่อยู่
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. การติดต่อ
   • https://www.googleapis.com/carddav/v1/principals/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 ในทรัพยากร Address Book (ที่มีส่วนหัว DEPTH เท่ากับ DEPTH_1) การคงค่า ETag ของรายชื่อติดต่อแต่ละรายการไว้ โปรแกรมไคลเอ็นต์จะขอค่าของรายชื่อติดต่อที่มีการเปลี่ยนแปลง ETag ได้
• การดึงข้อมูลรายชื่อติดต่อ
  • แอปพลิเคชันไคลเอ็นต์จะเรียกรายชื่อติดต่อด้วยการออกคำขอ addressbook-multiget REPORT ด้วยการแสดงรายการ URI รายชื่อติดต่อ รายงานจะแสดงรายชื่อติดต่อที่ขอทั้งหมดเป็นค่า VCard 3.0 โดยแต่ละรายการจะมี ETag สำหรับรายชื่อติดต่อ
• การแทรกรายชื่อติดต่อ
  • แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ POST กับรายชื่อติดต่อใหม่ในรูปแบบ VCard 3.0 การตอบกลับจะมีรหัสของรายชื่อติดต่อใหม่
• การอัปเดตรายชื่อติดต่อ
  • แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ PUT กับรายชื่อติดต่อที่อัปเดตในรูปแบบ VCard 3.0 ที่อยู่ติดต่อจะอัปเดตหากมีรายชื่อในสมุดที่อยู่อยู่แล้ว
  • แอปพลิเคชันไคลเอ็นต์ควรมีส่วนหัว If-Match พร้อมด้วย ETag ที่รู้จักของรายชื่อติดต่อในปัจจุบัน จากนั้นเซิร์ฟเวอร์จะปฏิเสธคำขอ PUT (ที่มี HTTP 412) หาก ETag ปัจจุบันบนเซิร์ฟเวอร์ต่างจาก ETag ที่ส่งมาจากโปรแกรมไคลเอ็นต์ วิธีนี้จะช่วยให้การอัปเดตเป็นลำดับที่ดีที่สุด
• การลบรายชื่อติดต่อ
  • แอปพลิเคชันไคลเอ็นต์จะลบรายชื่อติดต่อด้วยการออกคำขอ DELETE ต่อ URI ของรายชื่อติดต่อ