Events: instances

Trả về các thực thể của sự kiện định kỳ đã chỉ định. Thử ngay hoặc xem ví dụ.

Yêu cầu

Yêu cầu HTTP

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId/instances

Thông số

Tên thông số Giá trị Mô tả
Thông số đường dẫn
calendarId string Giá trị nhận dạng lịch. Để truy xuất mã lịch, hãy gọi phương thức calendarList.list. Nếu bạn muốn truy cập vào lịch chính của người dùng hiện đã đăng nhập, hãy sử dụng từ khoá "primary".
eventId string Giá trị nhận dạng sự kiện định kỳ.
Thông số truy vấn không bắt buộc
alwaysIncludeEmail boolean Ngừng sử dụng và bị bỏ qua. Hệ thống sẽ luôn trả về một giá trị trong trường email cho người tổ chức, nhà sáng tạo và người tham dự, ngay cả khi không có địa chỉ email thực (tức là hệ thống sẽ cung cấp một giá trị được tạo và không hoạt động).
maxAttendees integer Số lượng người tham dự tối đa cần đưa vào nội dung phản hồi. Nếu có nhiều hơn số người tham dự được chỉ định, thì chỉ người tham gia mới được trả về. Không bắt buộc.
maxResults integer Số sự kiện tối đa được trả về trên một trang kết quả. Theo mặc định, giá trị này là 250 sự kiện. Kích thước trang không được lớn hơn 2500 sự kiện. Không bắt buộc.
originalStart string Thời gian bắt đầu ban đầu của thực thể trong kết quả. Không bắt buộc.
pageToken string Mã thông báo chỉ định trang kết quả cần trả về. Không bắt buộc.
showDeleted boolean Liệu có đưa các sự kiện đã xoá (có status bằng "cancelled") vào kết quả hay không. Các phiên bản đã huỷ của sự kiện định kỳ vẫn sẽ được đưa vào nếu singleEvents là False. Không bắt buộc. Giá trị mặc định là False.
timeMax datetime Giới hạn trên (không bao gồm) cho thời gian bắt đầu của một sự kiện để lọc. Không bắt buộc. Chế độ mặc định là không lọc theo thời gian bắt đầu. Phải là dấu thời gian RFC3339 có độ lệch múi giờ bắt buộc.
timeMin datetime Giới hạn dưới (bao gồm) cho thời gian kết thúc của sự kiện để lọc. Không bắt buộc. Chế độ mặc định là không lọc theo thời gian kết thúc. Phải là dấu thời gian RFC3339 có độ lệch múi giờ bắt buộc.
timeZone string Múi giờ được dùng trong phản hồi. Không bắt buộc. Giá trị mặc định là múi giờ của lịch.

Ủy quyền

Yêu cầu này cho phép uỷ quyền với ít nhất một trong các phạm vi sau:

Phạm vi
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.events.owned.readonly
https://www.googleapis.com/auth/calendar.events.public.readonly

Để biết thêm thông tin, hãy xem trang xác thực và uỷ quyền.

Nội dung yêu cầu

Không cung cấp nội dung yêu cầu bằng phương thức này.

Phản hồi

Nếu thành công, phương thức này sẽ trả về một nội dung phản hồi có cấu trúc sau:

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
Tên tài sản Giá trị Mô tả Ghi chú
kind string Loại của bộ sưu tập ("calendar#events").
etag etag ETag của bộ sưu tập.
summary string Tiêu đề của lịch. Chỉ có thể đọc.
description string Nội dung mô tả về lịch. Chỉ có thể đọc.
updated datetime Thời gian sửa đổi gần đây nhất của lịch (dưới dạng dấu thời gian RFC3339). Chỉ có thể đọc.
timeZone string Múi giờ của lịch. Chỉ có thể đọc.
accessRole string Vai trò truy cập của người dùng đối với lịch này. Chỉ có thể đọc. Các giá trị có thể có là:
  • "none" – Người dùng không có quyền truy cập.
  • "freeBusyReader" – Người dùng có quyền đọc thông tin về lịch trống/bận.
  • "reader" – Người dùng có quyền đọc lịch. Sự kiện riêng tư sẽ xuất hiện với những người dùng có quyền đọc, nhưng thông tin chi tiết về sự kiện sẽ bị ẩn.
  • "writer" – Người dùng có quyền đọc và ghi vào lịch. Sự kiện riêng tư sẽ xuất hiện với những người dùng có quyền truy cập của người viết và họ sẽ thấy thông tin chi tiết về sự kiện.
  • "owner" – Người dùng có quyền sở hữu lịch. Vai trò này có tất cả các quyền của vai trò người ghi, đồng thời có thêm khả năng xem và thao tác với ACL.
defaultReminders[] list Lời nhắc mặc định trên lịch cho người dùng đã xác thực. Những lời nhắc này áp dụng cho tất cả sự kiện trên lịch này không ghi đè rõ ràng các sự kiện đó (tức là không đặt reminders.useDefault thành True).
defaultReminders[].method string Phương thức mà lời nhắc này sử dụng. Các giá trị có thể có là:
  • "email" – Lời nhắc được gửi qua email.
  • "popup" – Lời nhắc được gửi qua cửa sổ bật lên trên giao diện người dùng.

Bắt buộc khi thêm lời nhắc.

writable
defaultReminders[].minutes integer Số phút trước khi bắt đầu sự kiện mà lời nhắc sẽ kích hoạt. Giá trị hợp lệ nằm trong khoảng từ 0 đến 40320 (4 tuần tính bằng phút).

Bắt buộc khi thêm lời nhắc.

writable
nextPageToken string Mã thông báo dùng để truy cập vào trang tiếp theo của kết quả này. Bỏ qua nếu không có kết quả nào khác, trong trường hợp này, nextSyncToken sẽ được cung cấp.
items[] list Danh sách sự kiện trên lịch.
nextSyncToken string Mã thông báo được sử dụng tại một thời điểm sau đó để chỉ truy xuất các mục đã thay đổi kể từ khi kết quả này được trả về. Bỏ qua nếu có thêm kết quả, trong trường hợp này, nextPageToken sẽ được cung cấp.

Ví dụ

Lưu ý: Các đoạn mã mẫu của phương thức này không phải là ví dụ cho mọi ngôn ngữ lập trình được hỗ trợ (xem trang thông tin về các thư viện dùng cho ứng dụng để biết danh sách các ngôn ngữ được hỗ trợ).

Java

Sử dụng thư viện ứng dụng Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the instances of a specific recurring event
String pageToken = null;
do {
  Events events =
      service.events().instances('primary', 'eventId').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

Sử dụng thư viện ứng dụng Python.

page_token = None
while True:
  events = service.events().instances(calendarId='primary', eventId='eventId',
                                      pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

Sử dụng thư viện ứng dụng PHP.

$events = $service->events->instances('primary', "eventId");

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->instances('primary', "eventId",
        $optParams);
  } else {
    break;
  }
}

Ruby

Sử dụng thư viện ứng dụng Ruby.

page_token = nil
begin
  result = client.list_event_instances('primary', 'eventId')
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

Hãy dùng thử!

Sử dụng Trình khám phá API bên dưới để gọi phương thức này trên dữ liệu trực tiếp và xem phản hồi.