Sự kiện định kỳ

Tài liệu này mô tả cách xử lý các sự kiện định kỳ và bản sao của các sự kiện đó.

Tạo sự kiện định kỳ

Việc tạo sự kiện định kỳ tương tự như việc tạo một sự kiện thông thường (đơn lẻ) với nhóm trường recurrence của tài nguyên event.

Giao thức

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']

1.199

$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

Thực thể truy cập

Để xem tất cả bản sao của một sự kiện lặp lại nhất định, bạn có thể sử dụng yêu cầu events.instances().

Theo mặc định, yêu cầu events.list() chỉ trả về các sự kiện đơn lẻ, sự kiện định kỳ và ngoại lệ; các thực thể không phải là ngoại lệ sẽ không được trả về. Nếu thông số singleEvents được đặt true thì tất cả các thực thể riêng lẻ sẽ xuất hiện trong kết quả, nhưng các sự kiện định kỳ cơ bản thì không. Khi một người dùng có quyền rảnh/bận truy vấn events.list(), ứng dụng sẽ hoạt động như thể singleEvent là true. Để biết thêm thông tin về quy tắc danh sách kiểm soát quyền truy cập, hãy xem Acl.

Cảnh báo: Không sửa đổi từng thực thể riêng lẻ khi bạn muốn sửa đổi toàn bộ sự kiện định kỳ hoặc các thực thể "này và tiếp theo". Điều này tạo ra nhiều ngoại lệ làm lộn xộn lịch, làm chậm tốc độ truy cập và gửi một lượng lớn thông báo về thay đổi cho người dùng.

Các thực thể riêng lẻ tương tự như các sự kiện đơn lẻ. Không giống như các sự kiện định kỳ gốc, các thực thể không được đặt trường recurrence.

Sau đây là các trường sự kiện dành riêng cho từng trường hợp:

• recurringEventId — mã của sự kiện định kỳ mẹ có bản sao này
• originalStartTime – thời gian phiên bản này bắt đầu theo dữ liệu lặp lại trong sự kiện định kỳ mẹ. Thời gian này có thể khác với thời gian start thực tế nếu thực thể máy ảo đã được lên lịch lại. Mã này xác định duy nhất một bản sao trong chuỗi sự kiện định kỳ ngay cả khi bản sao đó đã được di chuyển.

Sửa đổi hoặc xoá bản sao

Để sửa đổi một phiên bản (tạo ngoại lệ), trước tiên, ứng dụng khách phải truy xuất phiên bản rồi cập nhật phiên bản đó bằng cách gửi yêu cầu PUT được ủy quyền đến URL chỉnh sửa phiên bản có dữ liệu được cập nhật trong phần nội dung. URL có dạng:

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

Sử dụng các giá trị thích hợp thay cho calendarId và instanceId.

Lưu ý: Giá trị calendarId đặc biệt primary có thể dùng để tham chiếu đến lịch chính của người dùng đã xác thực.

Sau khi thành công, máy chủ phản hồi bằng mã trạng thái HTTP 200 OK với phiên bản đã cập nhật. Ví dụ sau đây cho biết cách huỷ một phiên bản của một sự kiện định kỳ.

Giao thức

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']

1.199

$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

Sửa đổi tất cả trường hợp sau

Để thay đổi tất cả các lần xuất hiện của một sự kiện định kỳ vào hoặc sau một thực thể (mục tiêu) nhất định, bạn phải thực hiện hai yêu cầu API riêng biệt. Các yêu cầu này chia sự kiện định kỳ ban đầu thành hai: sự kiện ban đầu giữ lại các bản sao mà không có thay đổi và sự kiện định kỳ mới có các bản sao được áp dụng thay đổi:

1. Gọi events.update() để cắt bỏ sự kiện định kỳ ban đầu của các thực thể cần cập nhật. Thực hiện việc này bằng cách đặt thành phần UNTIL của RRULE trỏ đến trước thời gian bắt đầu của thực thể mục tiêu đầu tiên. Ngoài ra, bạn có thể đặt thành phần COUNT thay vì UNTIL.
2. Gọi events.insert() để tạo một sự kiện định kỳ mới có tất cả dữ liệu giống như dữ liệu ban đầu, ngoại trừ thay đổi mà bạn đang cố thực hiện. Sự kiện định kỳ mới phải có thời gian bắt đầu của thực thể mục tiêu.

Ví dụ này cho biết cách thay đổi vị trí thành "Nơi khác", bắt đầu từ bản sao thứ ba của sự kiện định kỳ trong các ví dụ trước.

Giao thức

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

Lưu ý: Việc thay đổi tất cả các thực thể sau sẽ đặt lại mọi ngoại lệ xảy ra sau thực thể mục tiêu đó.