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

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

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

ปฏิทิน

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

กิจกรรม

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

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

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

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

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

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

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

ผู้จัด

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

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

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

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

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

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

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

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 หมายถึงทุกๆ 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 ของปฏิทิน

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

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