คู่มือนี้จะอธิบายปฏิทิน กิจกรรม และความสัมพันธ์ของแต่ละกิจกรรม
บริการพิมพ์ปฏิทิน
ปฏิทินคือคอลเล็กชันของกิจกรรมที่เกี่ยวข้อง รวมถึงข้อมูลเมตาเพิ่มเติม เช่น สรุป เขตเวลาเริ่มต้น สถานที่ ฯลฯ ปฏิทินแต่ละรายการจะระบุด้วยรหัสซึ่งเป็นที่อยู่อีเมล ปฏิทินมีเจ้าของได้หลายคน
กิจกรรม
เหตุการณ์คือออบเจ็กต์ที่เชื่อมโยงกับช่วงวันที่หรือเวลาที่เฉพาะเจาะจง เหตุการณ์จะได้รับการระบุโดยรหัสที่ไม่ซ้ำกัน นอกจากวันที่และเวลาเริ่มต้นและสิ้นสุดแล้ว กิจกรรมยังมีข้อมูลอื่นๆ เช่น สรุป คำอธิบาย ตำแหน่ง สถานะ การแจ้งเตือน ไฟล์แนบ ฯลฯ
ประเภทเหตุการณ์
Google ปฏิทินรองรับกิจกรรมครั้งเดียวและที่เกิดซ้ำ
- เหตุการณ์เดี่ยวจะแสดงรายการที่ไม่ซ้ำ
- เหตุการณ์ตามรอบจะกำหนดการเกิดขึ้นหลายครั้ง
กิจกรรมอาจเป็นแบบกำหนดเวลาหรือตลอดวัน ดังนี้
- เหตุการณ์ตามลำดับเวลาจะเกิดขึ้นระหว่าง 2 ช่วงเวลาที่เจาะจง เหตุการณ์ที่กำหนดเวลาไว้จะใช้ช่อง
start.dateTime
และend.dateTime
เพื่อระบุเวลาที่เกิดขึ้น - กิจกรรมแบบตลอดวันที่ครอบคลุมทั้งวันหรือติดต่อกันหลายวัน เหตุการณ์ตลอดทั้งวันใช้ช่อง
start.date
และend.date
เพื่อระบุเวลาที่เกิดขึ้น โปรดทราบว่าช่องเขตเวลาไม่มีความสำคัญสำหรับกิจกรรมตลอดทั้งวัน
ผู้จัด
กิจกรรมจะมีผู้จัดรายเดียว ซึ่งก็คือปฏิทินที่มีสำเนาหลักของกิจกรรม กิจกรรมอาจมีผู้เข้าร่วมหลายรายการด้วย ผู้เข้าร่วมมักจะเป็นปฏิทินหลักของผู้ใช้ที่ได้รับเชิญ
แผนภาพต่อไปนี้แสดงความสัมพันธ์เชิงมโนทัศน์ระหว่างปฏิทิน กิจกรรม และองค์ประกอบอื่นๆ ที่เกี่ยวข้อง
ปฏิทินหลักและปฏิทินอื่นๆ
ปฏิทินหลักคือปฏิทินประเภทพิเศษที่เชื่อมโยงกับบัญชีผู้ใช้รายเดียว ระบบจะสร้างปฏิทินนี้ขึ้นโดยอัตโนมัติสำหรับบัญชีผู้ใช้ใหม่แต่ละบัญชี และรหัสตรงกับอีเมลหลักของผู้ใช้ ตราบใดที่บัญชียังมีอยู่ ปฏิทินหลักของผู้ใช้จะไม่สามารถลบหรือ "เป็นเจ้าของ" ได้ แต่ยังคงแชร์กับผู้ใช้คนอื่นๆ ได้
นอกจากปฏิทินหลักแล้ว คุณสามารถสร้างปฏิทินอื่นๆ ได้ตามต้องการ สามารถแก้ไข ลบ และแชร์ปฏิทินระหว่างผู้ใช้หลายรายได้
ปฏิทินและรายชื่อปฏิทิน
คอลเล็กชันปฏิทินจะแสดงปฏิทินที่มีอยู่ทั้งหมด สามารถสร้างและลบปฏิทิน นอกจากนี้ คุณยังสามารถเรียกหรือตั้งค่าพร็อพเพอร์ตี้ร่วมที่แชร์กันระหว่างผู้ใช้ทั้งหมดที่มีสิทธิ์เข้าถึงปฏิทินได้ด้วย เช่น ชื่อปฏิทินและเขตเวลาเริ่มต้น เป็นพร็อพเพอร์ตี้ส่วนกลาง
CalendarList คือคอลเล็กชันของรายการในปฏิทินทั้งหมดที่ผู้ใช้เพิ่มไว้ในรายการ (แสดงในแผงด้านซ้ายของ UI ทางเว็บ) คุณสามารถใช้เมนูนี้เพื่อเพิ่มและนำปฏิทิน ที่มีอยู่ออกไปยัง/ออกจากรายการของผู้ใช้ นอกจากนี้คุณยังใช้เพื่อเรียกข้อมูลและตั้งค่า คุณสมบัติปฏิทินที่เจาะจงผู้ใช้ได้ เช่น การช่วยเตือนเริ่มต้น อีกตัวอย่างหนึ่งคือสีพื้นหน้า เนื่องจากผู้ใช้แต่ละคนอาจมีสีที่ต่างกันสำหรับปฏิทินเดียวกัน
ตารางต่อไปนี้จะเปรียบเทียบความหมายของการดำเนินการสำหรับคอลเล็กชันทั้งสอง
การดำเนินการ | บริการพิมพ์ปฏิทิน | 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 Calendar API คุณต้องระบุเขตเวลาโดยใช้ตัวระบุเขตเวลาของ IANA
คุณสามารถตั้งค่าเขตเวลาสำหรับทั้งปฏิทินและกิจกรรมได้ ส่วนต่อไปนี้จะอธิบายผลกระทบของการตั้งค่าเหล่านี้
เขตเวลาของปฏิทิน
เขตเวลาของปฏิทินเรียกอีกอย่างว่าเขตเวลาเริ่มต้นเนื่องจากมีผลกับผลลัพธ์การค้นหา เขตเวลาของปฏิทินจะส่งผลต่อวิธีที่เมธอด events.get()
, events.list()
และ events.instances()
ตีความหรือนำเสนอค่าเวลา
- การแปลงเขตเวลาของผลการค้นหา
- ระบบจะแสดงผลลัพธ์ของเมธอด
get()
,list()
และinstances()
ในเขตเวลาที่คุณระบุในพารามิเตอร์timeZone
หากคุณไม่ใส่พารามิเตอร์นี้ เมธอดเหล่านี้จะใช้เขตเวลาของปฏิทินเป็นค่าเริ่มต้น - การจับคู่กิจกรรมตลอดทั้งวันกับคำค้นหาที่มีการจำกัดเวลา
- เมธอด
list()
และinstances()
ช่วยให้คุณระบุตัวกรองเวลาเริ่มต้นและสิ้นสุดได้ด้วยวิธีการแสดงผลอินสแตนซ์ที่อยู่ในช่วงที่ระบุ เขตเวลาของปฏิทินใช้เพื่อคำนวณเวลาเริ่มต้นและเวลาสิ้นสุดของกิจกรรมตลอดทั้งวัน เพื่อพิจารณาว่ากิจกรรมนั้นเป็นไปตามข้อกำหนดของตัวกรองหรือไม่
เขตเวลาของกิจกรรม
อินสแตนซ์กิจกรรมจะมีเวลาเริ่มต้นและสิ้นสุด ข้อกำหนดสำหรับเวลาเหล่านี้อาจมีเขตเวลาด้วย คุณสามารถระบุเขตเวลาได้หลายวิธี โดยทั้ง 2 แบบต่อไปนี้จะระบุเวลาเดียวกัน
- ใส่ค่าออฟเซ็ตเขตเวลาในช่อง
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
ออฟเซ็ต 0
การแสดงเวลาของกิจกรรมภายในจะเหมือนกันในทุกกรณีเหล่านี้ แต่การตั้งค่าช่อง timeZone
จะแนบเขตเวลาให้กับกิจกรรม เช่นเดียวกับเวลาที่คุณตั้งค่าเขตเวลาของกิจกรรมโดยใช้ UI ของปฏิทิน ดังนี้
เขตเวลาของกิจกรรมที่เกิดซ้ำ
สำหรับกิจกรรมที่เกิดซ้ำ คุณจะต้องระบุเขตเวลาเดียวเสมอ จำเป็นต้องใช้ในการขยายการเกิดซ้ำของกิจกรรม