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

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

ปฏิทิน

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

กิจกรรม

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

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

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

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

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

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

ผู้จัด

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

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

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

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

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

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

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

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

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

การดำเนินการ ปฏิทิน CalendarList
insert สร้างปฏิทินรองใหม่ โดยค่าเริ่มต้น ปฏิทินนี้จะ ลงในรายการปฏิทินของผู้สร้างแล้ว แทรกปฏิทินที่มีอยู่ลงในรายการของผู้ใช้
delete ลบปฏิทินรอง นำปฏิทินออกจากรายการของผู้ใช้
get เรียกข้อมูลข้อมูลเมตาของปฏิทิน เช่น ชื่อ เขตเวลา เรียกข้อมูลเมตาบวกการปรับแต่งที่ผู้ใช้กำหนด เช่น สีหรือลบล้างการช่วยเตือน
patch/update แก้ไขข้อมูลเมตาของปฏิทิน แก้ไขพร็อพเพอร์ตี้ของปฏิทินเฉพาะผู้ใช้

กิจกรรมที่เกิดซ้ำ

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

กิจกรรมจะเรียกว่าเกิดซ้ำหากเกิดซ้ำตามกำหนดเวลาที่กำหนดไว้ กิจกรรมรายการเดียวเป็นกิจกรรมที่เกิดซ้ำและเกิดขึ้นเพียงครั้งเดียว

กฎการเกิดซ้ำ

กำหนดการสำหรับกิจกรรมที่เกิดซ้ำแบ่งออกเป็น 2 ส่วน ดังนี้

  • ฟิลด์เริ่มต้นและสิ้นสุด (ซึ่งจะระบุรายการแรกเสมือนว่า เป็นกิจกรรมเดี่ยวๆ) และ

  • ฟิลด์การเกิดซ้ำ (ซึ่งกำหนดวิธีเกิดซ้ำของกิจกรรมเมื่อเวลาผ่านไป)

ฟิลด์การเกิดซ้ำมีอาร์เรย์ของสตริงที่แสดงค่าหนึ่งหรือหลายรายการ พร็อพเพอร์ตี้ RRULE, RDATE หรือ EXDATE ตามที่กำหนดไว้ใน 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 ทั้งหมด

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

  1. กิจกรรมที่จัดขึ้นตั้งแต่เวลา 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"
    ],
    …
    
  2. กิจกรรมตลอดทั้งวันเริ่มต้นในวันที่ 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)

ตัวอย่างวิธีทำงานกับกิจกรรมที่เกิดซ้ำและอินสแตนซ์ผ่านทาง โปรดดู API ของ Google ปฏิทินได้ที่นี่

เขตเวลา

เขตเวลาจะระบุภูมิภาคที่ใช้เวลามาตรฐานเดียวกัน ใน 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:

ส่วนย่อยของภาพหน้าจอแสดงเขตเวลาในกิจกรรม

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

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