Events: insert

הערה: נדרשת הרשאה.

ייווצר אירוע. רוצים לנסות?

בקשה

בקשת HTTP

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events

פרמטרים

שם הפרמטר	ערך	תיאור
פרמטרים של נתיב
calendarId	string	מזהה ביומן. כדי לאחזר את מזהי היומנים, קוראים לשיטה calendarList.list. כדי לגשת ליומן הראשי של המשתמש שמחובר כרגע, משתמשים במילות המפתח primary.
פרמטרים אופציונליים של שאילתות
conferenceDataVersion	integer	מספר הגרסה של נתוני הכנס שנתמכים בלקוח ה-API. בגרסה 0 לא מוגדרת תמיכה בנתוני כנסים, והמערכת מתעלמת מנתוני כנסים בגוף האירוע. בגרסה 1 יש תמיכה בהעתקה של ConferenceData וגם ביצירת שיחות ועידה חדשות באמצעות השדה createRequest של conferenceData. ערך ברירת המחדל הוא 0. הערכים הקבילים הם 0 עד 1, כולל.
maxAttendees	integer	המספר המקסימלי של משתתפים שאפשר לכלול בתשובה. אם יש יותר ממספר הנוכחים שצוין, רק המשתתף יוחזר. אופציונלי.
sendNotifications	boolean	הוצא משימוש. יש להשתמש במקום זאת ב-sendUpdates. האם לשלוח התראות על יצירת האירוע החדש. חשוב לדעת שחלק מהאימיילים עדיין עשויים להישלח גם אם תגדירו את הערך ל-false. ברירת המחדל היא false.
sendUpdates	string	האם לשלוח התראות על יצירת האירוע החדש. חשוב לזכור שחלק מהאימיילים עדיין עשויים להישלח. ברירת המחדל היא false. הערכים הקבילים הם: 'all': ההתראות נשלחות לכל המשתתפים. 'externalOnly': ההתראות נשלחות רק למשתתפים שלא משתמשים ביומן Google. 'none': לא נשלחות התראות. אזהרה: לשימוש בערך none יכולות להיות השפעות שליליות משמעותיות, כולל אירועים שלא מסתנכרנים עם יומנים חיצוניים או אירועים שאבדו לגמרי אצל חלק מהמשתמשים. למשימות של העברת יומנים, מומלץ להשתמש במקום זאת בשיטה events.import.
supportsAttachments	boolean	האם לקוח ה-API שמבצע את הפעולה תומך בקבצים מצורפים לאירועים. אופציונלי. ברירת המחדל היא False.

אישור

הבקשה הזו דורשת הרשאה עם לפחות אחד מההיקפים הבאים:

היקף
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.owned

מידע נוסף זמין בדף אימות והרשאה.

גוף הבקשה

בגוף הבקשה, מספקים משאב אירועים עם המאפיינים הבאים:

שם הנכס	ערך	תיאור	הערות
מאפיינים נדרשים
end	nested object	שעת הסיום (הבלעדית) של האירוע. באירוע חוזר, זוהי שעת הסיום של המופע הראשון.
start	nested object	שעת ההתחלה (כולל) של האירוע. באירוע חוזר, זוהי שעת ההתחלה של המופע הראשון.
מאפיינים אופציונליים
anyoneCanAddSelf	boolean	אם כל אחד יכול להזמין את עצמו לאירוע (תכונה לא מומלצת). אופציונלי. ברירת המחדל היא False.	לכתיבה
attachments[].fileUrl	string	כתובת URL של הקובץ המצורף. כדי לצרף קבצים מ-Google Drive, צריך להשתמש באותו פורמט כמו במאפיין alternateLink של המשאב Files ב-Drive API. חובה כשמוסיפים קובץ מצורף.	לכתיבה
attendees[]	list	המשתתפים באירוע. במדריך אירועים עם משתתפים מוסבר איך לתזמן אירועים עם משתמשים אחרים ביומן. חשבונות שירות צריכים להשתמש בהענקת גישה ברמת הדומיין כדי לאכלס את רשימת הנוכחים.	לכתיבה
attendees[].additionalGuests	integer	מספר האורחים הנוספים. אופציונלי. ערך ברירת המחדל הוא 0.	לכתיבה
attendees[].comment	string	התגובה של המשתתף. אופציונלי.	לכתיבה
attendees[].displayName	string	השם של המשתתף, אם יש. אופציונלי.	לכתיבה
attendees[].email	string	כתובת האימייל של המשתתף, אם יש כזו. השדה הזה חייב להופיע כשמוסיפים משתתף. היא חייבת להיות כתובת אימייל תקינה בהתאם ל-RFC5322. חובה להוסיף את השם כשמוסיפים משתתף.	לכתיבה
attendees[].optional	boolean	אם מדובר בנוכח אופציונלי. אופציונלי. ברירת המחדל היא False.	לכתיבה
attendees[].resource	boolean	אם המשתתף הוא משאב. אפשר להגדיר את האפשרות הזו רק כשהמשתתף מתווסף לאירוע בפעם הראשונה. המערכת מתעלמת משינויים נוספים. אופציונלי. ברירת המחדל היא False.	לכתיבה
attendees[].responseStatus	string	סטטוס התשובה של המשתתף. הערכים האפשריים הם: 'needsAction' – המשתתף לא הגיב להזמנה (מומלץ לאירועים חדשים). 'declined' – המשתתף דחה את ההזמנה. 'tentative' – המשתתף או המשתתפת אישרו את ההזמנה באופן זמני. 'accepted' – המשתתף או המשתתפת אישרו את ההזמנה. אזהרה: אם מוסיפים אירוע עם הערכים declined, ‏ tentative או accepted, ייתכן שהתשובה של משתתפים שהגדרתם להם את ההגדרה 'הוספת הזמנות ליומן שלי' ל'רק אם עניתי להזמנה באימייל' או ל'רק אם השולח מוכר לי' תתאפס ל-needsAction והם לא יראו את האירוע ביומן, אלא אם ישנו את התשובה באימייל עם ההזמנה לאירוע. בנוסף, אם הוזמנו יותר מ-200 משתתפים לאירוע, סטטוס התשובה לא מועבר אליהם.	לכתיבה
birthdayProperties	nested object	נתונים של יום הולדת או אירוע מיוחד. משמש אם הערך של eventType הוא "birthday". לא ניתן לשינוי.	לכתיבה
birthdayProperties.type	string	סוג יום ההולדת או האירוע המיוחד. הערכים האפשריים הם: "anniversary" – יום הולדת של אירוע אחר. תמיד יש לו contact. "birthday" – אירוע יום הולדת. זהו ערך ברירת המחדל. "custom" – תאריך מיוחד שהתווית שלו מצוינה בשדה customTypeName. תמיד יש לו contact. "other" – תאריך מיוחד שלא שייך לאף אחת מהקטגוריות האחרות, ואין לו תווית מותאמת אישית. תמיד יש לו contact. "self" – יום ההולדת של הבעלים של היומן. לא יכול להיות contact. ב-Calendar API יש תמיכה רק ביצירת אירועים מסוג "birthday". לא ניתן לשנות את הסוג אחרי שיוצרים את האירוע.	לכתיבה
colorId	string	הצבע של האירוע. זהו מזהה שמתייחס לרשומה בקטע event של הגדרת הצבעים (ראו נקודת הקצה colors). אופציונלי.	לכתיבה
conferenceData	nested object	המידע שקשור לוועידה, כמו פרטי ועידה ב-Google Meet. כדי ליצור פרטים חדשים של כנס, משתמשים בשדה createRequest. כדי לשמור את השינויים, חשוב להגדיר את פרמטר הבקשה conferenceDataVersion לערך 1 בכל הבקשות לשינוי אירועים.	לכתיבה
description	string	תיאור האירוע. יכול להכיל HTML. אופציונלי.	לכתיבה
end.date	date	התאריך, בפורמט 'yyyy-mm-dd', אם מדובר באירוע שנמשך כל היום.	לכתיבה
end.dateTime	datetime	השעה, כערך משולב של תאריך ושעה (בפורמט RFC3339). חובה לציין את הפרש השעות באזור הזמן, אלא אם צוין אזור זמן באופן מפורש ב-timeZone.	לכתיבה
end.timeZone	string	אזור הזמן שבו מצוין השעה. (בפורמט של שם במסד הנתונים IANA Time Zone Database, למשל 'אירופה/ציריך'). בשדות של אירועים חוזרים, השדה הזה נדרש ומציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית להתחלה או לסיום של האירוע.	לכתיבה
eventType	string	סוג ספציפי של האירוע. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את האירוע. הערכים האפשריים הם: 'birthday' – אירוע מיוחד שנמשך יום שלם וחוזר מדי שנה. default – אירוע רגיל או אירוע ללא ציון נוסף. 'focusTime' – אירוע 'זמן לעצמי'. 'fromGmail' – אירוע מ-Gmail. אי אפשר ליצור אירוע מהסוג הזה. 'outOfOffice' – אירוע מסוג 'לא בעבודה'. 'workingLocation' – אירוע של מיקום עבודה.	לכתיבה
extendedProperties.private	object	מאפיינים שיהיו פרטיים להעתק של האירוע שמופיע ביומן הזה.	לכתיבה
extendedProperties.shared	object	מאפיינים ששותפו בין עותקים של האירוע ביומני המשתתפים האחרים.	לכתיבה
focusTimeProperties	nested object	נתוני אירועים מסוג 'זמן לעצמי'. משמש אם הערך של eventType הוא focusTime.	לכתיבה
gadget.display	string	מצב התצוגה של הכלי. הוצא משימוש. הערכים האפשריים הם: 'icon' – הכלי יופיע לצד שם האירוע בתצוגת היומן. 'chip' – הכלי יוצג כשלוחצים על האירוע.	לכתיבה
gadget.height	integer	הגובה של הווידג'ט בפיקסלים. הגובה חייב להיות מספר שלם גדול מ-0. אופציונלי. הוצא משימוש.	לכתיבה
gadget.iconLink	string	כתובת ה-URL של הסמל של הגאדג'ט. סכימת כתובת ה-URL חייבת להיות HTTPS. הוצא משימוש.	לכתיבה
gadget.link	string	כתובת ה-URL של הכלי. סכימת כתובת ה-URL חייבת להיות HTTPS. הוצא משימוש.	לכתיבה
gadget.preferences	object	העדפות.	לכתיבה
gadget.title	string	שם הגאדג'ט. הוצא משימוש.	לכתיבה
gadget.type	string	סוג הגאדג'ט. הוצא משימוש.	לכתיבה
gadget.width	integer	רוחב הווידג'ט בפיקסלים. הרוחב חייב להיות מספר שלם גדול מ-0. אופציונלי. הוצא משימוש.	לכתיבה
guestsCanInviteOthers	boolean	אם משתתפים אחרים, מלבד המארגן, יכולים להזמין אנשים אחרים לאירוע. אופציונלי. ברירת המחדל היא True.	לכתיבה
guestsCanModify	boolean	אם משתתפים אחרים מלבד המארגן יכולים לשנות את האירוע. אופציונלי. ברירת המחדל היא False.	לכתיבה
guestsCanSeeOtherGuests	boolean	אם משתתפים אחרים מלבד המארגן יוכלו לראות מי המשתתפים באירוע. אופציונלי. ברירת המחדל היא True.	לכתיבה
id	string	מזהה אטום של האירוע. כשיוצרים אירועים חד-פעמיים או חוזרים, אפשר לציין את המזהים שלהם. המזהים שסופקו חייבים לעמוד בכללים הבאים: התווים שמותר להשתמש בהם במזהה הם אלה שמשמשים בקידוד base32hex, כלומר אותיות קטנות a-v ומספרים 0-9. אפשר לעיין בקטע 3.1.2 במסמך RFC2938 אורך המזהה צריך להיות בין 5 ל-1,024 תווים המזהה חייב להיות ייחודי לכל לוח שנה בגלל אופי ההפצה הגלובלי של המערכת, אנחנו לא יכולים להבטיח שיזוהו התנגשויות בין מזהים בזמן יצירת האירוע. כדי לצמצם את הסיכון להתנגשות, מומלץ להשתמש באלגוריתם UUID מקובל, כמו זה שמתואר ב-RFC4122. אם לא מציינים מזהה, השרת ייצור אותו באופן אוטומטי. חשוב לדעת: השדות icalUID ו-id הם לא זהים, ויש לציין רק אחד מהם בזמן יצירת האירוע. אחד ההבדלים בסמנטיקה שלהם הוא שבאירועים חוזרים, לכל המופעים של אירוע אחד יש ערכי id שונים, אבל לכל המופעים יש את אותם ערכי icalUID.	לכתיבה
location	string	המיקום הגיאוגרפי של האירוע כטקסט חופשי. אופציונלי.	לכתיבה
originalStartTime.date	date	התאריך, בפורמט 'yyyy-mm-dd', אם מדובר באירוע שנמשך כל היום.	לכתיבה
originalStartTime.dateTime	datetime	השעה, כערך משולב של תאריך ושעה (בפורמט RFC3339). חובה לציין את הפרש השעות באזור הזמן, אלא אם צוין אזור זמן באופן מפורש ב-timeZone.	לכתיבה
originalStartTime.timeZone	string	אזור הזמן שבו מצוין השעה. (בפורמט של שם במסד הנתונים IANA Time Zone Database, למשל 'אירופה/ציריך'). בשדות של אירועים חוזרים, השדה הזה נדרש ומציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית להתחלה או לסיום של האירוע.	לכתיבה
outOfOfficeProperties	nested object	נתונים של אירועים מסוג 'לא בעבודה'. משמש אם הערך של eventType הוא outOfOffice.	לכתיבה
recurrence[]	list	רשימה של שורות RRULE, ‏ EXRULE, ‏ RDATE ו-EXDATE לאירוע חוזר, כפי שמפורט ב-RFC5545. חשוב לזכור שאין להשתמש בשורות DTSTART ו-DTEND בשדה הזה. שעות ההתחלה והסיום של האירוע מצוינות בשדות start ו-end. השדה הזה לא מופיע באירועים בודדים או במופעים של אירועים חוזרים.	לכתיבה
reminders.overrides[]	list	אם לאירוע לא מוגדרות תזכורות ברירת המחדל, יופיעו כאן התזכורות הספציפיות לאירוע. אם לא הוגדרו תזכורות, יופיע הכיתוב 'לא הוגדרו תזכורות'. המספר המקסימלי של תזכורות לשינוי ברירת המחדל הוא 5.	לכתיבה
reminders.overrides[].method	string	השיטה שבה נעשה שימוש בתזכורת הזו. הערכים האפשריים הם: 'email' – התזכורות נשלחות באימייל. 'popup' – התזכורות נשלחות דרך חלון קופץ בממשק המשתמש. נדרש כשמוסיפים תזכורת.	לכתיבה
reminders.overrides[].minutes	integer	מספר הדקות לפני תחילת האירוע שבהן התזכורת אמורה להופיע. הערכים התקפים הם בין 0 ל-40320 (4 שבועות בדקות). נדרש כשמוסיפים תזכורת.	לכתיבה
reminders.useDefault	boolean	אם תזכורות ברירת המחדל של היומן חלות על האירוע.	לכתיבה
sequence	integer	מספר סידורי לפי iCalendar.	לכתיבה
source.title	string	כותרת המקור. לדוגמה, כותרת של דף אינטרנט או נושא של אימייל.	לכתיבה
source.url	string	כתובת ה-URL של המקור שמפנה למשאב. סכימת כתובת ה-URL חייבת להיות HTTP או HTTPS.	לכתיבה
start.date	date	התאריך, בפורמט 'yyyy-mm-dd', אם מדובר באירוע שנמשך כל היום.	לכתיבה
start.dateTime	datetime	השעה, כערך משולב של תאריך ושעה (בפורמט RFC3339). חובה לציין את הפרש השעות באזור הזמן, אלא אם צוין אזור זמן באופן מפורש ב-timeZone.	לכתיבה
start.timeZone	string	אזור הזמן שבו מצוין השעה. (בפורמט של שם במסד הנתונים IANA Time Zone Database, למשל 'אירופה/ציריך'). בשדות של אירועים חוזרים, השדה הזה נדרש ומציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית להתחלה או לסיום של האירוע.	לכתיבה
status	string	הסטטוס של האירוע. אופציונלי. הערכים האפשריים הם: 'confirmed' – האירוע אושר. זהו סטטוס ברירת המחדל. 'tentative' – האירוע אושר באופן לא סופי. 'cancelled' – האירוע בוטל (נמחק). שיטת list מחזירה אירועים שבוטלו רק בסנכרון מצטבר (כשמציינים את הערכים syncToken או updatedMin) או אם הדגל showDeleted מוגדר לערך true. הם תמיד מוחזרים על ידי השיטה get. הסטטוס 'מבוטל' מייצג שני מצבים שונים, בהתאם לסוג האירוע: אם ביטלתם חריגים של אירוע חוזר שלא בוטל, המשמעות היא שהאירוע הזה לא אמור להופיע יותר ביומן של המשתמש. הלקוחות צריכים לאחסן את האירועים האלה למשך כל תקופת החיים של האירוע החוזר הראשי. מובטח שרק בשדות id, ‏ recurringEventId ו-originalStartTime של החרגות שבוטלו יהיו ערכים מאוכלסים. שאר השדות יכולים להיות ריקים. כל שאר האירועים שבוטלו מייצגים אירועים שנמחקו. לקוחות צריכים להסיר את העותקים שלהם שסונכרנו באופן מקומי. אירועים שבוטלו ייעלמו בסופו של דבר, לכן אל תסמכו על כך שהם יהיו זמינים ללא הגבלת זמן. רק באירועים שנמחקו מובטח שהשדה id מאוכלס. ביומן של המארגן, פרטי האירועים שבוטלו (סיכום, מיקום וכו') עדיין גלויים, כדי שאפשר יהיה לשחזר אותם (לבטל את המחיקה שלהם). באופן דומה, האירועים שהמשתמש הוזמן אליהם והסיר אותם באופן ידני ימשיכו לספק פרטים. עם זאת, בקשות לסנכרון מצטבר עם הערך false של showDeleted לא יחזירו את הפרטים האלה. אם מארגן האירוע ישתנה (למשל באמצעות הפעולה move) והמארגן המקורי לא נכלל ברשימת הנוכחים, יישאר אירוע מבוטל שבו רק השדה id יהיה מאוכלס.	לכתיבה
summary	string	שם האירוע.	לכתיבה
transparency	string	אם האירוע חוסם זמן ביומן. אופציונלי. הערכים האפשריים הם: 'opaque' – ערך ברירת המחדל. האירוע חוסם זמן ביומן. זהו מצב מקביל להגדרה של הצגת המצב שלי כעסוק בממשק המשתמש של יומן Google. 'transparent' – האירוע לא חוסם זמן ביומן. זהו מצב מקביל להגדרה הצגת הסטטוס שלי בתור זמין בממשק המשתמש של יומן Google.	לכתיבה
visibility	string	מי יכול לראות את האירוע. אופציונלי. הערכים האפשריים הם: 'default' – המערכת משתמשת בהרשאות הגישה שמוגדרות כברירת מחדל לאירועים ביומן. זהו ערך ברירת המחדל. 'public' – האירוע גלוי לכולם ופרטי האירוע גלויים לכל הקוראים של היומן. 'private' – האירוע פרטי ורק המשתתפים בו יכולים לראות את פרטי האירוע. 'confidential' – האירוע הוא פרטי. הערך הזה מוצג מטעמי תאימות.	לכתיבה
workingLocationProperties	nested object	נתוני אירועים של מיקום העבודה.	לכתיבה
workingLocationProperties.customLocation	object	אם השדה הזה מופיע, המשמעות היא שהמשתמש עובד ממיקום מותאם אישית.	לכתיבה
workingLocationProperties.customLocation.label	string	תווית נוספת אופציונלית למידע נוסף.	לכתיבה
workingLocationProperties.homeOffice	any value	אם השדה הזה קיים, המשמעות היא שהמשתמש עובד מהבית.	לכתיבה
workingLocationProperties.officeLocation	object	אם השדה הזה מופיע, המשמעות היא שהמשתמש עובד מהמשרד.	לכתיבה
workingLocationProperties.officeLocation.buildingId	string	מזהה אופציונלי של בניין. המזהה הזה צריך להפנות למזהה של בניין במסד הנתונים של המשאבים של הארגון.	לכתיבה
workingLocationProperties.officeLocation.deskId	string	מזהה שולחן אופציונלי.	לכתיבה
workingLocationProperties.officeLocation.floorId	string	מזהה קומה אופציונלי.	לכתיבה
workingLocationProperties.officeLocation.floorSectionId	string	מזהה אופציונלי של קטע בקומה.	לכתיבה
workingLocationProperties.officeLocation.label	string	שם המשרד שמוצג ביומן Google בדפדפן ובאפליקציות לנייד. מומלץ להפנות לשם של המבנה במסד הנתונים של המשאבים של הארגון.	לכתיבה
workingLocationProperties.type	string	סוג מיקום העבודה. הערכים האפשריים הם: 'homeOffice' – המשתמש עובד מהבית. 'officeLocation' – המשתמש עובד ממשרד. 'customLocation' – המשתמש עובד ממיקום מותאם אישית. כל הפרטים מצוינים בשדה משנה של השם שצוין, אבל יכול להיות שהשדה הזה יהיה חסר אם הוא ריק. המערכת מתעלמת משדות אחרים. חובה להוסיף את המאפיין הזה כשמוסיפים נכסים של מיקומי עבודה.	לכתיבה

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-method מחזיר משאב אירועים בגוף התגובה.

נסה בעצמך!

אפשר להשתמש בכלי הבדיקה של ממשקי ה-API שבהמשך כדי להפעיל את השיטה הזו על נתונים פעילים ולראות את התגובה.