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

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

יומנים

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

אירועים

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

סוגי אירועים

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

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

אירועים יכולים להיות גם מתוזמנים או כל היום:

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

מארגנים

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

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

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

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

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

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

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

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

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

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

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

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

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

כלל לחזרה

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

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

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

שדה החזרה מכיל מערך מחרוזות שמייצגות מאפיין אחד או יותר של 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.

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

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

אזור הזמן של היומן נקרא גם אזור הזמן שמוגדר כברירת מחדל בגלל ההשלכות שלו על תוצאות השאילתה. אזור הזמן הקלנדרי משפיע על האופן שבו ערכי הזמן מפורשים או מוצגים ב-methods events.get(), events.list() ו-events.instances().

המרת אזור הזמן של תוצאת השאילתה
התוצאות של השיטות get(), list() ו-instances() מוחזרות באזור הזמן שציינתם בפרמטר timeZone. אם משמיטים את הפרמטר הזה, ב-methods של כל ה-methods נעשה שימוש באזור הזמן היומן כברירת מחדל.
התאמה של אירועים של יום שלם לשאילתות לפי זמן
השיטות 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, המערכת מצרפת אזור זמן לאירוע, בדיוק כמו שמגדירים אזור זמן של אירוע באמצעות ממשק המשתמש של היומן:

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

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

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