Events: update

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

בקשה

בקשת HTTP

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

פרמטרים

שם הפרמטר ערך תיאור
פרמטרים של נתיב
calendarId string מזהה היומן. כדי לאחזר מזהי יומנים, צריך להפעיל את השיטה calendarList.list. כדי להיכנס ליומן הראשי של המשתמש שמחובר כרגע, אפשר להשתמש באפשרות 'primary' במילת מפתח.
eventId string מזהה האירוע.
פרמטרים אופציונליים של שאילתה
alwaysIncludeEmail boolean הוצא משימוש והמערכת התעלמה ממנו. תמיד יוחזר ערך בשדה email עבור המארגן, היוצר והמשתתפים, גם אם לא קיימת כתובת אימייל אמיתית (כלומר יסופק ערך שנוצר שלא פועל).
conferenceDataVersion integer מספר הגרסה של נתוני שיחת ועידה שנתמך בלקוח ה-API. גרסה 0 מניחה שאין תמיכה בנתונים של שיחת ועידה ומתעלמת מנתוני שיחת הוועידה בגוף האירוע. גרסה 1 מאפשרת תמיכה בהעתקה של ConferenceData וגם ביצירת שיחות ועידה חדשות באמצעות השדה createRequest ב- שלב Data. ערך ברירת המחדל הוא 0. הערכים הקבילים הם 0 עד 1, כולל.
maxAttendees integer מספר המשתתפים המקסימלי שאפשר לכלול בתשובה. אם מספר המשתתפים גדול ממספר המשתתפים שצוין, רק המשתתף יוחזר. זה שינוי אופציונלי.
sendNotifications boolean הוצא משימוש. במקום זאת, אפשר להשתמש ב-sendUpdates.

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

הערכים הקבילים הם:
  • 'all': התראות נשלחות לכל המשתתפים.
  • 'externalOnly': ההתראות נשלחות רק למשתתפים שלא משתמשים ביומן Google.
  • "none": לא נשלחות התראות. למשימות של העברת יומן, כדאי להשתמש במקום זאת ב-method Events.import.
supportsAttachments boolean האם פעולה של לקוח API תומכת בקבצים מצורפים של אירועים. זה שינוי אופציונלי. ערך ברירת המחדל הוא False.

אישור

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

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

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

גוף הבקשה

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

שם הנכס ערך תיאור הערות
המאפיינים הנדרשים
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 - המשתתף אישר את ההזמנה.
 ניתן לכתיבה
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, לדוגמה "אירופה/ציריך".) לאירועים חוזרים, השדה הזה הוא חובה, והוא מציין את אזור הזמן שבו החזרה מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית בשביל ההתחלה/הסיום של האירוע. ניתן לכתיבה
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 המיקום הגיאוגרפי של האירוע כטקסט חופשי. זה שינוי אופציונלי. ניתן לכתיבה
originalStartTime.date date התאריך בפורמט 'yyyy-mm-dd', אם מדובר באירוע של יום שלם. ניתן לכתיבה
originalStartTime.dateTime datetime השעה, כערך משולב של תאריך (בפורמט בהתאם ל-RFC3339). חובה לציין אזור זמן, אלא אם צוין אזור זמן באופן מפורש ב-timeZone. ניתן לכתיבה
originalStartTime.timeZone string אזור הזמן שבו צוינה השעה. (בפורמט של שם מסד הנתונים של אזור זמן IANA, לדוגמה "אירופה/ציריך".) לאירועים חוזרים, השדה הזה הוא חובה, והוא מציין את אזור הזמן שבו החזרה מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית בשביל ההתחלה/הסיום של האירוע. ניתן לכתיבה
outOfOfficeProperties nested object נתוני אירועים מסוג 'לא בעבודה'. בשימוש אם הערך של eventType הוא outOfOffice. ניתן לכתיבה
recurrence[] list רשימה של שורות Rכלל, EXכלל, 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, לדוגמה "אירופה/ציריך".) לאירועים חוזרים, השדה הזה הוא חובה, והוא מציין את אזור הזמן שבו החזרה מורחבת. לאירועים בודדים, השדה הזה הוא אופציונלי ומציין אזור זמן מותאם אישית בשביל ההתחלה/הסיום של האירוע. ניתן לכתיבה
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 - האירוע הוא פרטי. הערך הזה צוין מסיבות של תאימות.
 ניתן לכתיבה
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 - המשתמש עובד ממיקום מותאם אישית.
כל הפרטים צוינו בשדה משנה של השם שצוין, אבל יכול להיות שהשדה הזה יהיה חסר אם הוא ריק. המערכת תתעלם משדות אחרים.

חובה כשמוסיפים מאפיינים של מיקום עבודה.

 ניתן לכתיבה

תשובה

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

דוגמאות

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

Java

משתמש בספריית הלקוח של Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Retrieve the event from the API
Event event = service.events().get("primary", "eventId").execute();

// Make a change
event.setSummary("Appointment at Somewhere");

// Update the event
Event updatedEvent = service.events().update("primary", event.getId(), event).execute();

System.out.println(updatedEvent.getUpdated());

Python

משתמש בספריית הלקוח של Python.

# First retrieve the event from the API.
event = service.events().get(calendarId='primary', eventId='eventId').execute()

event['summary'] = 'Appointment at Somewhere'

updated_event = service.events().update(calendarId='primary', eventId=event['id'], body=event).execute()

# Print the updated date.
print updated_event['updated']

PHP

משתמש בספריית הלקוח של PHP.

// First retrieve the event from the API.
$event = $service->events->get('primary', 'eventId');

$event->setSummary('Appointment at Somewhere');

$updatedEvent = $service->events->update('primary', $event->getId(), $event);

// Print the updated date.
echo $updatedEvent->getUpdated();

Ruby

משתמש בספריית הלקוח של Ruby.

event = client.get_event('primary', 'eventId')
event.summary = 'Appointment at Somewhere'
result = client.update_event('primary', event.id, event)
print result.updated

נסה בעצמך!

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