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

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

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

CalDAV API มีขีดจำกัดโควต้าเช่นเดียวกับ Calendar API ดูข้อมูลเพิ่มเติมได้ที่ ขีดจำกัด การใช้งาน

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

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

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

    • รองรับเมธอด HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND และ PROPPATCH
    • ไม่รองรับเมธอด HTTP LOCK, UNLOCK, COPY, MOVE, MKCOL หรือส่วนหัว If* (ยกเว้น If-Match)
    • ไม่รองรับพร็อพเพอร์ตี้ WebDAV ที่กำหนดเอง (ผู้ใช้กำหนด)
    • ไม่รองรับการควบคุมการเข้าถึง WebDAV (rfc3744)

  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)

    • รองรับเมธอด HTTP REPORT เราได้ใช้รายงานทั้งหมดแล้ว ยกเว้น free-busy-query
    • ไม่รองรับเมธอด HTTP MKCALENDAR
    • ไม่รองรับการดำเนินการ AUDIO

  • rfc5545: iCalendar

    • ข้อมูลที่แสดงในอินเทอร์เฟซ CalDAV จะได้รับการจัดรูปแบบตามข้อกำหนด iCalendar
    • ไม่รองรับข้อมูล VTODO หรือ VJOURNAL
    • ไม่รองรับส่วนขยาย Apple iCal เพื่ออนุญาตพร็อพเพอร์ตี้ URL ที่ผู้ใช้กำหนดได้

  • rfc6578: Collection Synchronization for WebDAV

    • แอปพลิเคชันไคลเอ็นต์ต้องเปลี่ยนไปใช้โหมดการทำงานนี้หลังจากการซิงค์ครั้งแรก

  • rfc6638: Scheduling Extensions to CalDAV

    • รองรับ "กล่องจดหมาย" ขนาดเล็ก ซึ่งว่างเปล่าเสมอ
    • ระบบจะส่งคำเชิญที่คุณได้รับไปยังคอลเล็กชัน "กิจกรรม" โดยอัตโนมัติแทนที่จะวางไว้ใน "กล่องจดหมาย"
    • ไม่รองรับการค้นหา free-busy

  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

    • ctag ของปฏิทินจะคล้ายกับ etag ของทรัพยากร โดยจะเปลี่ยนไปเมื่อมีการเปลี่ยนแปลงในปฏิทิน ซึ่งช่วยให้แอปพลิเคชันไคลเอ็นต์ทราบได้อย่างรวดเร็วว่าไม่จำเป็นต้องซิงค์กิจกรรมที่มีการเปลี่ยนแปลง

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • หากต้องการปรับปรุงประสิทธิภาพการซิงค์ปฏิทิน คำขอที่มีพร็อพเพอร์ตี้ calendar-proxy-read-for หรือ calendar-proxy-write-for จะล้มเหลวด้วย UserAgent ของ iOS เนื่องจากอุปกรณ์ iOS ไม่รองรับการมอบสิทธิ์

แม้ว่าการใช้งาน CalDAV ของเราจะไม่ครอบคลุมทุกข้อกำหนด แต่ก็ทำงานได้อย่างถูกต้องสำหรับไคลเอ็นต์จำนวนมาก รวมถึงปฏิทินของ Apple

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

หากต้องการใช้ CalDAV API คุณต้องมี บัญชี Google

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

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

จากนั้นคุณต้องเปิดใช้งาน CalDAV API

วิธีเปิดใช้ API สำหรับโปรเจ็กต์

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

หากต้องการส่งคำขอ CalDAV API คุณต้องมีรหัสไคลเอ็นต์ และ Client Secret

วิธีค้นหารหัสไคลเอ็นต์และ Client Secret ของโปรเจ็กต์

  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/CALENDAR_ID/user

แทนที่ CALENDAR_ID ด้วยรหัสของปฏิทินที่จะเข้าถึง

หากต้องการค้นหารหัสปฏิทินผ่านอินเทอร์เฟซเว็บ ให้เลือก **การตั้งค่าปฏิทิน** ในเมนูแบบเลื่อนลงข้างชื่อปฏิทิน รหัสปฏิทินจะแสดงในส่วนที่มีป้ายกำกับว่าที่อยู่ปฏิทิน รหัสปฏิทินสำหรับปฏิทินหลักของผู้ใช้จะเหมือนกับอีเมลของผู้ใช้รายนั้น

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

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