คู่มือสำหรับนักพัฒนาซอฟต์แวร์ 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 (rfc3744)
• rfc4791: ส่วนขยายปฏิทินไปยัง WebDAV (CalDAV)
  • รองรับเมธอด HTTP REPORT ระบบจะใช้งานรายงานทั้งหมด ยกเว้นการค้นหาว่าง/ไม่ว่าง
  • ไม่สนับสนุนเมธอด HTTP MKCALENDAR
  • ไม่สนับสนุนการดำเนินการ AUDIO
• rfc5545: iปฏิทิน
  • ข้อมูลที่เปิดเผยในอินเทอร์เฟซ CalDAV จะมีการจัดรูปแบบตามข้อกำหนดของ iปฏิทิน
  • ปัจจุบันยังไม่รองรับข้อมูล 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 โปรโตคอล CalDAV ควรทำงานร่วมกันอย่างถูกต้อง

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

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

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

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

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

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

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

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