Freebusy: query

Trả về thông tin về tình trạng rảnh/bận cho một nhóm lịch. Thử ngay.

Yêu cầu

Yêu cầu HTTP

POST https://www.googleapis.com/calendar/v3/freeBusy

Ủ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.freebusy
https://www.googleapis.com/auth/calendar.freebusy

Để 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

Trong phần nội dung yêu cầu, hãy cung cấp dữ liệu có cấu trúc sau:

{
  "timeMin": datetime,
  "timeMax": datetime,
  "timeZone": string,
  "groupExpansionMax": integer,
  "calendarExpansionMax": integer,
  "items": [
    {
      "id": string
    }
  ]
}
Tên tài sản Giá trị Mô tả Ghi chú
timeMin datetime Điểm bắt đầu của khoảng thời gian cho truy vấn được định dạng theo RFC3339.
timeMax datetime Thời điểm kết thúc khoảng thời gian cho truy vấn được định dạng theo RFC3339.
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à UTC.
groupExpansionMax integer Số lượng giá trị nhận dạng lịch tối đa được cung cấp cho một nhóm. Không bắt buộc. Hệ thống sẽ trả về lỗi đối với nhóm có số thành viên nhiều hơn giá trị này. Giá trị tối đa là 100.
calendarExpansionMax integer Số lượng lịch tối đa cần cung cấp thông tin về lịch biểu rảnh/bận. Không bắt buộc. Giá trị tối đa là 50.
items[] list Danh sách lịch và/hoặc nhóm cần truy vấn.
items[].id string Giá trị nhận dạng của một lịch hoặc một nhóm.

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#freeBusy",
  "timeMin": datetime,
  "timeMax": datetime,
  "groups": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "calendars": [
        string
      ]
    }
  },
  "calendars": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "busy": [
        {
          "start": datetime,
          "end": datetime
        }
      ]
    }
  }
}
Tên tài sản Giá trị Mô tả Ghi chú
kind string Loại tài nguyên ("calendar#freeBusy").
timeMin datetime Điểm bắt đầu của khoảng thời gian.
timeMax datetime Kết thúc khoảng thời gian.
groups object Mở rộng nhóm.
groups.(key) nested object Danh sách các lịch là thành viên của nhóm này.
groups.(key).errors[] list (Các) lỗi không bắt buộc (nếu không tính toán được cho nhóm).
groups.(key).errors[].domain string Loại lỗi hoặc danh mục lỗi chung.
groups.(key).errors[].reason string Lý do cụ thể gây ra lỗi. Một số giá trị có thể sử dụng là:
  • "groupTooBig" – Nhóm người dùng được yêu cầu quá lớn đối với một truy vấn.
  • "tooManyCalendarsRequested" – Số lượng lịch được yêu cầu quá lớn đối với một truy vấn.
  • "notFound" – Không tìm thấy tài nguyên được yêu cầu.
  • "internalError" – Dịch vụ API đã gặp lỗi nội bộ.
Các loại lỗi khác có thể được thêm vào trong tương lai, vì vậy, ứng dụng phải xử lý linh hoạt các trạng thái lỗi khác không có trong danh sách này.
groups.(key).calendars[] list Danh sách giá trị nhận dạng của lịch trong một nhóm.
calendars object Danh sách thông tin về tình trạng rảnh/bận cho lịch.
calendars.(key) nested object Thông tin mở rộng về lịch trống/bận cho một lịch.
calendars.(key).errors[] list (Các) lỗi không bắt buộc (nếu không tính toán được lịch).
calendars.(key).errors[].domain string Loại lỗi hoặc danh mục lỗi chung.
calendars.(key).errors[].reason string Lý do cụ thể gây ra lỗi. Một số giá trị có thể sử dụng là:
  • "groupTooBig" – Nhóm người dùng được yêu cầu quá lớn đối với một truy vấn.
  • "tooManyCalendarsRequested" – Số lượng lịch được yêu cầu quá lớn đối với một truy vấn.
  • "notFound" – Không tìm thấy tài nguyên được yêu cầu.
  • "internalError" – Dịch vụ API đã gặp lỗi nội bộ.
Các loại lỗi khác có thể được thêm vào trong tương lai, vì vậy, ứng dụng phải xử lý linh hoạt các trạng thái lỗi khác không có trong danh sách này.
calendars.(key).busy[] list Danh sách các khoảng thời gian mà lịch này được coi là bận.
calendars.(key).busy[].start datetime Thời điểm bắt đầu (bao gồm cả thời điểm bắt đầu) của khoảng thời gian.
calendars.(key).busy[].end datetime Thời điểm kết thúc (không bao gồm) của khoảng thời gian.

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.