Wiederkehrende Termine

In diesem Dokument wird die Arbeit mit wiederkehrenden Ereignissen und ihren Instanzen beschrieben.

Wiederkehrende Termine erstellen

Das Erstellen wiederkehrender Termine ähnelt dem Erstellen eines regulären (einzelnen) Ereignisses, für das das Feld event der Ressource recurrence festgelegt ist.

Protokoll

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

Auf Instanzen zugreifen

Mit der Anfrage events.instances() können Sie alle Instanzen eines bestimmten wiederkehrenden Ereignisses aufrufen.

Die events.list()-Anfrage gibt standardmäßig nur einzelne Ereignisse, wiederkehrende Ereignisse und Ausnahmen zurück. Instanzen, die keine Ausnahmen sind, werden nicht zurückgegeben. Wenn der Parameter singleEvents auf true gesetzt ist, werden alle einzelnen Instanzen im Ergebnis angezeigt, nicht jedoch die zugrunde liegenden wiederkehrenden Ereignisse. Wenn ein Nutzer, der Berechtigungen zur Verfügbarkeit hat, events.list() abfragen, verhält sich singleEvent so, als wäre er true. Weitere Informationen zu Regeln für die Zugriffssteuerung finden Sie unter ACL.

Warnung:Ändern Sie Instanzen nicht einzeln, wenn Sie den gesamten wiederkehrenden Termin oder die Instanzen „this and following“ ändern möchten. Dies führt zu vielen Ausnahmen, die den Kalender unübersichtlich machen, den Zugriff verlangsamen und zahlreiche Änderungsbenachrichtigungen an Nutzer senden.

Einzelne Instanzen ähneln einzelnen Ereignissen. Im Gegensatz zu den übergeordneten wiederkehrenden Ereignissen ist für Instanzen das Feld recurrence nicht festgelegt.

Die folgenden Ereignisfelder sind instanzspezifisch:

• recurringEventId: Die ID des übergeordneten wiederkehrenden Ereignisses, zu dem diese Instanz gehört.
• originalStartTime: Die Zeit, zu der diese Instanz gemäß den Wiederholungsdaten im wiederkehrenden wiederkehrenden Ereignis startet. Dieser Wert kann sich vom tatsächlichen start-Zeitpunkt unterscheiden, wenn die Instanz verschoben wurde. Damit wird die Instanz innerhalb der wiederkehrenden Terminreihe eindeutig identifiziert, auch wenn die Instanz verschoben wurde.

Instanzen ändern oder löschen

Zum Ändern einer einzelnen Instanz (Erstellung einer Ausnahme) müssen Clientanwendungen zuerst die Instanz abrufen und dann durch Senden einer autorisierten PUT-Anfrage mit aktualisierten Daten an den Instanz aktualisieren. Die URL hat das folgende Format:

https://www.googleapis.com/calendar/v3/calendars/calendarId/events/instanceId

Ersetzen Sie calendarId und instanceId durch entsprechende Werte.

Hinweis: Mit dem speziellen Wert calendarId kann primary auf den Hauptkalender des authentifizierten Nutzers verwiesen werden.

Bei Erfolg gibt der Server den HTTP-Statuscode "200 OK" mit der aktualisierten Instanz zurück. Das folgende Beispiel zeigt, wie Sie eine Instanz eines wiederkehrenden Termins absagen.

Protokoll

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

Alle folgenden Instanzen ändern

Um alle Instanzen eines wiederkehrenden Ereignisses auf oder nach einer bestimmten (Ziel-)Instanz zu ändern, müssen Sie zwei separate API-Anfragen stellen. Bei diesen Anfragen wird das ursprüngliche wiederkehrende Ereignis in zwei Teile aufgeteilt: das ursprüngliche Ereignis, bei dem die Instanzen ohne Änderung beibehalten werden, und das neue wiederkehrende Ereignis mit Instanzen, auf die die Änderung angewendet wurde:

1. Rufen Sie events.update() auf, um das ursprüngliche wiederkehrende Ereignis der zu aktualisierenden Instanzen zu entfernen. Legen Sie dazu die Komponente UNTIL der RRULE so fest, dass sie vor der Startzeit der ersten Zielinstanz verweist. Alternativ können Sie die Komponente COUNT anstelle von UNTIL festlegen.
2. Rufen Sie events.insert() auf, um ein neues wiederkehrendes Ereignis mit denselben Daten wie das Original zu erstellen, mit Ausnahme der Änderung, die Sie vornehmen möchten. Das neue wiederkehrende Ereignis muss die Startzeit der Zielinstanz haben.

In diesem Beispiel wird gezeigt, wie Sie den Standort zu „Irgendwo anders“ ändern. Beginnen Sie dabei mit der dritten Instanz des wiederkehrenden Termins aus den vorherigen Beispielen.

Protokoll

# 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...
    },
    # ...
  ],
}

Hinweis: Wenn Sie alle folgenden Instanzen ändern, werden alle Ausnahmen zurückgesetzt, die nach der Zielinstanz auftreten.