ปฏิทินและกิจกรรม

คู่มือนี้จะอธิบายปฏิทิน กิจกรรม และความสัมพันธ์ของกันและกัน

บริการพิมพ์ปฏิทิน

ปฏิทินคือคอลเล็กชันของกิจกรรมที่เกี่ยวข้อง พร้อมด้วยข้อมูลเมตาเพิ่มเติม เช่น ข้อมูลสรุป เขตเวลาเริ่มต้น สถานที่ตั้ง ฯลฯ แต่ละปฏิทินจะระบุโดยใช้รหัสซึ่งเป็นอีเมล ปฏิทินมีเจ้าของได้หลายคน

กิจกรรม

เหตุการณ์ คือออบเจ็กต์ที่เชื่อมโยงกับวันที่หรือช่วงเวลาที่เจาะจง เหตุการณ์จะได้รับการระบุด้วยรหัสที่ไม่ซ้ํากัน นอกจากวันที่และเวลาเริ่มต้นแล้ว กิจกรรมยังมีข้อมูลอื่นๆ เช่น ข้อมูลสรุป คําอธิบาย สถานที่ สถานะ การช่วยเตือน ไฟล์แนบ ฯลฯ

ประเภทเหตุการณ์

Google ปฏิทินรองรับกิจกรรมแบบครั้งเดียวและที่เกิดซ้ํา ดังนี้

• เหตุการณ์เดี่ยวแสดงถึงรายการที่ไม่ซ้ํากัน
• กิจกรรมที่เกิดซ้ําจะกําหนดจํานวนการเกิดซ้ํา

กิจกรรมอาจมีเวลาหรือทั้งวัน

• เหตุการณ์ตามลําดับเวลาเกิดขึ้นระหว่างเวลา 2 จุดที่เฉพาะเจาะจง เหตุการณ์ที่กําหนดเวลาจะใช้ช่อง start.dateTime และ end.dateTime เพื่อระบุเวลาที่เกิดเหตุการณ์
• กิจกรรมตลอดวันครอบคลุมทั้งวันหรือหลายวันติดต่อกัน กิจกรรมที่จัดตลอดทั้งวันจะใช้ช่อง start.date และ end.date เพื่อระบุเวลาที่เกิดขึ้น โปรดทราบว่าช่องเขตเวลาไม่มีนัยสําคัญสําหรับกิจกรรมตลอดทั้งวัน

เวลาเริ่มต้นและสิ้นสุดของกิจกรรมต้องเป็นเวลาตามลําดับหรือทั้ง 2 วันตลอดทั้งวัน เช่น การระบุไม่ถูกต้อง หากระบุ start.date และ end.dateTime

ผู้จัด

กิจกรรมจะมีผู้จัดเดียว ซึ่งก็คือปฏิทินที่มีสําเนาหลักของกิจกรรม กิจกรรมอาจมีผู้เข้าร่วมได้หลายคน ผู้เข้าร่วมมักจะเป็นปฏิทินหลักของผู้ใช้ที่ได้รับเชิญ

แผนภาพต่อไปนี้แสดงความสัมพันธ์เชิงแนวคิดระหว่างปฏิทิน กิจกรรม และองค์ประกอบอื่นๆ ที่เกี่ยวข้อง

ปฏิทินหลักและปฏิทินอื่นๆ

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

นอกเหนือจากปฏิทินหลักแล้ว คุณสามารถสร้างปฏิทินอื่นๆ อีกกี่ปฏิทินอย่างชัดแจ้ง นอกจากนี้คุณยังแก้ไข ลบ และแชร์ปฏิทินเหล่านี้ระหว่างผู้ใช้หลายคนได้ด้วย

ปฏิทินและรายการปฏิทิน

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

CalendarList คือคอลเล็กชันรายการปฏิทินทั้งหมดที่ผู้ใช้ได้เพิ่มลงในรายการ (แสดงในแผงด้านซ้ายของ UI บนเว็บ) คุณสามารถใช้ปฏิทินนี้เพื่อเพิ่มและนําปฏิทินที่มีอยู่ออก/จากรายชื่อผู้ใช้ได้ นอกจากนี้ ยังใช้เพื่อเรียกข้อมูลและกําหนดค่าของพร็อพเพอร์ตี้ปฏิทินที่เจาะจงผู้ใช้ เช่น การช่วยเตือนเริ่มต้น อีกตัวอย่างหนึ่งคือสีเบื้องหน้า เนื่องจากผู้ใช้แต่ละคนจะตั้งค่าสีที่ต่างกันสําหรับปฏิทินเดียวกันได้

ตารางต่อไปนี้จะเปรียบเทียบความหมายของการดําเนินการสําหรับคอลเล็กชัน 2 ชุด

การดำเนินการ	บริการพิมพ์ปฏิทิน	รายการปฏิทิน
insert	สร้างปฏิทินรองใหม่ โดยค่าเริ่มต้น ปฏิทินนี้จะเพิ่มลงในรายการปฏิทินของครีเอเตอร์ด้วย	แทรกปฏิทินที่มีอยู่ลงในรายชื่อผู้ใช้
delete	ลบปฏิทินรอง	นําปฏิทินออกจากรายชื่อผู้ใช้
get	เรียกดูข้อมูลเมตาของปฏิทิน เช่น ชื่อ เขตเวลา	เรียกข้อมูลเมตาบวกการปรับแต่งเฉพาะผู้ใช้ เช่น สีหรือลบล้างการช่วยเตือน
patch/update	แก้ไขข้อมูลเมตาของปฏิทิน	แก้ไขพร็อพเพอร์ตี้ปฏิทินเฉพาะผู้ใช้

กิจกรรมที่เกิดซ้ํา

กิจกรรมบางอย่างเกิดขึ้นหลายครั้งตามกําหนดเวลาปกติ เช่น การประชุมรายสัปดาห์ วันเกิด และวันหยุด นอกจากจะมีเวลาเริ่มต้นและเวลาสิ้นสุดที่แตกต่างกันแล้ว กิจกรรมที่เกิดซ้ําเหล่านี้ยังเหมือนเดิมด้วย

กิจกรรมเรียกว่าเกิดซ้ํา หากกิจกรรมเกิดซ้ําตามกําหนดการ กิจกรรมแบบครั้งเดียวเป็นแบบรายครั้งและเกิดขึ้นเพียงครั้งเดียว

กฎการเกิดซ้ํา

กําหนดการสําหรับกิจกรรมที่เกิดซ้ําแบ่งออกเป็น 2 ส่วน ได้แก่

• โดยมีช่องเริ่มต้นและตอนจบ (ซึ่งระบุว่าเป็นเหตุการณ์แรก เสมือนเป็นเหตุการณ์เดี่ยวๆ)

• ช่องการเกิดซ้ํา (ซึ่งจะกําหนดวิธีการทําซ้ํากิจกรรมเมื่อเวลาผ่านไป)

ช่องการเกิดซ้ํามีอาร์เรย์ของสตริงที่แสดงถึงพร็อพเพอร์ตี้ RRULE, RDATE หรือ EXDATE อย่างน้อย 1 รายการตามที่กําหนดไว้ใน RFC 5545

พร็อพเพอร์ตี้ RRULE สําคัญที่สุดเนื่องจากกําหนดกฎทั่วไปสําหรับการทําซ้ําเหตุการณ์ ซึ่งประกอบด้วยหลายองค์ประกอบ ตัวอย่างคําขอประเภทดังกล่าว ได้แก่

• FREQ — ความถี่ที่ควรทําซ้ํากิจกรรม (เช่น DAILY หรือ WEEKLY) ต้องระบุ

• INTERVAL - ทํางานร่วมกันกับ FREQ เพื่อระบุความถี่ในการทําซ้ํากิจกรรม ตัวอย่างเช่น FREQ=DAILY;INTERVAL=2 หมายถึง 1 ครั้งในทุกๆ 2 วัน

• COUNT — จํานวนครั้งที่ควรจัดกิจกรรมนี้ซ้ํา

  คุณจะใช้ COUNT หรือ UNTIL เพื่อระบุการสิ้นสุดกิจกรรมที่เกิดซ้ําได้ อย่าใช้ทั้ง 2 อย่างในกฎเดียวกัน

• UNTIL — วันที่หรือวันที่และเวลาที่กิจกรรมควรเกิดซ้ํา (รวม)

• BYDAY — วันในสัปดาห์ที่ควรจัดกิจกรรมซ้ํา (SU, MO, TU ฯลฯ) คอมโพเนนต์อื่นๆ ที่คล้ายกัน ได้แก่ BYMONTH, BYYEARDAY และ BYHOUR

พร็อพเพอร์ตี้ RDATE ระบุวันที่หรือเวลาเพิ่มเติมเมื่อเกิดเหตุการณ์ เช่น RDATE;VALUE=DATE:19970101,19970120 ใช้ข้อมูลนี้เพื่อเพิ่มการเกิดซ้ําโดย RRULE ที่ไม่ครอบคลุม

พร็อพเพอร์ตี้ EXDATE คล้ายกับ RDATE แต่ระบุวันที่หรือวันที่และเวลาที่เหตุการณ์ไม่ควรเกิดขึ้น กล่าวคือ เหตุการณ์เหล่านั้นควรจะได้รับการยกเว้น ซึ่งต้องชี้ไปที่อินสแตนซ์ที่ถูกต้องที่สร้างโดยกฎการเกิดซ้ํา

EXDATE และ RDATE จะมีเขตเวลาได้และต้องเป็นวันที่ (ไม่ใช่วันที่และเวลา) สําหรับกิจกรรมที่จัดตลอดทั้งวัน

พร็อพเพอร์ตี้แต่ละรายการจะเกิดขึ้นภายในช่องการเกิดซ้ําหลายครั้ง การเกิดซ้ําหมายถึงการรวมกฎ RRULE และ RDATE ทั้งหมด ลบด้วยกฎที่ยกเว้นจากกฎ EXDATE ทั้งหมด

ต่อไปนี้คือตัวอย่างกิจกรรมที่เกิดซ้ํา

1. เหตุการณ์ที่เกิดขึ้นตั้งแต่เวลา 6.00 น. ถึง 7.00 น. ของทุกวันอังคารและวันศุกร์ เริ่มตั้งแต่วันที่ 15 กันยายน 2015 และหยุดหลังจากวันที่ 5 ของเดือนในวันที่ 29 กันยายน

   ...
   "start": {
    "dateTime": "2015-09-15T06:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "end": {
    "dateTime": "2015-09-15T07:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "recurrence": [
    "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
   ],
   …
   

2. กิจกรรมตลอดวันที่เริ่มต้นในวันที่ 1 มิถุนายน 2015 และทําซ้ําทุก 3 วันตลอดทั้งเดือน ยกเว้นวันที่ 10 มิถุนายน ยกเว้นวันที่ 9 และ 11 มิถุนายน

   ...
   "start": {
    "date": "2015-06-01"
   },
   "end": {
    "date": "2015-06-02"
   },
   "recurrence": [
    "EXDATE;VALUE=DATE:20150610",
    "RDATE;VALUE=DATE:20150609,20150611",
    "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
   ],
   …
   

อินสแตนซ์และข้อยกเว้น

กิจกรรมที่เกิดซ้ําประกอบด้วยอินสแตนซ์หลายรายการ เช่น จํานวนเหตุการณ์ที่เกิดขึ้นในเวลาที่ต่างกัน ซึ่งอินสแตนซ์เหล่านี้จะทําหน้าที่เป็นเหตุการณ์ด้วยตนเอง

การแก้ไขกิจกรรมที่เกิดซ้ําอาจส่งผลต่อทั้งกิจกรรมที่เกิดซ้ํา (และอินสแตนซ์ทั้งหมดของกิจกรรม) หรือเฉพาะอินสแตนซ์แต่ละรายการ อินสแตนซ์ที่แตกต่างจากเหตุการณ์ที่เกิดซ้ําของผู้ปกครองเรียกว่าข้อยกเว้น

เช่น ข้อยกเว้นอาจมีข้อมูลสรุปอื่น เวลาเริ่มต้นอื่น หรือผู้เข้าร่วมเพิ่มเติมที่ได้รับคําเชิญสําหรับอินสแตนซ์นั้นเท่านั้น นอกจากนี้ คุณยังยกเลิกอินสแตนซ์ทั้งหมดได้โดยไม่ต้องนํากิจกรรมที่เกิดซ้ําออก (การยกเลิกอินสแตนซ์จะแสดงในกิจกรรม status)

ดูวิธีจัดการกิจกรรมและอินสแตนซ์ที่เกิดซ้ําผ่าน Calendar API ได้ที่นี่

เขตเวลา

เขตเวลาจะระบุภูมิภาคที่สังเกตเห็นเวลามาตรฐานแบบเดียวกัน ใน Calendar API คุณจะระบุเขตเวลาโดยใช้ตัวระบุเขตเวลา IANA ได้

คุณกําหนดเขตเวลาสําหรับทั้งปฏิทินและกิจกรรมได้ ส่วนต่อไปนี้จะอธิบายผลกระทบของการตั้งค่าเหล่านี้

เขตเวลาของปฏิทิน

เขตเวลาของปฏิทินเรียกอีกอย่างว่าเขตเวลาเริ่มต้น เนื่องจากผลกระทบต่อผลการค้นหา เขตเวลาของปฏิทินจะส่งผลต่อวิธีที่ค่าเวลาตีความหรือนําเสนอโดยเมธอด events.get(), events.list() และ events.instances()

การแปลงเขตเวลาของผลการค้นหา

ผลลัพธ์ของเมธอด get(),list() และ instances() จะแสดงผลในเขตเวลาที่คุณระบุไว้ในพารามิเตอร์ timeZone หากคุณละเว้นพารามิเตอร์นี้ เมธอดเหล่านี้ทั้งหมดจะใช้เขตเวลาของปฏิทินเป็นค่าเริ่มต้น

การจับคู่กิจกรรมที่เกิดขึ้นตลอดวันกับคําค้นหาที่มีการแบ่งเวลา

เมธอด list() และ instances() ช่วยให้คุณระบุตัวกรองเวลาเริ่มต้นและเวลาสิ้นสุดได้ พร้อมด้วยเมธอดที่ส่งคืนอินสแตนซ์ที่อยู่ในช่วงที่ระบุ เขตเวลาของปฏิทินใช้ในการคํานวณเวลาเริ่มต้นและสิ้นสุดของกิจกรรมตลอดทั้งวันเพื่อพิจารณาว่ากิจกรรมเหล่านั้นเป็นไปตามข้อกําหนดของตัวกรองหรือไม่

เขตเวลาของกิจกรรม

อินสแตนซ์เหตุการณ์มีเวลาเริ่มต้นและเวลาสิ้นสุด โดยข้อกําหนดของเวลาเหล่านี้อาจรวมถึงเขตเวลาด้วย คุณสามารถระบุเขตเวลาได้หลายวิธี ดังนี้ เขตเวลาต่อไปนี้ระบุเวลาเดียวกัน

• ใส่การชดเชยเขตเวลาในช่อง dateTime เช่น 2017-01-25T09:00:00-0500
• ระบุเวลาที่ไม่มีออฟเซ็ต เช่น 2017-01-25T09:00:00 โดยการเว้นช่อง timeZone ว่างไว้ (ใช้เขตเวลาเริ่มต้นโดยปริยาย)
• ระบุเวลาที่ไม่มีออฟเซ็ต เช่น 2017-01-25T09:00:00 แต่ใช้ช่อง timeZone เพื่อระบุเขตเวลา

นอกจากนี้ คุณยังระบุเวลากิจกรรมใน UTC ได้หากต้องการ

• ระบุเวลาในเขตเวลา UTC: 2017-01-25T14:00:00Z หรือใช้ออฟเซ็ต 2017-01-25T14:00:00+0000

การแสดงเวลาภายในของเหตุการณ์เหมือนกันทั้งหมดในทุกกรณี แต่การตั้งค่าช่อง timeZone จะแนบเขตเวลาไปกับกิจกรรม เช่นเดียวกับการกําหนดเขตเวลาของกิจกรรมโดยใช้ UI ของปฏิทิน ดังนี้

สําหรับกิจกรรมเดียว คุณจะระบุเขตเวลาที่แตกต่างกันสําหรับเวลาเริ่มต้นและเวลาสิ้นสุดของกิจกรรมได้ (วิธีนี้ช่วยส่งเสริมเหตุการณ์ต่างๆ เช่น การเดินทาง ซึ่งจริงๆ แล้วเริ่มต้นในเขตเวลาที่ต่างกัน) โปรดดูกิจกรรมที่เกิดซ้ํา

เขตเวลาของกิจกรรมที่เกิดซ้ํา

สําหรับกิจกรรมที่เกิดซ้ํา คุณต้องระบุเขตเวลาเดียวเสมอ จําเป็นสําหรับการขยายการเกิดซ้ําของกิจกรรม