יומנים ואירועים

במדריך הזה מתוארים יומנים, אירועים והקשר ביניהם.

יומנים

יומן הוא אוסף של אירועים קשורים, יחד עם מטא נתונים נוספים כמו סיכום, אזור זמן שמוגדר כברירת מחדל, מיקום וכו'. כל יומן מזוהה באמצעות מזהה שהוא כתובת אימייל. לכל יומן יכולים להיות כמה בעלים.

אירועים

אירוע הוא אובייקט שמשויך לטווח תאריכים או שעות ספציפי. אירועים מזוהים באמצעות מזהה ייחודי. בנוסף לשעת ההתחלה ושעת הסיום, אירועים מכילים נתונים אחרים כמו סיכום, תיאור, מיקום, סטטוס, תזכורות, קבצים מצורפים וכו'.

סוגי אירועים

יומן Google תומך באירועים חד-פעמיים ובאירועים חוזרים:

  • אירוע יחיד מייצג התרחשות ייחודית.
  • אירוע חוזר מגדיר כמה מקרים של אותו אירוע.

אירועים יכולים להיות גם עם שעה או לכל היום:

  • אירוע מתוזמן מתרחש בין שתי נקודות זמן ספציפיות. אירועים מתוזמנים משתמשים בשדות start.dateTime ו-end.dateTime כדי לציין מתי הם מתרחשים.
  • אירוע של יום שלם נמשך יום שלם או סדרה של ימים רצופים. אירועים שנמשכים יום שלם משתמשים בשדות start.date ו-end.date כדי לציין מתי הם מתרחשים. חשוב לזכור שלשדה של אזור הזמן אין משמעות לאירועים שנמשכים כל היום.

מארגנים

לכל אירוע יש מארגן אחד, שהוא היומן שמכיל את העותק הראשי של האירוע. באירועים יכולים להיות גם כמה משתתפים. בדרך כלל, היומן הראשי של המשתמש המוזמן.

בתרשים הבא מוצג הקשר הרעיוני בין יומנים, אירועים ואלמנטים קשורים אחרים:

יומנים ראשיים ויומנים אחרים

יומן ראשי הוא סוג מיוחד של יומן שמשויך לחשבון משתמש יחיד. היומן הזה נוצר באופן אוטומטי לכל חשבון משתמש חדש, והמזהה שלו בדרך כלל זהה לכתובת האימייל הראשית של המשתמש. כל עוד החשבון קיים, אי אפשר למחוק את היומן הראשי שלו או לבטל את הבעלות של המשתמש עליו. עם זאת, עדיין אפשר לשתף אותו עם משתמשים אחרים.

בנוסף ליומן הראשי, אפשר ליצור במפורש כל מספר של יומנים אחרים. אפשר לשנות, למחוק ולשתף את היומנים האלה בין כמה משתמשים.

היומן ורשימת היומנים

אוסף Calendars מייצג את כל היומנים הקיימים. אפשר להשתמש בו כדי ליצור ולמחוק לוחות שנה. אפשר גם לאחזר או להגדיר מאפיינים גלובליים שמשותפים לכל המשתמשים שיש להם גישה ליומן. לדוגמה, הכותרת ואזור הזמן שמוגדר כברירת מחדל ביומן הם מאפיינים גלובליים.

‫CalendarList הוא אוסף של כל הערכים ביומן שמשתמש הוסיף לרשימה שלו (מוצג בחלונית הימנית של ממשק המשתמש באינטרנט). אפשר להשתמש בו כדי להוסיף לרישום של המשתמשים לוחות שנה קיימים או להסיר אותם ממנו. משתמשים בה גם כדי לאחזר ולהגדיר את הערכים של מאפייני יומן ספציפיים למשתמש, כמו תזכורות שמוגדרות כברירת מחדל. דוגמה נוספת היא צבע הטקסט, כי משתמשים שונים יכולים להגדיר צבעים שונים לאותו יומן.

בטבלה הבאה מוצגת השוואה בין המשמעויות של הפעולות בשני האוספים:

פעולה יומנים CalendarList
insert יצירת יומן משני חדש. כברירת מחדל, היומן הזה מתווסף גם לרשימת היומנים של היוצר. הוספה של יומן קיים לרשימה של המשתמש.
delete מחיקת יומן משני. הסרת יומן מהרשימה של המשתמש.
get אחזור מטא-נתונים של היומן, למשל כותרת ואזור זמן. אחזור מטא-נתונים בנוסף להתאמה אישית ספציפית למשתמש, כמו צבע או תזכורות שמוגדרות כברירת מחדל.
patch/update שינוי המטא-נתונים של היומן. שינוי מאפייני יומן ספציפיים למשתמש.

אירועים חוזרים

יש אירועים שמתרחשים כמה פעמים בלוח זמנים קבוע, כמו פגישות שבועיות, ימי הולדת וחגים. בדרך כלל, האירועים החוזרים האלה זהים, מלבד שעות ההתחלה והסיום השונות שלהם.

אירועים נקראים חוזרים אם הם חוזרים לפי לוח זמנים מוגדר. אירועים בודדים הם אירועים לא חוזרים שמתרחשים רק פעם אחת.

כלל לחזרה

התזמון של אירוע חוזר מוגדר בשני חלקים:

  • שדות ההתחלה והסיום שלו (שמגדירים את המופע הראשון, כאילו מדובר באירוע יחיד עצמאי), וגם

  • שדה החזרה שלו (שמגדיר איך האירוע צריך לחזור על עצמו לאורך זמן).

השדה recurrence מכיל מערך של מחרוזות שמייצגות מאפיין אחד או כמה מאפיינים של RRULE, RDATE או EXDATE, כפי שמוגדר ב-RFC 5545.

המאפיין RRULE הוא החשוב ביותר, כי הוא מגדיר כלל רגיל לחזרה על האירוע. הוא מורכב מכמה רכיבים. למשל:

  • ‫FREQ – התדירות שבה האירוע צריך לחזור (למשל DAILY או WEEKLY). חובה.

  • ‫INTERVAL — פועל יחד עם FREQ כדי לציין את תדירות החזרה של האירוע. לדוגמה, FREQ=DAILY;INTERVAL=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, ומפסיק אחרי הפעם החמישית ב-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).

כאן אפשר לראות דוגמאות לאופן השימוש באירועים חוזרים ומופעים דרך 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 או משתמשים בסטייה של אפס 2017-01-25T14:00:00+0000.

הייצוג הפנימי של שעת האירוע זהה בכל המקרים האלה, אבל הגדרת השדה timeZone מצרפת אזור זמן לאירוע, בדיוק כמו כשמגדירים אזור זמן לאירוע באמצעות ממשק המשתמש של היומן:

קטע מצילום מסך שבו מוצג אזור הזמן של אירוע

אזור הזמן של אירוע חוזר

באירועים חוזרים, תמיד צריך לציין אזור זמן אחד. הוא נדרש כדי להרחיב את המופעים החוזרים של האירוע.