คู่มือนี้จะอธิบายเกี่ยวกับปฏิทิน กิจกรรม และความสัมพันธ์ซึ่งกันและกัน
บริการพิมพ์ปฏิทิน
ปฏิทินคือคอลเล็กชันของกิจกรรมที่เกี่ยวข้องกัน พร้อมด้วยข้อมูลเมตาเพิ่มเติม เช่น ข้อมูลสรุป เขตเวลาเริ่มต้น สถานที่ ฯลฯ แต่ละปฏิทินจะระบุด้วยรหัสซึ่งเป็นที่อยู่อีเมล ปฏิทินมีเจ้าของได้หลายคน
กิจกรรม
เหตุการณ์คือออบเจ็กต์ที่เชื่อมโยงกับช่วงวันที่หรือเวลาที่เจาะจง ระบบจะระบุเหตุการณ์ด้วยรหัสที่ไม่ซ้ำกัน นอกจากวันที่และเวลาเริ่มต้นและสิ้นสุดแล้ว กิจกรรมยังมีข้อมูลอื่นๆ เช่น สรุป คำอธิบาย สถานที่ สถานะ การช่วยเตือน ไฟล์แนบ ฯลฯ
ประเภทเหตุการณ์
Google ปฏิทินรองรับกิจกรรมครั้งเดียวและกิจกรรมที่เกิดซ้ำดังนี้
- เหตุการณ์เดียวแสดงถึงรายการที่ไม่ซ้ำ
- กิจกรรมที่เกิดซ้ำจะเป็นการกำหนดหลายครั้ง
กิจกรรมอาจเป็นแบบตามกำหนดเวลาหรือตลอดวัน ดังนี้
- เหตุการณ์ตามกำหนดเวลาจะเกิดขึ้นระหว่างช่วงเวลาที่เฉพาะเจาะจง 2 ช่วงเวลา เหตุการณ์ตามลำดับเวลาจะใช้ช่อง
start.dateTime
และend.dateTime
เพื่อระบุเวลาที่เกิดเหตุการณ์ - กิจกรรมตลอดทั้งวันจะครอบคลุมทั้งวันหรือหลายวันติดต่อกัน กิจกรรมตลอดทั้งวันจะใช้ช่อง
start.date
และend.date
เพื่อระบุเวลาที่เกิด โปรดทราบว่าช่องเขตเวลาไม่มีนัยสำคัญสำหรับกิจกรรมตลอดทั้งวัน
ผู้จัด
กิจกรรมจะมีผู้จัดเพียงรายการเดียว ซึ่งเป็นปฏิทินที่มีสำเนาหลักของกิจกรรม นอกจากนี้ กิจกรรมยังมีผู้เข้าร่วมได้หลายรายการ โดยผู้เข้าร่วมมักเป็นปฏิทินหลักของผู้ใช้ที่ได้รับเชิญ
แผนภาพต่อไปนี้แสดงความสัมพันธ์เชิงแนวคิดระหว่างปฏิทิน กิจกรรม และองค์ประกอบอื่นๆ ที่เกี่ยวข้อง
ปฏิทินหลักและปฏิทินอื่นๆ
ปฏิทินหลัก คือปฏิทินประเภทพิเศษที่เชื่อมโยงกับบัญชีผู้ใช้เดียว ปฏิทินนี้สร้างขึ้นโดยอัตโนมัติสำหรับบัญชีผู้ใช้ใหม่แต่ละบัญชี และรหัสมักจะตรงกับที่อยู่อีเมลหลักของผู้ใช้ ตราบใดที่ยังมีบัญชีนี้อยู่ ผู้ใช้จะไม่สามารถลบปฏิทินหลักหรือ "ไม่ได้เป็นเจ้าของ" ได้ แต่สามารถแชร์ให้ผู้ใช้คนอื่นๆ ได้
นอกจากปฏิทินหลักแล้ว คุณยังสร้างปฏิทินอื่นๆ ได้ตามต้องการ โดยสามารถแก้ไข ลบ และแชร์ได้ระหว่างผู้ใช้หลายคน
ปฏิทินและรายการปฏิทิน
คอลเล็กชันปฏิทินจะแสดงปฏิทินที่มีอยู่ทั้งหมด โดยสามารถใช้สร้างและลบปฏิทิน และคุณยังเรียกดูหรือตั้งค่าพร็อพเพอร์ตี้ส่วนกลางที่แชร์กับผู้ใช้ทั้งหมดที่มีสิทธิ์เข้าถึงปฏิทินได้ด้วย เช่น ชื่อปฏิทินและเขตเวลาเริ่มต้นคือพร็อพเพอร์ตี้ส่วนกลาง
CalendarListคือคอลเล็กชันของรายการปฏิทินทั้งหมดที่ผู้ใช้เพิ่มไว้ในรายการ (แสดงในแผงด้านซ้ายของ UI บนเว็บ) คุณสามารถใช้เพื่อเพิ่มและนำปฏิทินที่มีอยู่ออก ไปยัง/ออกจากรายการของผู้ใช้ได้ นอกจากนี้ ยังใช้เพื่อเรียกและตั้งค่า ของพร็อพเพอร์ตี้ปฏิทินเฉพาะผู้ใช้ เช่น การช่วยเตือนเริ่มต้น อีกตัวอย่างหนึ่งคือสีพื้นหน้า เนื่องจากผู้ใช้แต่ละคนอาจมีชุดสีที่ต่างกันสำหรับปฏิทินเดียวกันได้
ตารางต่อไปนี้จะเปรียบเทียบความหมายของการดำเนินการของทั้ง 2 คอลเล็กชัน
การดำเนินการ | บริการพิมพ์ปฏิทิน | CalendarList |
---|---|---|
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
— จำนวนครั้งที่ควรทำกิจกรรมนี้ซ้ำUNTIL
— วันที่หรือวันที่และเวลาที่ควรสร้างเหตุการณ์ซ้ำ (รวมด้วย)BYDAY
— วันในสัปดาห์ที่ควรแสดงเหตุการณ์ซ้ำ (SU
,MO
,TU
ฯลฯ) คอมโพเนนต์อื่นๆ ที่คล้ายกัน ได้แก่BYMONTH
,BYYEARDAY
และBYHOUR
พร็อพเพอร์ตี้ RDATE
ระบุวันที่หรือวันที่และเวลาเพิ่มเติมที่จะเกิดเหตุการณ์ เช่น RDATE;VALUE=DATE:19970101,19970120
ใช้รายการนี้เพื่อเพิ่มเหตุการณ์พิเศษที่ RRULE
ไม่ได้กล่าวถึง
พร็อพเพอร์ตี้ EXDATE
คล้ายกับ RDATE แต่จะระบุวันที่หรือวันที่และเวลาที่ไม่ควรเกิดเหตุการณ์ กล่าวคือ ระบบควรยกเว้น
เหตุการณ์เหล่านั้น โดยต้องชี้ไปยังอินสแตนซ์ที่ถูกต้องซึ่งกฎการเกิดซ้ำสร้างขึ้น
EXDATE
และ RDATE
มีเขตเวลาได้ และต้องเป็นวันที่ (ไม่ใช่วันที่และเวลา) สำหรับกิจกรรมตลอดทั้งวัน
พร็อพเพอร์ตี้แต่ละรายการอาจเกิดขึ้นในช่องการเกิดซ้ำหลายครั้ง
การเกิดซ้ำหมายถึงการรวมกฎ RRULE
และกฎ RDATE
ทั้งหมดเข้าด้วยกัน ลบกับรายการที่ยกเว้นโดยกฎ EXDATE
ทั้งหมด
ตัวอย่างกิจกรรมที่เกิดซ้ำมีดังนี้
กิจกรรมที่เกิดขึ้นตั้งแต่เวลา 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" ], …
กิจกรรมตลอดทั้งวันที่เริ่มในวันที่ 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
)
ดูตัวอย่างวิธีทำงานกับกิจกรรมที่เกิดซ้ำและอินสแตนซ์ผ่าน Google Calendar API ได้ที่นี่
เขตเวลา
เขตเวลาจะระบุภูมิภาคที่ใช้เวลามาตรฐานเดียวกัน ใน Google ปฏิทิน 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
หรือใช้ออฟเซ็ตเป็น 02017-01-25T14:00:00+0000
การแสดงเวลาภายในของกิจกรรมจะเท่ากันในทุกกรณีเหล่านี้
แต่การตั้งค่าช่อง timeZone
จะเพิ่มเขตเวลาให้กับกิจกรรม เช่นเดียวกับ
เมื่อคุณตั้งค่าเขตเวลาของกิจกรรมโดยใช้ UI ปฏิทิน
เขตเวลาของกิจกรรมที่เกิดซ้ำ
ต้องระบุเขตเวลาเดียวสำหรับกิจกรรมที่เกิดซ้ำ เป็นสิ่งที่จำเป็นเพื่อขยายการเกิดซ้ำของกิจกรรม