Freebusy: query

傳回一組日曆的有空/忙碌資訊。立即試用。

要求

HTTP 要求

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

授權

這項要求允許使用下列其中一個範圍進行授權：

範圍
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

詳情請參閱「驗證與授權」頁面。

要求主體

在要求主體中，請按照下列結構提供資料：

{
  "timeMin": datetime,
  "timeMax": datetime,
  "timeZone": string,
  "groupExpansionMax": integer,
  "calendarExpansionMax": integer,
  "items": [
    {
      "id": string
    }
  ]
}
屬性名稱 值 說明 附註
timeMin datetime 查詢的間隔開始時間，格式符合 RFC3339 規範。
timeMax datetime 查詢的時間間隔結束時間，格式符合 RFC3339 規範。
timeZone string 回應中使用的時區。選用設定。預設為世界標準時間。
groupExpansionMax integer 為單一群組提供的日曆 ID 數量上限。選用設定。如果群組的成員人數超過這個值，系統會傳回錯誤。值的上限為 100。
calendarExpansionMax integer 要提供有空/忙碌資訊的日曆數量上限。選用設定。最大值為 50。
items[] list 要查詢的日曆和/或群組清單。
items[].id string 日曆或群組的 ID。

回應

如果成功的話，這個方法會傳回回應內文，其結構如下：

{
  "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
        }
      ]
    }
  }
}
屬性名稱 值 說明 附註
kind string 資源類型 (「calendar#freeBusy」)。
timeMin datetime 有效時間範圍的開始時間。
timeMax datetime 有效時間範圍的結束時間。
groups object 展開群組。
groups.(key) nested object 這個群組的成員日曆清單。
groups.(key).errors[] list 選用錯誤 (如果群組的運算失敗)。
groups.(key).errors[].domain string 錯誤的領域或廣泛類別。
groups.(key).errors[].reason string 錯誤的具體原因。可能的值包括：
  • 「groupTooBig」：要求的使用者群組太大，無法單獨查詢。
  • 「tooManyCalendarsRequested」：要求的日曆數量太多，無法透過單一查詢執行。
  • 「notFound」- 找不到要求的資源。
  • 「internalError」：API 服務發生內部錯誤。
日後可能會新增其他錯誤類型，因此用戶端應妥善處理這份清單中未列出的其他錯誤狀態。
groups.(key).calendars[] list 群組內的日曆 ID 清單。
calendars object 日曆的有空/忙碌資訊清單。
calendars.(key) nested object 單一日曆的有空/忙碌擴充資料。
calendars.(key).errors[] list 選用錯誤 (如果日曆運算失敗)。
calendars.(key).errors[].domain string 錯誤的領域或大類。
calendars.(key).errors[].reason string 錯誤的具體原因。可能的值包括：
  • 「groupTooBig」：要求的使用者群組太大，無法單獨查詢。
  • 「tooManyCalendarsRequested」：要求的日曆數量太多，無法透過單一查詢執行。
  • 「notFound」- 找不到要求的資源。
  • 「internalError」：API 服務發生內部錯誤。
日後可能會新增其他錯誤類型，因此用戶端應妥善處理這份清單中未列出的其他錯誤狀態。
calendars.(key).busy[] list 列出這個日曆應視為忙碌時段的時間範圍。
calendars.(key).busy[].start datetime 時間範圍的開始時間 (包含在內)。
calendars.(key).busy[].end datetime 時間範圍的結束時間 (不包含在內)。

試試看！

您可以使用下方的 API Explorer，針對即時資料呼叫這個方法，然後查看回應。