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

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

יומנים

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

אירועים

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

סוגי אירועים

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

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

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

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

מארגנים

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

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

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

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

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

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

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

‫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 בספטמבר 2015:

   ...
   "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 מצרפת לאירוע אזור זמן, בדיוק כמו כשמגדירים אזור זמן לאירוע באמצעות ממשק המשתמש של היומן:

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

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