เอกสารนี้อธิบายวิธีใช้กิจกรรมที่เกิดซ้ำและอินสแตนซ์ของกิจกรรมดังกล่าว
สร้างกิจกรรมที่เกิดซ้ำ
การสร้างกิจกรรมที่เกิดซ้ำจะคล้ายกับการสร้าง
กิจกรรมปกติ (ครั้งเดียว) โดยตั้งค่าฟิลด์ 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 ระบบจะทำงานราวกับว่า singleEvents เป็น true ดูข้อมูลเพิ่มเติมเกี่ยวกับกฎรายการควบคุมการเข้าถึงได้ที่ ACL
อินสแตนซ์แต่ละรายการจะคล้ายกับกิจกรรมครั้งเดียว โดยอินสแตนซ์จะไม่มีการตั้งค่าฟิลด์ recurrence ซึ่งแตกต่างจากกิจกรรมที่เกิดซ้ำระดับบน
ฟิลด์กิจกรรมต่อไปนี้ใช้กับอินสแตนซ์โดยเฉพาะ
recurringEventId\- รหัสของกิจกรรมที่เกิดซ้ำระดับบนที่อินสแตนซ์นี้เป็นของoriginalStartTime\- เวลาเริ่มต้นของอินสแตนซ์นี้ตามข้อมูลการเกิดซ้ำในกิจกรรมที่เกิดซ้ำระดับบน ซึ่งอาจแตกต่างจากเวลาstartจริงหากมีการกำหนดเวลาใหม่สำหรับอินสแตนซ์ โดยจะระบุอินสแตนซ์ภายในชุดกิจกรรมที่เกิดซ้ำได้อย่างไม่ซ้ำกัน แม้ว่าจะมีการย้ายอินสแตนซ์แล้วก็ตาม
แก้ไขหรือลบอินสแตนซ์
หากต้องการแก้ไขอินสแตนซ์เดียว (สร้างข้อยกเว้น) แอปพลิเคชันไคลเอ็นต์ต้องดึงข้อมูลอินสแตนซ์ก่อน แล้วจึงอัปเดตโดยส่งคำขอ PUT ที่ได้รับอนุญาตไปยัง URL การแก้ไขอินสแตนซ์พร้อมข้อมูลที่อัปเดตในเนื้อหา 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 แยกกัน 2 รายการ คำขอเหล่านี้จะแยกกิจกรรมที่เกิดซ้ำเดิมออกเป็น 2 รายการ ได้แก่ กิจกรรมเดิมซึ่งจะเก็บอินสแตนซ์ไว้โดยไม่มีการเปลี่ยนแปลง และกิจกรรมที่เกิดซ้ำใหม่ซึ่งมีอินสแตนซ์ที่มีการเปลี่ยนแปลง
- เรียก
events.updateเพื่อ ตัดกิจกรรมที่เกิดซ้ำเดิมออกจากอินสแตนซ์ที่จะอัปเดต โดยตั้งค่าคอมโพเนนต์UNTILของRRULEให้ชี้ไปที่เวลาก่อนเวลาเริ่มต้นของอินสแตนซ์เป้าหมายแรก หรือคุณจะตั้งค่าคอมโพเนนต์COUNTแทนUNTILก็ได้ - เรียก
events.insertเพื่อ สร้างกิจกรรมที่เกิดซ้ำใหม่ที่มีข้อมูลทั้งหมดเหมือนกับกิจกรรมเดิม ยกเว้นการ เปลี่ยนแปลงที่คุณกำลังทำ กิจกรรมที่เกิดซ้ำใหม่ต้องมีเวลาเริ่มต้นเป็นเวลาของอินสแตนซ์เป้าหมาย
ตัวอย่างนี้แสดงวิธีเปลี่ยนสถานที่จัดกิจกรรมเป็น "ที่อื่น" โดยเริ่มจากอินสแตนซ์ที่ 3 ของกิจกรรมที่เกิดซ้ำจากตัวอย่างก่อนหน้า
โปรโตคอล
# 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", ], "attendees": [ { "email": "attendeeEmail", # Other attendee's data... }, # ... ], }