Trả về các sự kiện trên lịch đã 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
Tham số
| Tên thông số | Giá trị | Nội dung mô tả |
|---|---|---|
| Tham 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ừ khóa "primary".
|
| Tham số truy vấn không bắt buộc | ||
alwaysIncludeEmail |
boolean |
Không dùng nữa và bị bỏ qua. |
eventTypes |
string |
Các loại sự kiện cần trả về. Không bắt buộc. Bạn có thể lặp lại thông số này nhiều lần để trả về các sự kiện thuộc nhiều loại. Nếu không được đặt, hàm này sẽ trả về mọi loại sự kiện.
Các giá trị có thể chấp nhận là:
|
iCalUID |
string |
Chỉ định một mã sự kiện ở định dạng iLịch sẽ được cung cấp trong phản hồi. Không bắt buộc. Sử dụng tuỳ chọn này nếu bạn muốn tìm kiếm một sự kiện theo mã iLịch của sự kiện đó. |
maxAttendees |
integer |
Số người tham dự tối đa được đưa vào phản hồi. Nếu nhiều hơn số người tham dự đã chỉ định, thì chỉ người tham gia được trả về. Không bắt buộc. |
maxResults |
integer |
Số lượng sự kiện tối đa được trả về trên một trang kết quả. Số lượng sự kiện trên trang kết quả có thể ít hơn giá trị này hoặc hoàn toàn không có sự kiện nào, ngay cả khi có nhiều sự kiện hơn khớp với cụm từ tìm kiếm. Trường nextPageToken không trống trong phản hồi có thể phát hiện các trang chưa hoàn chỉnh. Theo mặc định, giá trị này là 250 sự kiện. Kích thước trang không bao giờ được lớn hơn 2.500 sự kiện. Không bắt buộc.
|
orderBy |
string |
Thứ tự của các sự kiện được trả về trong kết quả. Không bắt buộc. Giá trị mặc định là thứ tự ổn định, không xác định.
Các giá trị có thể chấp nhận là:
|
pageToken |
string |
Mã thông báo chỉ định trang kết quả sẽ trả về. Không bắt buộc. |
privateExtendedProperty |
string |
Quy tắc ràng buộc thuộc tính mở rộng được chỉ định dưới dạng attributeName=value. Chỉ so khớp các khu vực tư nhân. Thông số này có thể được lặp lại nhiều lần để trả về các sự kiện khớp với tất cả những quy tắc ràng buộc nhất định. |
q |
string |
Cụm từ tìm kiếm dạng văn bản tự do để tìm những sự kiện khớp với những cụm từ này trong các trường sau:
Các cụm từ tìm kiếm này cũng so khớp các từ khoá được xác định trước với tất cả các bản dịch tiêu đề hiển thị của địa điểm làm việc, sự kiện không có mặt tại văn phòng và sự kiện thời gian cần tập trung. Ví dụ: thao tác tìm kiếm "Văn phòng" hoặc "Bureau" sẽ trả về các sự kiện địa điểm làm việc thuộc loại |
sharedExtendedProperty |
string |
Quy tắc ràng buộc thuộc tính mở rộng được chỉ định dưới dạng attributeName=value. Chỉ so khớp các tài sản dùng chung. Thông số này có thể được lặp lại nhiều lần để trả về các sự kiện khớp với tất cả những quy tắc ràng buộc nhất định. |
showDeleted |
boolean |
Liệu có bao gồm các sự kiện đã xoá (với status bằng "cancelled") trong kết quả hay không. Nếu giá trị showDeleted và singleEvents đều là False, thì các trường hợp đã huỷ của các sự kiện định kỳ (nhưng không phải là sự kiện lặp lại cơ bản) vẫn sẽ được tính. Nếu showDeleted và singleEvents đều là True, thì chỉ một phiên bản của sự kiện đã xoá (chứ không phải là sự kiện lặp lại cơ bản) được trả về. Không bắt buộc. Giá trị mặc định là False.
|
showHiddenInvitations |
boolean |
Có bao gồm lời mời ẩn trong kết quả hay không. Không bắt buộc. Giá trị mặc định là False. |
singleEvents |
boolean |
Liệu có mở rộng sự kiện lặp lại thành thực thể và chỉ trả về các sự kiện một lần và phiên bản của sự kiện lặp lại, chứ không phải chính các sự kiện định kỳ cơ bản hay không. Không bắt buộc. Giá trị mặc định là False. |
syncToken |
string |
Mã thông báo thu được từ trường nextSyncToken được trả về trên trang kết quả cuối cùng của yêu cầu danh sách trước đó. Điều này khiến cho kết quả của yêu cầu danh sách này chỉ chứa các mục đã thay đổi kể từ thời điểm đó. Tất cả các sự kiện bị xoá vì yêu cầu danh sách trước đó sẽ luôn nằm trong tập hợp kết quả và không được phép đặt showDeleted thành False. Có một số tham số truy vấn không thể được chỉ định cùng với nextSyncToken để đảm bảo tính nhất quán của trạng thái ứng dụng. Đó là:
syncToken hết hạn, máy chủ sẽ phản hồi bằng mã phản hồi 410 GONE và ứng dụng sẽ xoá bộ nhớ và thực hiện quá trình đồng bộ hoá toàn bộ mà không có bất kỳ syncToken nào. Tìm hiểu thêm về tính năng đồng bộ hoá gia tăng. Không bắt buộc. Giá trị mặc định là trả về tất cả các mục nhập. |
timeMax |
datetime |
Giới hạn trên (dành riêng) cho thời gian bắt đầu của một sự kiện để lọc theo. Không bắt buộc. Tuỳ chọn 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, ví dụ: 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Có thể cung cấp mili giây nhưng sẽ bị bỏ qua. Nếu bạn đặt timeMin, timeMax phải lớn hơn timeMin.
|
timeMin |
datetime |
Giới hạn dưới (dành riêng) cho thời gian kết thúc của một sự kiện để lọc theo. Không bắt buộc. 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, ví dụ: 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Có thể cung cấp mili giây nhưng sẽ bị bỏ qua. Nếu bạn đặt timeMax, thì timeMin phải nhỏ hơn timeMax.
|
timeZone |
string |
Múi giờ dùng trong câu trả lời. Không bắt buộc. Múi giờ mặc định là múi giờ của lịch. |
updatedMin |
datetime |
Giới hạn dưới của thời điểm sửa đổi gần đây nhất của một sự kiện (dưới dạng dấu thời gian RFC3339) để lọc theo. Khi được chỉ định, các mục bị xoá kể từ thời điểm này sẽ luôn được đưa vào bất kể showDeleted. Không bắt buộc. Mặc định là không lọc theo thời gian sửa đổi gần đây nhất.
|
Ủy quyền
Yêu cầu này cho phép uỷ quyền trong í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 |
Để 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ề nội dung phản hồi có cấu trúc như 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ị | Nội dung mô tả | Ghi chú |
|---|---|---|---|
kind |
string |
Loại bộ sưu tập ("calendar#events"). |
|
etag |
etag |
Thẻ ETag của bộ sưu tập. | |
summary |
string |
Tên lịch. Chỉ đọc. | |
description |
string |
Nội dung mô tả về lịch. Chỉ đọ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. | |
timeZone |
string |
Múi giờ của lịch. Chỉ đọc. | |
accessRole |
string |
Vai trò truy cập của người dùng đối với lịch này. Chỉ đọc. Các giá trị có thể sử dụng là:
|
|
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 mọi sự kiện trên lịch này mà không ghi đè một cách 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ể sử dụng là:
Bắt buộc khi thêm lời nhắc. |
có thể ghi |
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. |
có thể ghi |
nextPageToken |
string |
Mã thông báo được dùng để truy cập vào trang tiếp theo của kết quả này. Bị bỏ qua nếu không có thêm kết quả, 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 sau này để chỉ truy xuất các mục đã thay đổi kể từ khi kết quả này được trả về. Bị 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 events in the specified calendar
String pageToken = null;
do {
Events events = service.events().list('primary').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().list(calendarId='primary', pageToken=page_token).execute()
for event in events['items']:
print event['summary']
page_token = events.get('nextPageToken')
if not page_token:
break
1.199
Sử dụng thư viện ứng dụng PHP.
$events = $service->events->listEvents('primary');
while(true) {
foreach ($events->getItems() as $event) {
echo $event->getSummary();
}
$pageToken = $events->getNextPageToken();
if ($pageToken) {
$optParams = array('pageToken' => $pageToken);
$events = $service->events->listEvents('primary', $optParams);
} else {
break;
}
}
Ruby
Sử dụng thư viện ứng dụng Ruby.
page_token = nil
begin
result = client.list_events('primary', page_token: page_token)
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 APIs Explorer 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.