Wydarzenia cykliczne

Ten dokument opisuje sposób korzystania z wydarzeń cyklicznych i ich wystąpień.

Tworzenie wydarzeń cyklicznych

Tworzenie wydarzeń cyklicznych przypomina tworzenie zwykłych (pojedynczych) wydarzeń z ustawieniem pola recurrence zasobu event.

Protokół

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

Dostęp do instancji

Aby zobaczyć wszystkie wystąpienia danego wydarzenia cyklicznego, możesz użyć żądania events.instances().

domyślne żądanie events.list(), zwraca tylko pojedyncze wydarzenia, wydarzenia cykliczne i wyjątki; – instancje, które nie są wyjątkiem, nie są zwracane. Jeśli parametr singleEvents ustawiona jest wartość true, wtedy w wyniku pojawiają się wszystkie pojedyncze wystąpienia, ale nie występują w nich zdarzenia cykliczne. Gdy użytkownik z uprawnieniami dostępu do informacji o stanie Wolny/Zajęty wysyła zapytanie do funkcji events.list(), działa tak, jakby pole singleEvent miało wartość true. Więcej informacji o regułach listy kontroli dostępu znajdziesz w sekcji Acl.

Ostrzeżenie: nie modyfikuj poszczególnych instancji, jeśli chcesz zmodyfikować całe wydarzenie cykliczne lub wystąpienia „to i kolejne”. Powoduje to powstanie wielu wyjątków, które zaśmiecają kalendarz, spowalniają dostęp i powodują wysyłanie dużej liczby i powiadomienia o zmianach.

Poszczególne instancje są podobne do pojedynczych zdarzeń. W odróżnieniu od nadrzędnych wydarzeń cyklicznych instancje nie mają ustawionego pola recurrence.

Te pola zdarzeń są specyficzne dla instancji:

• recurringEventId – identyfikator nadrzędnego wydarzenia cyklicznego, do którego należy ta instancja
• originalStartTime – czas uruchomienia tej instancji zgodnie z danymi dotyczącymi powtarzania w nadrzędnym zdarzeniu cyklicznym. Może się on różnić od rzeczywistego czasu start, jeśli przełożono instancję. Jednoznacznie identyfikuje wystąpienie w serii zdarzeń cyklicznych, nawet jeśli instancja została przeniesiona.

Modyfikowanie i usuwanie instancji

Aby zmodyfikować pojedynczą instancję (tworząc wyjątek), aplikacje klienckie muszą najpierw pobrać instancję, a następnie zaktualizować ją, wysyłając autoryzowane żądanie PUT do adresu URL edycji instancji, umieszczając w treści zaktualizowane dane. Adres URL ma postać:

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

Użyj odpowiednich wartości zamiast calendarId i instanceId.

Uwaga: specjalną wartość calendarId primary można użyć w odniesieniu do głównego kalendarza uwierzytelnionego użytkownika.

Po pomyślnym zakończeniu serwer wysyła w odpowiedzi kod stanu HTTP 200 OK z zaktualizowaną instancją. Poniższy przykład pokazuje, jak anulować wystąpienie wydarzenia cyklicznego.

Protokół

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

Zmodyfikuj wszystkie następujące instancje

Aby zmienić wszystkie wystąpienia wydarzenia cyklicznego w danym wystąpieniu (docelowym) lub później, musisz wysłać 2 osobne żądania do interfejsu API. Żądania te powodują podzielenie oryginalnego wydarzenia cyklicznego na 2 grupy: oryginalne, które zachowuje wystąpienia bez zmiany, a nowe wydarzenie cykliczne przypadki zastosowania zmiany:

1. Zadzwoń pod numer events.update() przytnij pierwotne zdarzenie cykliczne z instancji, które chcesz zaktualizować. Aby to zrobić, ustaw parametr Komponent UNTIL elementu RRULE wskazujący przed czasem rozpoczęcia pierwszej instancji docelowej. Ewentualnie możesz ustawić komponentCOUNT zamiast UNTIL
2. Zadzwoń pod numer events.insert() utwórz nowe wydarzenie cykliczne z tymi samymi danymi co pierwotne wydarzenie, z wyjątkiem którą chcesz wprowadzić. Czas rozpoczęcia nowego wydarzenia cyklicznego: w instancji docelowej.

W tym przykładzie pokazujemy, jak zmienić lokalizację na „W innym miejscu”, zaczynając od trzeciej wystąpienia wydarzenia cyklicznego z poprzednich przykładów.

Protokół

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

.

Uwaga: zmiana wszystkich poniższych instancji spowoduje zresetowanie wszystkich występujących wyjątków po instancji docelowej.