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

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

יומנים

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

אירועים

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

סוגי אירועים

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

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

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

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

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

מארגנים

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

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

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

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

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

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

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

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

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

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

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

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

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

כלל לחזרה

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

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

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

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

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

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

• INTERVAL — פועלת יחד עם FREQ כדי לציין באיזו תדירות צריך לחזור על האירוע. לדוגמה: המשמעות של FREQ=DAILY;INTERVAL=2 היא פעם ביומיים.

• COUNT – מספר הפעמים שהאירוע הזה צריך לחזור.

  אפשר להשתמש ב-COUNT או ב-Sheets כדי לציין את סוף החזרה של האירוע. אין להשתמש בשתיהן באותו כלל.

• UNTIL – התאריך או השעה שעד אליו צריך לחזור על האירוע (כולל).

• BYDAY — הימים בשבוע שבהם צריך לחזור על האירוע (SU, MO, TU וכו'). רכיבים דומים אחרים כוללים את BYMONTH, BYYEARDAY ו-BYHOUR.

המאפיין RDATE מציין תאריכים או שעות נוספים שבהם מתרחשים אירועים. לדוגמה, RDATE;VALUE=DATE:19970101,19970120. אפשר להשתמש בו כדי להוסיף מופעים נוספים שלא נכללים ב-RRULE.

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

אפשר להגדיר אזור זמן ב-EXDATE וב-RDATE, וצריך להגדיר אותו כתאריכים (ולא כתאריכי תאריכים) באירועים של יום שלם.

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

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

1. אירוע שמתרחש מ-06:00 עד 07: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).

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

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

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

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

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