本文件說明如何使用週期性事件及其執行個體。
建立週期性活動
建立週期性活動的做法,與在 event
資源的 recurrence
欄位組合中建立一般 (單一) 活動的做法類似。
通訊協定
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) 規則,請參閱 Acl。
個別例項與單一事件類似。執行個體與父項週期性事件不同,並未設定 recurrence
欄位。
以下是例項專用的事件欄位:
recurringEventId
:這個執行個體所屬的父項週期性事件 IDoriginalStartTime
:根據父項週期性事件中的週期資料,這個執行個體開始的時間。如果執行個體已重新排程,這個值可能會與實際的start
時間不同。該標記能夠唯一識別週期性活動系列中的執行個體,即使執行個體已移動也一樣。
修改或刪除執行個體
如要修改單一執行個體 (建立例外狀況),用戶端應用程式必須先擷取該執行個體,然後傳送授權 PUT 要求給主體中含有最新資料的執行個體編輯網址,才能更新執行個體。網址的格式如下:
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()
以剪輯要更新的執行個體原始週期性事件。方法是將RRULE
的UNTIL
元件設定為指向第一個目標執行個體的開始時間之前。或者,您也可以設定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;UNTIL=20110617T065959Z", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], }