คู่มือสําหรับนักพัฒนาซอฟต์แวร์ 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 จะมีการจัดรูปแบบตามข้อกำหนดของ iCalendar
  • ขณะนี้ยังไม่รองรับข้อมูล 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 ด้วย UserAgent ของ 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 จุดเริ่มต้นก่อน ไม่ว่าในกรณีใด การเชื่อมต่อต้องทำผ่าน 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.