หน้านี้ได้รับการแปลโดย 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 ทั้งหมด

ตัวอย่างกิจกรรมที่เกิดซ้ำมีดังนี้

กิจกรรมที่เกิดขึ้นตั้งแต่เวลา 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 หรือใช้ออฟเซ็ตเป็น 0 2017-01-25T14:00:00+0000

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

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

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