במאמר הזה מוסבר איך עובדים עם אירועים חוזרים והמופעים שלהם.
יצירת אירועים חוזרים
יצירת אירועים חוזרים דומה ליצירה של אירוע רגיל (יחיד) עם הגדרה של השדה recurrence במשאב Event.
פרוטוקול
POST /calendar/v3/calendars/primary/events ... { "summary": "Appointment", "location": "Somewhere", "start": { "dateTime": "2011-06-03T10:00:00.000-07:00", "timeZone": "America/Los_Angeles" }, "end": { "dateTime": "2011-06-03T10:25:00.000-07:00", "timeZone": "America/Los_Angeles" }, "recurrence": [ "RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], }
Java
Event event = new Event(); event.setSummary("Appointment"); event.setLocation("Somewhere"); ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>(); attendees.add(new EventAttendee().setEmail("attendeeEmail")); // ... event.setAttendees(attendees); DateTime start = DateTime.parseRfc3339("2011-06-03T10:00:00.000-07:00"); DateTime end = DateTime.parseRfc3339("2011-06-03T10:25:00.000-07:00"); event.setStart(new EventDateTime().setDateTime(start).setTimeZone("America/Los_Angeles")); event.setEnd(new EventDateTime().setDateTime(end).setTimeZone("America/Los_Angeles")); event.setRecurrence(Arrays.asList("RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z")); Event recurringEvent = service.events().insert("primary", event).execute(); System.out.println(createdEvent.getId());
.NET
Event event = new Event() { Summary = "Appointment", Location = "Somewhere", Start = new EventDateTime() { DateTime = new DateTime("2011-06-03T10:00:00.000:-07:00") TimeZone = "America/Los_Angeles" }, End = new EventDateTime() { DateTime = new DateTime("2011-06-03T10:25:00.000:-07:00") TimeZone = "America/Los_Angeles" }, Recurrence = new String[] { "RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z" }, Attendees = new List<EventAttendee>() { new EventAttendee() { Email: "attendeeEmail" }, // ... } }; Event recurringEvent = service.Events.Insert(event, "primary").Fetch(); Console.WriteLine(recurringEvent.Id);
Python
event = { 'summary': 'Appointment', 'location': 'Somewhere', 'start': { 'dateTime': '2011-06-03T10:00:00.000-07:00', 'timeZone': 'America/Los_Angeles' }, 'end': { 'dateTime': '2011-06-03T10:25:00.000-07:00', 'timeZone': 'America/Los_Angeles' }, 'recurrence': [ 'RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z', ], 'attendees': [ { 'email': 'attendeeEmail', # Other attendee's data... }, # ... ], } recurring_event = service.events().insert(calendarId='primary', body=event).execute() print recurring_event['id']
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'); $start->setTimeZone('America/Los_Angeles'); $event->setStart($start); $end = new Google_Service_Calendar_EventDateTime(); $end->setDateTime('2011-06-03T10:25:00.000-07:00'); $end->setTimeZone('America/Los_Angeles'); $event->setEnd($end); $event->setRecurrence(array('RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z')); $attendee1 = new Google_Service_Calendar_EventAttendee(); $attendee1->setEmail('attendeeEmail'); // ... $attendees = array($attendee1, // ... ); $event->attendees = $attendees; $recurringEvent = $service->events->insert('primary', $event); echo $recurringEvent->getId();
Ruby
event = Google::Apis::CalendarV3::Event.new( summary: 'Appointment', location: 'Somewhere', start: { date_time: '2011-06-03T10:00:00.000-07:00', time_zone: 'America/Los_Angeles' }, end: { date_time: '2011-06-03T10:25:00.000-07:00', time_zone: 'America/Los_Angeles' }, recurrence: ['RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z'] attendees: [ { email: 'attendeeEmail' }, #... ] ) response = client.insert_event('primary', event) print response.id
גישה למופעים
כדי לראות את כל המופעים של אירוע חוזר מסוים, משתמשים בשיטה events.instances.
כברירת מחדל, השיטה events.list מחזירה אירועים בודדים, אירועים חוזרים ומקרים חריגים. מופעים שלא מוגדרים כמקרים חריגים לא מוחזרים.
אם הפרמטר singleEvents מוגדר לערך true, כל המופעים הנפרדים יופיעו בתוצאה, אבל לא האירועים החוזרים הבסיסיים. כשמשתמש שיש לו הרשאות לראות את הזמינות של משתמשים אחרים שולח שאילתה ל-events.list, המערכת מתנהגת כאילו singleEvents הוא true. מידע נוסף על כללים של רשימות בקרת גישה (ACL) זמין במאמר בנושא ACL.
מקרים נפרדים דומים לאירועים בודדים. בניגוד לאירועים החוזרים הראשיים, במופעים לא מוגדר השדה recurrence.
שדות האירועים הבאים ספציפיים למופעים:
-
recurringEventId– המזהה של אירוע ההורה החוזר שאליו שייך המופע הזה -
originalStartTime— השעה שבה המופע הזה מתחיל לפי נתוני החזרה באירוע החוזר הראשי. יכול להיות שהזמן הזה יהיה שונה מהזמן בפועל שלstartאם הפגישה נדחתה. המזהה הייחודי של המופע בסדרת האירועים החוזרים, גם אם המופע הועבר.
שינוי או מחיקה של מופעים
כדי לשנות מופע יחיד (ליצור חריג), אפליקציות לקוח צריכות קודם לאחזר את המופע ואז לעדכן אותו על ידי שליחת בקשת PUT מורשית לכתובת ה-URL לעריכת המופע עם נתונים מעודכנים בגוף הבקשה. כתובת ה-URL היא מהצורה:
https://www.googleapis.com/calendar/v3/calendars/calendarId/events/instanceId
במקום calendarId ו-instanceId, צריך להשתמש בערכים מתאימים.
אם הפעולה בוצעה ללא שגיאות, השרת ישיב עם קוד הסטטוס HTTP 200 OK עם המופע המעודכן. בדוגמה הבאה אפשר לראות איך מבטלים מופע של אירוע חוזר.
פרוטוקול
PUT /calendar/v3/calendars/primary/events/instanceId
...
{
"kind": "calendar#event",
"id": "instanceId",
"etag": "instanceEtag",
"status": "cancelled",
"htmlLink": "https://www.google.com/calendar/event?eid=instanceEid",
"created": "2011-05-23T22:27:01.000Z",
"updated": "2011-05-23T22:27:01.000Z",
"summary": "Recurring event",
"location": "Somewhere",
"creator": {
"email": "userEmail"
},
"recurringEventId": "recurringEventId",
"originalStartTime": "2011-06-03T10:00:00.000-07:00",
"organizer": {
"email": "userEmail",
"displayName": "userDisplayName"
},
"start": {
"dateTime": "2011-06-03T10:00:00.000-07:00",
"timeZone": "America/Los_Angeles"
},
"end": {
"dateTime": "2011-06-03T10:25:00.000-07:00",
"timeZone": "America/Los_Angeles"
},
"iCalUID": "eventUID",
"sequence": 0,
"attendees": [
{
"email": "attendeeEmail",
"displayName": "attendeeDisplayName",
"responseStatus": "needsAction"
},
# ...
{
"email": "userEmail",
"displayName": "userDisplayName",
"responseStatus": "accepted",
"organizer": true,
"self": true
}
],
"guestsCanInviteOthers": false,
"guestsCanSeeOtherGuests": false,
"reminders": {
"useDefault": true
}
}Java
// First retrieve the instances from the API. Events instances = service.events().instances("primary", "recurringEventId").execute(); // Select the instance to cancel. Event instance = instances.getItems().get(0); instance.setStatus("cancelled"); Event updatedInstance = service.events().update("primary", instance.getId(), instance).execute(); // Print the updated date. System.out.println(updatedInstance.getUpdated());
.NET
// First retrieve the instances from the API. Events instances = service.Events.Instances("primary", "recurringEventId").Fetch(); // Select the instance to cancel. Event instance = instances.Items[0]; instance.Status = "cancelled"; Event updatedInstance = service.Events.Update(instance, "primary", instance.Id).Fetch(); // Print the updated date. Console.WriteLine(updatedInstance.Updated);
Python
# First retrieve the instances from the API. instances = service.events().instances(calendarId='primary', eventId='recurringEventId').execute() # Select the instance to cancel. instance = instances['items'][0] instance['status'] = 'cancelled' updated_instance = service.events().update(calendarId='primary', eventId=instance['id'], body=instance).execute() # Print the updated date. print updated_instance['updated']
PHP
$events = $service->events->instances("primary", "eventId"); // Select the instance to cancel. $instance = $events->getItems()[0]; $instance->setStatus('cancelled'); $updatedInstance = $service->events->update('primary', $instance->getId(), $instance); // Print the updated date. echo $updatedInstance->getUpdated();
Ruby
# First retrieve the instances from the API. instances = client.list_event_instances('primary', 'recurringEventId') # Select the instance to cancel. instance = instances.items[0] instance.status = 'cancelled' response = client.update_event('primary', instance.id, instance) print response.updated
שינוי כל המופעים הבאים
כדי לשנות את כל המופעים של אירוע חוזר במופע נתון (מופע היעד) או אחריו, צריך לשלוח שתי בקשות API נפרדות. הבקשות האלה מפצלות את האירוע החוזר המקורי לשני אירועים: האירוע המקורי, שכולל מופעים בלי השינוי, והאירוע החוזר החדש שכולל מופעים עם השינוי:
- מפעילים את הפונקציה
events.updateכדי לקצץ את המופעים של האירוע החוזר המקורי שרוצים לעדכן. כדי לעשות את זה, מגדירים את הרכיבUNTILשלRRULEכך שיצביע לפני שעת ההתחלה של מכונת היעד הראשונה. אפשר גם להגדיר את הרכיבCOUNTבמקוםUNTIL. - מתקשרים אל
events.insertכדי ליצור אירוע חוזר חדש עם כל הנתונים המקוריים, למעט השינוי שרוצים לבצע. לאירוע החוזר החדש צריכה להיות שעת ההתחלה של מופע היעד.
בדוגמה הזו מוסבר איך לשנות את המיקום ל'מקום אחר', החל מהמופע השלישי של האירוע החוזר מהדוגמאות הקודמות.
פרוטוקול
# Updating the original recurring event to trim the instance list: PUT /calendar/v3/calendars/primary/events/recurringEventId ... { "summary": "Appointment", "location": "Somewhere", "start": { "dateTime": "2011-06-03T10:00:00.000-07:00", "timeZone": "America/Los_Angeles" }, "end": { "dateTime": "2011-06-03T10:25:00.000-07:00", "timeZone": "America/Los_Angeles" }, "recurrence": [ "RRULE:FREQ=WEEKLY;UNTIL=20110617T065959Z", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], } # Creating a new recurring event with the change applied: POST /calendar/v3/calendars/primary/events ... { "summary": "Appointment", "location": "Somewhere else", "start": { "dateTime": "2011-06-17T10:00:00.000-07:00", "timeZone": "America/Los_Angeles" }, "end": { "dateTime": "2011-06-17T10:25:00.000-07:00", "timeZone": "America/Los_Angeles" }, "recurrence": [ "RRULE:FREQ=WEEKLY", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], }