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

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

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

บริการพิมพ์ปฏิทิน

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

กิจกรรม

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

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

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

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

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

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

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

ผู้จัด

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

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

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

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

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

ปฏิทินและรายชื่อปฏิทิน

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

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" เพื่อระบุการสิ้นสุดการเกิดซ้ำของกิจกรรม อย่าใช้ทั้ง 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 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 ของปฏิทิน ดังนี้

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

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