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

אישור

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

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

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

גוף הבקשה

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

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

חשוב לשים לב שה-iCalUID וה-id אינם זהים, ויש לספק רק אחד מהם בעת יצירת האירוע. הבדל אחד בסמנטיקה שלהם הוא שבאירועים חוזרים, לכל המופעים של אירוע אחד יש אירועי id שונים, בעוד שלכולם יש אותם iCalUID. כדי לאחזר אירוע באמצעות iCalUID שלו, צריך להפעיל את ה-method 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 חדשים, EXBLOCK, 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' – האירוע לא חוסם את הזמן ביומן. ההגדרה הזו מקבילה להגדרת Show me as כ-זמין בממשק המשתמש של יומן Google.
ניתן לכתיבה
visibility string החשיפה של האירוע. זה שינוי אופציונלי. הערכים האפשריים הם:
  • 'default' – משתמשת בברירת המחדל של סטטוס החשיפה של אירועים ביומן. זהו ערך ברירת המחדל.
  • 'public' - האירוע ציבורי ופרטי האירוע גלויים לכל הקוראים של היומן.
  • 'private' – האירוע הוא פרטי ורק משתתפי האירוע יכולים לראות את פרטי האירוע.
  • 'confidential' – האירוע הוא פרטי. הערך הזה צוין מסיבות של תאימות.
ניתן לכתיבה

תשובה

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

דוגמאות

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

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 שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.