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

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

יומנים

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

אירועים

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

סוגי אירועים

יומן 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).

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

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

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