Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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 phiên bản của 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ẻ) bằng cách đặt 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

Truy cập vào các phiên bản

Để xem tất cả các phiên bản của một sự kiện định kỳ nhất định, hãy sử dụng phương thức events.instances.

Theo mặc định, phương thức events.list sẽ trả về các sự kiện đơn lẻ, sự kiện định kỳ và ngoại lệ; những phiên bản không phải là ngoại lệ sẽ không được trả về. Nếu bạn đặt tham số singleEvents thành true, thì tất cả các phiên bản 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 xem thông tin rảnh/bận truy vấn events.list, thì hệ thống sẽ hoạt động như thể singleEvents là true. Để biết thêm thông tin về các quy tắc trong danh sách kiểm soát quyền truy cập, hãy xem phần ACL.

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

Sau đây là các trường sự kiện dành riêng cho các phiên bản:

recurringEventId – mã nhận dạng của sự kiện định kỳ mẹ mà phiên bản này thuộc về
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 phiên được lên lịch lại. Giá trị này xác định duy nhất lần xuất hiện trong chuỗi sự kiện định kỳ, ngay cả khi lần xuất hiện đó đã được di chuyển.

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

Để sửa đổi một phiên bản duy nhất (tạo một 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 đó, sau đó cập nhật bằng cách gửi một yêu cầu PUT được uỷ quyền đến URL chỉnh sửa phiên bản với 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ị đặc biệt calendarId primary để tham chiếu đến lịch chính của người dùng đã xác thực.

Khi thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK cùng với phiên bản đã cập nhật. Ví dụ sau đây cho thấy cách huỷ một phiên bản của 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 xuất hiện của một sự kiện định kỳ vào hoặc sau một lần xuất hiện nhất định (mục tiêu), hãy thực hiện 2 yêu cầu riêng biệt đối với API. Các yêu cầu này chia sự kiện định kỳ ban đầu thành hai sự kiện: sự kiện ban đầu (vẫn giữ nguyên các phiên bản không có thay đổi) và sự kiện định kỳ mới (có các phiên bản đã áp dụng thay đổi):

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

Ví dụ này cho thấy cách thay đổi vị trí thành "Một nơi khác", bắt đầu từ lần 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",
  ],
  "attendees": [
    {
      "email": "attendeeEmail",
      # Other attendee's data...
    },
    # ...
  ],
}

Sự kiện định kỳ Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

Giao thức

Java

.NET

Python

PHP

Ruby

Truy cập vào các phiên bản

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

Giao thức

Java

.NET

Python

PHP

Ruby

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

Giao thức

Sự kiện định kỳ