Questo documento descrive come utilizzare gli eventi ricorrenti e le relative istanze.
Creare eventi ricorrenti
La creazione di eventi ricorrenti è simile alla creazione di un evento normale (singolo) con il campo recurrence
della risorsa event
impostato.
Protocollo
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
Accedi alle istanze
Per visualizzare tutte le istanze di un determinato evento ricorrente, puoi utilizzare la richiesta events.instances().
Per impostazione predefinita, la richiesta events.list()
restituisce solo eventi singoli, eventi ricorrenti e eccezioni. Le istanze che non sono eccezioni non vengono restituite.
Se il parametro singleEvents
è impostato su true
, nel risultato vengono visualizzate tutte le singole istanze, ma non gli eventi ricorrenti sottostanti. Quando un utente con autorizzazioni disponibile/occupato esegue una query su events.list()
,
si comporta come se singleEvent
fosse true
. Per ulteriori informazioni sulle regole per l'elenco di controllo dell'accesso, vedi Acl.
Le singole istanze sono simili ai singoli eventi. A differenza degli eventi ricorrenti principali, per le istanze non è impostato il campo recurrence
.
I seguenti campi evento sono specifici per le istanze:
recurringEventId
: l'ID dell'evento ricorrente principale a cui appartiene questa istanzaoriginalStartTime
: l'ora di avvio di questa istanza in base ai dati sulla ricorrenza nell'evento ricorrente principale. Può essere diversa dall'ora effettiva distart
se l'istanza è stata ripianificata. Identifica in modo univoco l'istanza all'interno della serie di eventi ricorrenti anche se l'istanza è stata spostata.
Modifica o elimina istanze
Per modificare una singola istanza (creando un'eccezione), le applicazioni client devono prima recuperare l'istanza e poi aggiornarla inviando una richiesta PUT autorizzata all'URL di modifica dell'istanza con i dati aggiornati nel corpo. L'URL ha il seguente formato:
https://www.googleapis.com/calendar/v3/calendars/calendarId/events/instanceId
Utilizza i valori appropriati al posto di calendarId e instanceId.
Se l'operazione ha esito positivo, il server risponde con un codice di stato HTTP 200 OK con l'istanza aggiornata. L'esempio seguente mostra come annullare un'istanza di un evento ricorrente.
Protocollo
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
Modifica tutte le istanze seguenti
Per modificare tutte le istanze di un evento ricorrente su o dopo una determinata istanza (target), devi effettuare due richieste API separate. Queste richieste suddividono l'evento ricorrente originale in due: l'originale che conserva le istanze senza la modifica e il nuovo evento ricorrente con istanze in cui viene applicata la modifica:- Chiama
events.update()
per tagliare l'evento ricorrente originale delle istanze da aggiornare. Per farlo, imposta il componenteUNTIL
diRRULE
in modo che punti prima dell'ora di inizio della prima istanza di destinazione. In alternativa, puoi impostare il componenteCOUNT
anzichéUNTIL
. - Chiama
events.insert()
per creare un nuovo evento ricorrente con tutti gli stessi dati dell'originale, fatta eccezione per la modifica che stai cercando di apportare. Il nuovo evento ricorrente deve avere l'ora di inizio dell'istanza di destinazione.
Questo esempio mostra come modificare la località in "Altro luogo", a partire dalla terza istanza dell'evento ricorrente degli esempi precedenti.
Protocollo
# 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... }, # ... ], }