דף זה תורגם על ידי Cloud Translation API.

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

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

יומנים

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

אירועים

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

סוגי אירועים

ביומן 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 או ב-UNTIL כדי לציין את סיום החזרה של האירוע. אין להשתמש בשניהם באותו כלל.
UNTIL – התאריך או התאריך-שעה עד שאליו צריך לחזור על האירוע (כולל).
BYDAY – ימי השבוע שבהם האירוע צריך לחזור על עצמו (SU,‏ MO,‏ TU וכו'). רכיבים דומים אחרים כוללים את BYMONTH,‏ BYYEARDAY ו-BYHOUR.

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

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

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

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

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

אירוע שמתרחש מ-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"
],
…

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

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

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

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

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

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