คู่มือสําหรับนักพัฒนาซอฟต์แวร์ CalDAV API

CalDAV เป็นส่วนขยายของ WebDAV ที่ให้มาตรฐานแก่ลูกค้าในการเข้าถึงข้อมูลปฏิทินในเซิร์ฟเวอร์ระยะไกล

Google มีอินเทอร์เฟซ CalDAV ที่คุณสามารถใช้เพื่อดูและจัดการปฏิทินโดยใช้โปรโตคอล CalDAV

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

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

• rfc4918: ส่วนขยาย HTTP สําหรับการเขียนและการเผยแพร่เวอร์ชันที่เผยแพร่ในเว็บ (WebDAV)
  • รองรับเมธอด HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND และ PROPPATCH
  • ไม่รองรับเมธอด HTTP, LOCK, UNLOCK, COPY, MOVE หรือ MKCOL หรือส่วนหัว If* (ยกเว้น If-Match)
  • ไม่รองรับพร็อพเพอร์ตี้ WebDAV ที่กําหนดเอง (กําหนดโดยผู้ใช้)
  • ไม่รองรับ WebDAV Access Control (rfc3744)
• rfc4791: ส่วนขยายปฏิทินไปยัง WebDAV (CalDAV)
  • รองรับเมธอด HTTP REPORT ระบบจะติดตั้งใช้งานรายงานทั้งหมดยกเว้นการค้นหาข้อมูลว่าง/ไม่ว่าง
  • ไม่รองรับเมธอด HTTP MKCALENDAR
  • ไม่รองรับการดําเนินการ AUDIO
• rfc5545: iCalendar
  • ข้อมูลที่เปิดเผยในอินเทอร์เฟซ CalDAV จะได้รับการจัดรูปแบบตามข้อกําหนดของ iMessage
  • ปัจจุบันยังไม่รองรับข้อมูล VTODO หรือ VJOURNAL
  • ไม่รองรับส่วนขยาย Apple iCal® เพื่ออนุญาตพร็อพเพอร์ตี้ URL ที่ผู้ใช้ตั้งค่าได้
• rfc6578: การซิงค์คอลเล็กชันสําหรับ WebDAV
  • แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนเป็นโหมดนี้หลังจากการซิงค์เริ่มต้น
• rfc6638: การตั้งเวลาส่วนขยายไปยัง CalDAV
  • รองรับ "กล่องจดหมาย" เล็กๆ ซึ่งว่างเปล่าเสมอ
  • คําเชิญที่คุณได้รับจะส่งไปยังคอลเล็กชัน "กิจกรรม" โดยอัตโนมัติ แทนที่จะวางไว้ใน "กล่องจดหมาย"
  • ไม่รองรับการค้นหาว่าง/ไม่ว่าง
• caldav-ctag-02: ปฏิทินเอนทิตีคอลเล็กชันปฏิทิน (CTag) ใน CalDAV
  • ปฏิทิน ctag เป็นเหมือนทรัพยากร etag ซึ่งมีการเปลี่ยนแปลงเมื่อมีการเปลี่ยนแปลงในปฏิทิน วิธีนี้ช่วยให้แอปพลิเคชันไคลเอ็นต์ทราบได้อย่างรวดเร็วว่าไม่จําเป็นต้องซิงค์ข้อมูลเหตุการณ์ที่มีการเปลี่ยนแปลง
• calendar-Proxy: ฟังก์ชันพร็อกซีของผู้ใช้ในปฏิทินใน CalDAV
  • หากต้องการปรับปรุงการซิงค์ปฏิทินจากอุปกรณ์ iOS ซึ่งไม่รองรับการมอบสิทธิ์ การใช้พร็อพเพอร์ตี้ calendar-proxy-read-for หรือ calendar-proxy-write-for กับ User Agent ของ iOS จะล้มเหลว

เรายังไม่ได้จัดเตรียมข้อกําหนดที่เกี่ยวข้องทั้งหมดอย่างเต็มรูปแบบ อย่างไรก็ตาม สําหรับไคลเอ็นต์หลายรายการ เช่น Apple iCal โปรโตคอล CalDAV ควรทํางานร่วมกันได้อย่างถูกต้อง

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

การสร้างรหัสไคลเอ็นต์

หากต้องการใช้ CalDAV API คุณต้องมีบัญชี Google หากมีบัญชีที่ใช้งานได้ ทุกอย่างก็พร้อมใช้งาน

ก่อนที่จะส่งคําขอไปยัง CalDAV API คุณต้องลงทะเบียนไคลเอ็นต์กับคอนโซล Google API ด้วยการสร้างโปรเจ็กต์

ไปที่คอนโซล Google API คลิกสร้างโครงการ จากนั้นป้อนชื่อแล้วคลิกสร้าง

ขั้นตอนถัดไปคือการเปิดใช้งาน CalDAV API

หากต้องการเปิดใช้ API สําหรับโปรเจ็กต์ ให้ทําตามขั้นตอนต่อไปนี้

1. เปิดไลบรารี API ในคอนโซล Google API เมื่อได้รับข้อความเตือน ให้เลือกโปรเจ็กต์หรือสร้างโปรเจ็กต์ใหม่ ไลบรารี API จะแสดง API ที่พร้อมใช้งานทั้งหมด โดยจัดกลุ่มตามตระกูลผลิตภัณฑ์และความนิยม
2. หาก API ที่ต้องการเปิดใช้ไม่แสดงในรายการ ให้ใช้การค้นหาเพื่อหา API
3. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
4. เปิดใช้การเรียกเก็บเงินหากได้รับข้อความแจ้ง
5. ยอมรับข้อกําหนดในการให้บริการของ API หากได้รับแจ้ง

หากต้องการส่งคําขอ CalDAV API คุณจะต้องใช้รหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์

หากต้องการค้นหารหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์ของโปรเจ็กต์ ให้ทําดังนี้

1. เลือกข้อมูลเข้าสู่ระบบ OAuth 2.0 ที่มีอยู่ หรือเปิดหน้าข้อมูลเข้าสู่ระบบ
2. หากยังไม่ได้ดําเนินการ ให้สร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 ของโปรเจ็กต์โดยคลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth และระบุข้อมูลที่จําเป็นในการสร้างข้อมูลเข้าสู่ระบบ
3. มองหารหัสไคลเอ็นต์ในส่วนรหัสไคลเอ็นต์ OAuth 2.0 คลิกรหัสไคลเอ็นต์เพื่อดูรายละเอียด

การเชื่อมต่อกับเซิร์ฟเวอร์ CalDAV ของ Google

หากต้องการใช้อินเทอร์เฟซ CalDAV โปรแกรมไคลเอ็นต์จะเชื่อมต่อกับเซิร์ฟเวอร์ปฏิทินในตอนต้นของหนึ่งใน 2 จุดเริ่มต้น ในทั้ง 2 กรณี การเชื่อมต่อจะต้องทําผ่าน HTTPS และต้องใช้รูปแบบการตรวจสอบสิทธิ์ OAuth 2.0 เซิร์ฟเวอร์ CalDAV จะปฏิเสธการตรวจสอบสิทธิ์คําขอ ยกเว้นกรณีที่มาถึง HTTPS ด้วยการตรวจสอบสิทธิ์ OAuth 2.0 ของบัญชี Google กําลังพยายามเชื่อมต่อผ่าน HTTP หรือใช้การตรวจสอบสิทธิ์พื้นฐานในรหัสสถานะ HTTP 401 Unauthorized

หากโปรแกรมไคลเอ็นต์ (เช่น Apple iCal) ต้องใช้คอลเล็กชันหลักเป็นจุดเริ่มต้น URI ที่จะเชื่อมต่อคือ

https://apidata.googleusercontent.com/caldav/v2/calid/user

ควรแทนที่ calid ด้วย "รหัสปฏิทิน" ของปฏิทินในการเข้าถึง ซึ่งดูผ่านอินเทอร์เฟซบนเว็บของ Google ปฏิทินได้ดังต่อไปนี้ ในเมนูแบบเลื่อนลงข้างชื่อปฏิทิน ให้เลือกการตั้งค่าปฏิทิน ในหน้าผลลัพธ์ รหัสปฏิทินจะแสดงในส่วนที่มีป้ายกํากับที่อยู่ปฏิทิน รหัสปฏิทินสําหรับปฏิทินหลักของผู้ใช้จะเหมือนกันกับอีเมลของผู้ใช้

หากโปรแกรมไคลเอ็นต์ (เช่น Mozilla Sunbird) กําหนดให้การรวบรวมปฏิทินเป็นจุดเริ่มต้น URI ที่จะเชื่อมต่อคือ

https://apidata.googleusercontent.com/caldav/v2/calid/events

ปลายทางเก่า https://www.google.com/calendar/dav เลิกใช้งานแล้วและไม่รองรับอีกต่อไป คุณต้องรับความเสี่ยงจากการใช้งานปลายทางเอง เราขอแนะนําให้เปลี่ยนไปใช้รูปแบบปลายทางใหม่ตามที่อธิบายข้างต้น

iCal เป็นเครื่องหมายการค้าของ Apple Inc.