Events: list

Trả về các sự kiện trên lịch được chỉ định. Thử ngay.

Yêu cầu

Yêu cầu HTTP

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

Thông số

Tên thông số Giá trị Mô tả
Tham số đường dẫn
calendarId string Mã 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 đang đăng nhập, hãy sử dụng từ khoá "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 bạn không đặt chính sách này, tất cả các loại sự kiện sẽ được trả về.

Các giá trị được chấp nhận là:
  • "birthday": Sự kiện đặc biệt diễn ra cả ngày và lặp lại hằng năm.
  • "default": Sự kiện định kỳ.
  • "focusTime": Sự kiện thời gian tập trung.
  • "fromGmail": Sự kiện từ Gmail.
  • "outOfOffice": Sự kiện không có mặt tại văn phòng.
  • "workingLocation": Sự kiện về địa điểm làm việc.
iCalUID string Chỉ định mã sự kiện ở định dạng iCalendar sẽ được cung cấp trong phản hồi. Không bắt buộc. Sử dụng tham số này nếu bạn muốn tìm kiếm một sự kiện theo mã iCalendar.
maxAttendees integer Số người tham dự tối đa cần đưa vào phản hồi. Nếu có nhiều người tham dự hơn số lượng được chỉ định, thì chỉ người tham gia mới đượ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 trong trang kết quả có thể ít hơn giá trị này hoặc không có sự kiện nào, ngay cả khi có nhiều sự kiện khác khớp với truy vấn. Bạn có thể phát hiện các trang chưa hoàn chỉnh bằng trường nextPageToken không trống trong phản hồi. 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à một thứ tự ổn định, không xác định.

Các giá trị được chấp nhận là:
  • "startTime": Sắp xếp theo ngày/giờ bắt đầu (tăng dần). Bạn chỉ có thể sử dụng tham số này khi truy vấn các sự kiện riêng lẻ (tức là tham số singleEvents là True)
  • "updated": Sắp xếp theo thời gian sửa đổi gần đây nhất (tăng dần).
pageToken string Mã thông báo chỉ định trang kết quả cần trả về. Không bắt buộc.
privateExtendedProperty string Ràng buộc thuộc tính mở rộng được chỉ định là propertyName=value. Chỉ khớp với các thuộc tính riêng tư. Tham 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ả các điều kiện ràng buộc đã cho.
q string Cụm từ tìm kiếm văn bản tự do để tìm những sự kiện khớp với các cụm từ này trong các trường sau:
  • summary
  • description
  • location
  • displayName của người tham dự
  • email của người tham dự
  • displayName của người tổ chức
  • email của người tổ chức
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Những cụm từ tìm kiếm này cũng khớp với các từ khoá được xác định trước dựa trên tất cả bản dịch tiêu đề hiển thị của các sự kiện vị trí làm việc, không làm việc và thời gian tập trung. Ví dụ: khi bạn tìm kiếm "Văn phòng" hoặc "Cục", hệ thống sẽ trả về các sự kiện vị trí làm việc thuộc loại officeLocation, còn khi bạn tìm kiếm "Không làm việc" hoặc "Abwesend", hệ thống sẽ trả về các sự kiện không làm việc. Không bắt buộc.
sharedExtendedProperty string Ràng buộc thuộc tính mở rộng được chỉ định là propertyName=value. Chỉ khớp với các thuộc tính được chia sẻ. Tham 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ả các điều kiện ràng buộc đã cho.
showDeleted boolean Có bao gồm các sự kiện đã xoá (có status bằng "cancelled") trong kết quả hay không. Các phiên bản đã huỷ của sự kiện định kỳ (nhưng không phải sự kiện định kỳ cơ bản) vẫn sẽ được đưa vào nếu cả showDeleted và singleEvents đều là False. Nếu cả showDeleted và singleEvents đều là True, thì chỉ các trường hợp riêng lẻ của sự kiện đã xoá (nhưng không phải sự kiện định kỳ 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 bị ẩn trong kết quả hay không. Không bắt buộc. Giá trị mặc định là False.
singleEvents boolean Có mở rộng các sự kiện định kỳ thành các lần diễn ra và chỉ trả về các sự kiện một lần riêng lẻ và các lần diễn ra của sự kiện định kỳ hay không, nhưng không trả về chính các sự kiện định kỳ cơ bản. Không bắt buộc. Giá trị mặc định là False.
syncToken string Mã thông báo nhận đượ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 đó. Nhờ đó, kết quả của yêu cầu danh sách này chỉ chứa những mục đã thay đổi kể từ thời điểm đó. Tất cả các sự kiện đã bị xoá kể từ yêu cầu danh sách trước đó sẽ luôn nằm trong tập kết quả và bạn không được phép đặt showDeleted thành False.
Có một số tham số truy vấn không thể chỉ định cùng với nextSyncToken để đảm bảo tính nhất quán của trạng thái máy khách.

Đó là:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Tất cả các tham số truy vấn khác phải giống như tham số truy vấn cho lần đồng bộ hoá ban đầu để tránh hành vi không xác định. Nếu 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 khách sẽ xoá bộ nhớ của mình, đồng thời thực hiện quy trình đồng bộ hoá đầy đủ mà không có syncToken.
Tìm hiểu thêm về tính năng đồng bộ hoá gia tăng.
Không bắt buộc. Chế độ mặc định là trả về tất cả các mục.
timeMax datetime Giới hạn trên (loại trừ) cho thời gian bắt đầu của một sự kiện để lọc theo. Không bắt buộc. Theo mặc định, bạn không thể 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. Bạn có thể cung cấp giá trị theo mili giây nhưng giá trị này sẽ bị bỏ qua. Nếu bạn đặt timeMin, thì timeMax phải lớn hơn timeMin.
timeMin datetime Giới hạn dưới (loại trừ) cho thời gian kết thúc của một sự kiện để lọc theo. 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, ví dụ: 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Bạn có thể cung cấp giá trị theo mili giây nhưng giá trị này sẽ bị bỏ qua. Nếu bạn đặt timeMax, thì timeMin phải nhỏ hơn timeMax.
timeZone string Múi giờ được 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 cho thời gian 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 đã 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. Theo mặc định, bạn sẽ 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 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 phần 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 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.
description string Nội dung mô tả về lịch. Chỉ đọc.
updated datetime Thời gian sửa đổi lần 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ể 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ề trạng thái rảnh/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 truy cập đọ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. Người dùng có quyền ghi sẽ thấy các sự kiện riêng tư và thông tin chi tiết về sự kiện.
  • "owner" – Người dùng có quyền truy cập của người quản lý vào lịch. Vai trò này có tất cả các quyền của vai trò người viết, cộng thêm quyền xem và sửa đổi cấp độ truy cập của những người dùng khác.

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 mà không ghi đè một cách rõ ràng (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ể 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.

 có thể ghi
defaultReminders[].minutes integer Số phút trước khi sự kiện bắt đầu 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 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ó kết quả nào khác, trong trường hợp đó, nextSyncToken sẽ được cung cấp.
items[] list Danh sách các sự kiện trên lịch.
nextSyncToken string Mã thông báo được dùng vào thời điểm sau này để chỉ truy xuất những 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 đó, nextPageToken sẽ được cung cấp.

Hãy dùng thử!

Hãy 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 thực và xem phản hồi.