Trang này được dịch bởi Cloud Translation API.

Sự kiện định kỳ

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

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

Việc tạo sự kiện định kỳ cũng tương tự như việc tạo một sự kiện thông thường (đơn) bằng 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']

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

Thực thể truy cập

Để xem tất cả các bản sao của một đối tượng cụ thể bạn có thể sử dụng yêu cầu events.instances().

Yêu cầu events.list() theo mặc định 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 tham số singleEvents được đặt true thì tất cả các lần xuất hiện riêng lẻ sẽ xuất hiện trong kết quả, nhưng các sự kiện lặp lại cơ bản thì không. Khi người dùng có quyền rảnh/bận truy vấn events.list(), nó sẽ hoạt động như thể singleEvent là true. Để biết thêm thông tin về các quy tắc đối với danh sách kiểm soát quyền truy cập, hãy xem phần Acl.

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, chưa đặt trường recurrence.

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

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

Sửa đổi hoặc xoá thực thể

Để sửa đổi một phiên bản duy nhất (tạo trường hợp 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 uỷ quyền đến URL chỉnh sửa phiên bản có dữ liệu 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 ý: Bạn có thể dùng giá trị calendarId đặc biệt primary để 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ủ sẽ 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 trình bày 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']

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

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

Để thay đổi tất cả các lần diễn ra của một sự kiện định kỳ vào hoặc sau một phiên bản (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. Những yêu cầu này chia sự kiện định kỳ ban đầu thành hai phần: phiên bản ban đầu giữ lại các thực thể mà không cần thay đổi và sự kiện định kỳ mới có các trường hợp áp dụng thay đổi:

Gọi events.update() tới cắt bỏ sự kiện định kỳ ban đầu của các thực thể cần cập nhật. Hãy 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 phiên bản mục tiêu đầu tiên. Ngoài ra, bạn có thể đặt thành phần COUNT thay vì UNTIL
Gọi events.insert() tới tạo một sự kiện định kỳ mới với tất cả dữ liệu giống như sự kiện ban đầu, ngoại trừ thay đổi bạn đang cố gắng thực hiện. Sự kiện định kỳ mới phải có thời gian bắt đầu là thực thể mục tiêu.

Ví dụ này cho biết cách thay đổi vị trí thành "Một nơi khác", bắt đầu từ vị trí thứ ba bản sao của sự kiện định kỳ từ 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...
    },
    # ...
  ],
}