Events: import

ייבוא אירוע. הפעולה הזו משמשת להוספת עותק פרטי של אירוע קיים ליומן. אפשר לייבא רק אירועים עם eventType של default.

התנהגות שיצאה משימוש: אם מייבאים אירוע שהוא לא מסוג default, הסוג שלו ישתנה ל-default וכל המאפיינים הספציפיים לסוג האירוע יוסרו.

רוצים לנסות?

בקשה

בקשת HTTP

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

פרמטרים

שם הפרמטר ערך תיאור
פרמטרים של נתיבים
calendarId string מזהה היומן. כדי לאחזר מזהי יומנים, קוראים לשיטה calendarList.list. אם רוצים לגשת ליומן הראשי של המשתמש שמחובר כרגע, משתמשים במילת המפתח primary.
פרמטרים אופציונליים של שאילתה
conferenceDataVersion integer מספר הגרסה של נתוני הוועידה שנתמכים על ידי לקוח ה-API. בגרסה 0 אין תמיכה בנתוני שיחות ועידה, והיא מתעלמת מנתוני שיחות ועידה בגוף האירוע. גרסה 1 מאפשרת תמיכה בהעתקה של ConferenceData וגם ביצירה של שיחות ועידה חדשות באמצעות השדה createRequest של conferenceData. ערך ברירת המחדל הוא 0. הערכים הקבילים הם 0 עד 1, כולל.
eventLabelVersion integer מספר הגרסה של התכונה 'תווית אירוע' שנתמכת על ידי לקוח ה-API. בגרסה 0 אין תמיכה בתוויות אירועים, והיא מעבדת את השדה colorId לניהול צבעים. גרסה 1 מאפשרת תמיכה בתוויות אירועים ומעבדת את eventLabelId בגוף האירוע. במקרה כזה, המערכת מתעלמת מהשדה colorId. ערך ברירת המחדל הוא 0. הערכים הקבילים הם 0 עד 1, כולל.
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

למידע נוסף, ראו את הדף אימות והרשאה.

גוף הבקשה

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

שם הנכס ערך תיאור הערות
מאפייני חובה
end nested object שעת הסיום (לא כולל) של האירוע. באירוע חוזר, זו שעת הסיום של המופע הראשון.
iCalUID string מזהה ייחודי של האירוע כפי שהוגדר ב-RFC5545. הוא משמש לזיהוי ייחודי של אירועים במערכות יומנים שונות, וחובה לספק אותו כשמייבאים אירועים באמצעות השיטה import.

שימו לב שהתגים iCalUID ו-id לא זהים, וצריך לספק רק אחד מהם בזמן יצירת האירוע. הבדל אחד בסמנטיקה הוא שבאירועים חוזרים, לכל המופעים של אירוע אחד יש ערכי id שונים, אבל לכולם יש את אותו ערך iCalUID. כדי לאחזר אירוע באמצעות iCalUID, קוראים לשיטה events.list באמצעות הפרמטר iCalUID. כדי לאחזר אירוע באמצעות ה-id שלו, מפעילים את השיטה events.get.
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 – המשתתף אישר את ההזמנה.
 ניתן לכתיבה
attendeesOmitted boolean האם יכול להיות שמשתתפים לא נכללו בייצוג של האירוע. יכול להיות שהסיבה לכך היא הגבלה שצוינה בפרמטר השאילתה maxAttendee. כשמעדכנים אירוע, אפשר להשתמש בפרמטר הזה כדי לעדכן רק את התשובה של המשתתף. אופציונלי. ברירת המחדל היא False. ניתן לכתיבה
colorId string הצבע של האירוע. זהו מזהה שמתייחס לרשומה בקטע event בהגדרת הצבעים (ראו נקודת הקצה של הצבעים). אופציונלי. ניתן לכתיבה
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, לדוגמה, 'Europe/Zurich'). באירועים חוזרים, חובה למלא את השדה הזה ולציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית לשעת ההתחלה או הסיום של האירוע. ניתן לכתיבה
eventLabelId string המזהה של תווית האירוע שהוקצתה לאירוע. אופציונלי. המזהה הזה מתייחס למזהה של רשומה במאפיין labelProperties.eventLabels של היומן (ראו את נקודת הקצה Calendars.get).

הנכס הזה מחליף את הנכס colorId שמבוסס על אינדקס. כדי להגדיר או לשנות את המאפיין הזה, צריך לציין את הערך eventLabelVersion=1 בפרמטרים של השיטות insert,‏ import,‏ update ו-patch.

אם מגדירים מחרוזת ריקה או לא מגדירים את השדה הזה בכלל, התווית הקיימת תוסר מהאירוע.

 ניתן לכתיבה
extendedProperties.private object מאפיינים שפרטיים לעותק של האירוע שמופיע ביומן הזה. ניתן לכתיבה
extendedProperties.shared object מאפיינים שמשותפים בין עותקים של האירוע ביומנים של משתתפים אחרים. ניתן לכתיבה
focusTimeProperties nested object נתוני אירוע של 'זמן לעצמי'. המאפיין הזה משמש אם הערך של eventType הוא focusTime. ניתן לכתיבה
gadget.display string מצב התצוגה של הגאדג'ט. הוצא משימוש. הערכים האפשריים הם:
  • ‫"icon" – הגאדג'ט מוצג לצד שם האירוע בתצוגת היומן.
  • ‫chip – הגאדג'ט מוצג כשלוחצים על האירוע.
 ניתן לכתיבה
gadget.height integer גובה הגאדג'ט בפיקסלים. הגובה חייב להיות מספר שלם גדול מ-0. אופציונלי. הוצא משימוש. ניתן לכתיבה
gadget.preferences object העדפות. ניתן לכתיבה
gadget.title string השם של הגאדג'ט. הוצא משימוש. ניתן לכתיבה
gadget.type string סוג הגאדג'ט. הוצא משימוש. ניתן לכתיבה
gadget.width integer הרוחב של הגאדג'ט בפיקסלים. הרוחב חייב להיות מספר שלם גדול מ-0. אופציונלי. הוצא משימוש. ניתן לכתיבה
guestsCanInviteOthers boolean האם משתתפים אחרים מלבד המארגן יכולים להזמין אחרים לאירוע. אופציונלי. ברירת המחדל היא True. ניתן לכתיבה
guestsCanModify boolean האם משתתפים אחרים מלבד המארגן יכולים לשנות את האירוע. אופציונלי. ברירת המחדל היא False. ניתן לכתיבה
guestsCanSeeOtherGuests boolean האם משתתפים שאינם המארגן יכולים לראות את רשימת המשתתפים באירוע. אופציונלי. ברירת המחדל היא True. ניתן לכתיבה
location string המיקום הגיאוגרפי של האירוע כטקסט חופשי. אופציונלי. ניתן לכתיבה
organizer object מארגן האירוע. אם המארגן הוא גם משתתף, זה יצוין ברשומה נפרדת ב-attendees כשהשדה organizer מוגדר כ-True. כדי לשנות את המארגן, משתמשים בפעולה העברה. קריאה בלבד, למעט כשמייבאים אירוע. ניתן לכתיבה
organizer.displayName string השם של מארגן הפגישה, אם הוא זמין. ניתן לכתיבה
organizer.email string כתובת האימייל של מארגן הפגישה, אם היא זמינה. היא חייבת להיות כתובת אימייל תקינה לפי RFC5322. ניתן לכתיבה
originalStartTime.date date התאריך בפורמט yyyy-mm-dd, אם מדובר באירוע של יום שלם. ניתן לכתיבה
originalStartTime.dateTime datetime השעה, כערך משולב של תאריך ושעה (בפורמט RFC3339). חובה לציין את ההפרש מאזור הזמן, אלא אם מציינים אזור זמן באופן מפורש ב-timeZone. ניתן לכתיבה
originalStartTime.timeZone string אזור הזמן שבו מצוין הזמן. (בפורמט של שם במסד הנתונים IANA Time Zone Database, לדוגמה, 'Europe/Zurich'). באירועים חוזרים, חובה למלא את השדה הזה ולציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית לשעת ההתחלה או הסיום של האירוע. ניתן לכתיבה
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, לדוגמה, 'Europe/Zurich'). באירועים חוזרים, חובה למלא את השדה הזה ולציין את אזור הזמן שבו התדירות מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית לשעת ההתחלה או הסיום של האירוע. ניתן לכתיבה
status string הסטטוס של האירוע. אופציונלי. הערכים האפשריים הם:
  • ‫confirmed – האירוע אושר. זהו סטטוס ברירת המחדל.
  • ‫tentative – האירוע אושר באופן זמני.
  • ‫"cancelled" – האירוע בוטל (נמחק). השיטה list מחזירה אירועים שבוטלו רק בסנכרון מצטבר (כשמציינים את syncToken או updatedMin) או אם הדגל showDeleted מוגדר לערך true. השיטה get תמיד מחזירה אותם.

    הסטטוס 'בוטל' מייצג שני מצבים שונים, בהתאם לסוג האירוע:

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

      מובטח שרק בשדות id, recurringEventId ו-originalStartTime של חריגים שבוטלו יופיעו ערכים. יכול להיות ששאר השדות יהיו ריקים.

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

      רק השדה id מובטח להיות מאוכלס באירועים שנמחקו.

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

    אם המארגן של אירוע משתנה (לדוגמה, באמצעות הפעולה העברה) והמארגן המקורי לא נמצא ברשימת המשתתפים, יישאר אירוע מבוטל שרק השדה id שלו יאוכלס בוודאות.

ניתן לכתיבה
summary string שם האירוע. ניתן לכתיבה
transparency string האם האירוע חוסם זמן ביומן. אופציונלי. הערכים האפשריים הם:
  • ‫opaque – ערך ברירת המחדל. האירוע חוסם זמן ביומן. ההגדרה הזו מקבילה להגדרה של הצגת המצב שלי כעסוק/ה בממשק המשתמש של יומן Google.
  • ‫"transparent" – האירוע לא חוסם זמן ביומן. ההגדרה הזו מקבילה להגדרה של הסטטוס שלי לזמין/ה בממשק המשתמש של יומן Google.
 ניתן לכתיבה
visibility string הרשאות הגישה לאירוע. אופציונלי. הערכים האפשריים הם:
  • ‫default – נעשה שימוש בברירת המחדל של הרשאות הגישה לאירועים ביומן. זהו ערך ברירת המחדל.
  • ‫"public" – האירוע גלוי לכולם וכל מי שיכול לקרוא את היומן יכול לראות את פרטי האירוע.
  • ‫private – האירוע פרטי ורק המשתתפים יכולים לראות את הפרטים שלו.
  • ‫confidential – האירוע הוא פרטי. הערך הזה מסופק מסיבות של תאימות.
 ניתן לכתיבה

תשובה

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

רוצה לנסות?

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