במאמר הזה נסביר איך עובדים עם אירועים חוזרים והמופעים שלהם.
יצירת אירועים חוזרים
יצירת אירועים חוזרים דומה ליצירת אירוע רגיל (יחיד) שבו מוגדר השדות 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()
,
ההתנהגות שלו מתנהגת כאילו singleEvent
הוא true
. למידע נוסף על הכללים ליצירת רשימות של בקרת גישה, אפשר לעיין ב-Acl.
מופעים בודדים דומים לאירועים בודדים. בניגוד לאירועים חוזרים של ההורים,
השדה recurrence
לא מוגדר במכונות.
שדות האירועים הבאים הם ספציפיים למכונות:
recurringEventId
– המזהה של האירוע החוזר ההורה שאליו שייך המופע הזהoriginalStartTime
– השעה שבה המופע יתחיל בהתאם לנתוני החזרה באירוע החוזר ההורה. זה יכול להיות שונה מהזמן בפועל ב-start
, אם למכונה נקבע מועד חדש. הוא מזהה באופן ייחודי את המופע מתוך סדרת האירועים החוזרים, גם אם הוא הועבר.
שינוי או מחיקה של מופעים
כדי לשנות מכונה אחת (על ידי יצירת חריגה), אפליקציות לקוח צריכות תחילה לאחזר את המופע ואז לעדכן אותו על ידי שליחה של בקשת PUT מורשית לכתובת ה-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()
כדי ליצור אירוע חוזר חדש עם כל הנתונים כמו המקור, מלבד השינוי שאתם מנסים לבצע. לאירוע החוזר החדש חייבת להיות שעת ההתחלה של מופע היעד.
בדוגמה הזו מוסבר איך לשנות את המיקום ל-"Somewhere else", החל מהמופע השלישי של האירוע החוזר מהדוגמאות הקודמות.
פרוטוקול
# 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;UNTIL=20110617T065959Z", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], }