Events: import

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

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

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

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

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

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

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

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

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

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

תשובה

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

דוגמאות

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

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

נסה בעצמך!

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