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

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

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

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

ไม่ได้ใช้ข้อกำหนดฉบับเต็ม แต่ไคลเอ็นต์จำนวนมาก เช่น รายชื่อติดต่อของ Apple iOS™ และ macOS ควรทำงานร่วมกันได้อย่างถูกต้อง

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

• rfc2518: ส่วนขยาย HTTP สำหรับการเขียนแบบกระจาย (WebDAV)
  • รองรับเมธอด HTTP GET, PUT, DELETE, OPTIONS และ PROPFIND
  • ไม่รองรับเมธอด HTTP LOCK, UNLOCK, COPY, MOVE หรือ MKCOL
  • ไม่รองรับพร็อพเพอร์ตี้ WebDAV ที่กำหนดเอง (ผู้ใช้กำหนด)
  • ไม่รองรับการควบคุมการเข้าถึง WebDAV (rfc3744)
• rfc5995: การใช้ "โพสต์" เพื่อเพิ่มสมาชิกไปยังคอลเล็กชัน WebDAV
  • รองรับการสร้างรายชื่อติดต่อใหม่โดยไม่ต้องระบุรหัส
• rfc6352: CardDAV: ส่วนขยาย vCard ไปยังการเขียนที่เผยแพร่บนเว็บและ การกำหนดเวอร์ชัน (WebDAV)
  • รองรับเมธอด HTTP REPORT แต่รายงานที่กำหนดไว้บางส่วนอาจไม่ได้รับ ที่มีการนำไปใช้
  • รองรับการให้คอลเล็กชันหลักและคอลเล็กชันรายชื่อติดต่อ
• rfc6578: การซิงค์คอลเล็กชันสำหรับ WebDAV
  • แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนเป็นโหมดนี้หลังจาก การซิงค์ครั้งแรก
• rfc6749: กรอบการให้สิทธิ์ OAuth 2.0 และ rfc6750: กรอบการให้สิทธิ์ OAuth 2.0: การใช้โทเค็น Bearer
  • รองรับการตรวจสอบสิทธิ์โปรแกรมไคลเอ็นต์ CardDAV โดยใช้ OAuth 2.0 HTTP การตรวจสอบสิทธิ์ Google ไม่รองรับวิธีการตรวจสอบสิทธิ์อื่นๆ เรากำหนดให้การเชื่อมต่อ CardDAV ใช้ HTTPS เพื่อรักษาความปลอดภัยของข้อมูลรายชื่อติดต่อ
• rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to 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 แบบฮาร์ดโค้ด เนื่องจาก URI อาจเปลี่ยนแปลงได้ทุกเมื่อ

แอปพลิเคชันไคลเอ็นต์ต้องใช้ HTTPS และการตรวจสอบสิทธิ์ OAuth 2.0 ต้องใช้ สำหรับบัญชี Google ของผู้ใช้ เซิร์ฟเวอร์ CardDAV จะไม่ตรวจสอบสิทธิ์คำขอ เว้นแต่คำขอจะส่งผ่าน HTTPS พร้อมการตรวจสอบสิทธิ์ OAuth 2.0 ของบัญชี Google และแอปพลิเคชันของคุณได้รับการลงทะเบียนใน DevConsole การพยายามเชื่อมต่อผ่าน HTTP ด้วยการตรวจสอบสิทธิ์พื้นฐานหรือด้วยอีเมล/รหัสผ่านที่ไม่ตรงกับบัญชี Google จะส่งผลให้เกิดรหัสการตอบกลับ HTTP401 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. Home Set
   • 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 ในที่อยู่ แหล่งข้อมูลหนังสือ (ที่มีส่วนหัว 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 ของรายชื่อติดต่อ