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 ב- שלב Data. ערך ברירת המחדל הוא 0. הערכים הקבילים הם 0 עד 1, כולל.
supportsAttachments boolean האם פעולה של לקוח API תומכת בקבצים מצורפים של אירועים. זה שינוי אופציונלי. ערך ברירת המחדל הוא False.

אישור

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

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

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

גוף הבקשה

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

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

תשובה

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

דוגמאות

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

Java

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

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.EventAttendee;
import com.google.api.services.calendar.model.EventDateTime;
import com.google.api.client.util.DateTime;

import java.util.Date;
// ...

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

// Create and initialize a new event (could also retrieve an existing event)
Event event = new Event();
event.setICalUID("originalUID");

Event.Organizer organizer = new Event.Organizer();
organizer.setEmail("organizerEmail");
organizer.setDisplayName("organizerDisplayName");
event.setOrganizer(organizer);

ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>();
attendees.add(new EventAttendee().setEmail("attendeeEmail"));
// ...
event.setAttendees(attendees);

Date startDate = new Date();
Date endDate = new Date(startDate.getTime() + 3600000);
DateTime start = new DateTime(startDate, TimeZone.getTimeZone("UTC"));
event.setStart(new EventDateTime().setDateTime(start));
DateTime end = new DateTime(endDate, TimeZone.getTimeZone("UTC"));
event.setEnd(new EventDateTime().setDateTime(end));

// Import the event into a calendar
Event importedEvent = service.events().calendarImport('primary', event).execute();

System.out.println(importedEvent.getId());

Python

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

event = {
  'summary': 'Appointment',
  'location': 'Somewhere',
  'organizer': {
    'email': 'organizerEmail',
    'displayName': 'organizerDisplayName'
  },
  'start': {
    'dateTime': '2011-06-03T10:00:00.000-07:00'
  },
  'end': {
    'dateTime': '2011-06-03T10:25:00.000-07:00'
  },
  'attendees': [
    {
      'email': 'attendeeEmail',
      'displayName': 'attendeeDisplayName',
    },
    # ...
  ],
  'iCalUID': 'originalUID'
}

imported_event = service.events().import_(calendarId='primary', body=event).execute()

print imported_event['id']

PHP

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

$event = new Google_Service_Calendar_Event();
$event->setSummary('Appointment');
$event->setLocation('Somewhere');
$start = new Google_Service_Calendar_EventDateTime();
$start->setDateTime('2011-06-03T10:00:00.000-07:00');
$event->setStart($start);
$end = new Google_Service_Calendar_EventDateTime();
$end->setDateTime('2011-06-03T10:25:00.000-07:00');
$event->setEnd($end);
$attendee1 = new Google_Service_Calendar_EventAttendee();
$attendee1->setEmail('attendeeEmail');
// ...
$attendees = array($attendee1,
                   // ...,
                  );
$event->attendees = $attendees;
$organizer = new Google_Service_Calendar_EventOrganizer();
$organizer->setEmail('organizerEmail');
$organizer->setDisplayName('organizerDisplayName');
$event->setOrganizer($organizer);
$event->setICalUID('originalUID');
$importedEvent = $service->events->import('primary', $event);

echo $importedEvent->getId();

Ruby

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

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Appointment',
  location: 'Somewhere',
  organizer: {
    email: 'organizerEmail',
    display_name: 'organizerDisplayName'
  },
  start: {
    date_time: '2011-06-03T10:00:00.000-07:00'
  },
  end: {
    date_time: '2011-06-03T10:25:00.000-07:00'
  },
  attendees: [
    {
      email: 'attendeeEmail',
      display_name: 'attendeeDisplayName',
    },
    # ...
  ],
  i_cal_uid: 'originalUID'
)
result = client.import_event('primary', event)
print result.id

נסה בעצמך!

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