หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

ปฏิทิน

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

กิจกรรม

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

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

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

เหตุการณ์เดียวแสดงถึงเหตุการณ์ที่เกิดขึ้นเพียงครั้งเดียว
เหตุการณ์ที่เกิดซ้ำจะกำหนดการเกิดหลายครั้ง

กิจกรรมยังอาจเป็นแบบกำหนดเวลาหรือทั้งวันได้ด้วย

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

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

ผู้จัด

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

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

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

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

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

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

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

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 — จํานวนครั้งที่เหตุการณ์นี้ควรเกิดซ้ำ

คุณใช้ 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 ทั้งหมดยกเว้นไว้

ตัวอย่างเหตุการณ์ที่เกิดขึ้นซ้ำๆ มีดังนี้

กิจกรรมที่เกิดขึ้นตั้งแต่ 06:00 น. ถึง 07: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() ช่วยให้คุณระบุตัวกรองเวลาเริ่มต้นและเวลาสิ้นสุดได้ โดยเมธอดจะแสดงอินสแตนซ์ที่อยู่ในช่วงที่ระบุ ระบบจะใช้เขตเวลาของปฏิทินเพื่อคํานวณเวลาเริ่มต้นและเวลาสิ้นสุดของกิจกรรมที่จัดขึ้นตลอดทั้งวันเพื่อพิจารณาว่ากิจกรรมดังกล่าวอยู่ภายในข้อกําหนดของตัวกรองหรือไม่

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

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

ใส่ออฟเซ็ตเขตเวลาในช่อง 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 หรือใช้การชดเชยเป็น 0 2017-01-25T14:00:00+0000

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

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

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