דף זה תורגם על ידי 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 מציין פעם ב-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:

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

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