המדריך הזה מתאר יומנים, אירועים ואת הקשר שלהם זה לזה.
יומנים
יומן הוא אוסף של אירועים קשורים, יחד עם מטא-נתונים נוספים כמו סיכום, ברירת מחדל של אזור הזמן, מיקום וכו'. כל יומן מזוהה באמצעות מזהה, שהוא כתובת אימייל. ליומנים יכולים להיות מספר בעלים.
אירועים
אירוע הוא אובייקט שמשויך לטווח תאריכים או שעות ספציפיים. אירועים מזוהים באמצעות מזהה ייחודי. מלבד התחלה תאריך הסיום, האירועים מכילים נתונים אחרים כמו סיכום, תיאור, מיקום, סטטוס, תזכורות, קבצים מצורפים וכו'
סוגי אירועים
יומן 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
הכללים.
ריכזנו כאן כמה דוגמאות של אירועים חוזרים:
אירוע שמתרחש מ-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
).
דוגמאות לאופן שבו אפשר לעבוד עם אירועים ואירועים חוזרים באמצעות כאן אפשר למצוא את ממשק ה-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:
אזור הזמן של האירוע החוזר
באירועים חוזרים, תמיד צריך לציין אזור זמן אחד. האירוע הזה נדרש כדי להגדיל את מספר החזרות של האירוע.