Events: list

注意： 授權為選用項目。

傳回指定日曆上的活動。立即試用。

要求

HTTP 要求

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

參數

參數名稱	值	說明
路徑參數
calendarId	string	日曆 ID。如要擷取日曆 ID，請呼叫 calendarList.list 方法。如要存取目前登入使用者的主日曆，請使用「primary」關鍵字。
選用查詢參數
alwaysIncludeEmail	boolean	已淘汰且遭到忽略。
eventTypes	string	要傳回的事件類型。(非必要) 這個參數可重複多次，以便傳回不同類型的事件。如未設定，則會傳回所有事件類型。 可接受的值如下： 「birthday」：每年重複發生的特別全天活動。 「default」：定期活動。 「focusTime」：專注時間活動。 「fromGmail」：Gmail 中的活動。 「outOfOffice」：不在辦公室的活動。 「workingLocation」：工作地點事件。
iCalUID	string	在回應中指定 iCalendar 格式的事件 ID。(非必要) 如要依據 iCalendar ID 搜尋活動，請使用這個參數。
maxAttendees	integer	回應中可納入的出席者人數上限。如果出席者人數超過指定數量，系統只會傳回參與者。選用。
maxResults	integer	一個結果頁面中傳回的事件數量上限。即使有更多事件符合查詢，結果頁面中的事件數量可能會少於這個值，甚至可能一點都沒有。回應中非空白的 nextPageToken 欄位可用於偵測不完整的網頁。預設值為 250 個事件。每頁的事件數量不得超過 2,500 個。選用。
orderBy	string	結果中傳回事件的順序。(非必要) 預設值為未指定的穩定順序。 可接受的值如下： 「startTime」：依開始日期/時間遞增排序。只有在查詢單一事件時 (也就是參數 singleEvents 為 True) 才會顯示此資訊 「updated」：依上次修改時間排序 (遞增)。
pageToken	string	符記，可指定要傳回的結果頁面。選用。
privateExtendedProperty	string	延伸屬性限制，以 propertyName=value 的格式指定。僅比對私人資源。這個參數可能會重複多次，以便傳回符合所有指定限制的事件。
q	string	自由文字搜尋字詞，用於在下列欄位中找出符合這些字詞的事件： summary description location 與會者的 displayName 與會者的 email 主辦人 displayName 主辦人 email workingLocationProperties.officeLocation.buildingId workingLocationProperties.officeLocation.deskId workingLocationProperties.officeLocation.label workingLocationProperties.customLocation.label 這些搜尋字詞也會比對預先定義的關鍵字，與工作地點、外出辦公和專注時間事件的所有顯示標題翻譯內容相符。舉例來說，搜尋「辦公室」或「Bureau」會傳回 officeLocation 類型的辦公地點事件，而搜尋「不在辦公室」或「Abwesend」則會傳回不在辦公室事件。選填。
sharedExtendedProperty	string	延伸屬性限制，以 propertyName=value 的格式指定。僅比對共用房源。這個參數可能會重複多次，以便傳回符合所有指定限制的事件。
showDeleted	boolean	是否要在結果中納入已刪除的事件 (status 等於「cancelled」)。如果 showDeleted 和 singleEvents 都為 False，系統仍會納入週期性活動的已取消例項 (但不會納入基礎週期性活動)。如果 showDeleted 和 singleEvents 都為 True，系統只會傳回已刪除事件的單一例項 (而非基礎週期性事件)。(非必要) 預設值為 False。
showHiddenInvitations	boolean	是否要在結果中納入隱藏的邀請。(非必要) 預設值為 False。
singleEvents	boolean	是否要將週期性活動展開為個別事件，並只傳回單次週期性活動和週期性活動的個別事件，而非基礎週期性活動本身。(非必要) 預設值為 False。
syncToken	string	從先前列出要求的最後一個結果頁面傳回的 nextSyncToken 欄位取得的符記。這會讓這項清單要求的結果只包含自該日期起變更的項目。自上次列出要求以來刪除的所有事件，一律會列入結果集，且不允許將 showDeleted 設為 False。 為了確保用戶端狀態的一致性，有幾個查詢參數無法與 nextSyncToken 一併指定。 這些是： iCalUID orderBy privateExtendedProperty q sharedExtendedProperty timeMin timeMax updatedMin 所有其他查詢參數都應與初始同步作業相同，以免發生未定義的行為。如果 syncToken 到期，伺服器會傳回 410 GONE 回應代碼，用戶端應清除儲存空間，並在沒有任何 syncToken 的情況下執行完整同步作業。 進一步瞭解增量同步處理。 選用。預設會傳回所有項目。
timeMax	datetime	活動開始時間的上限 (不含)，用於篩選資料。(非必要) 預設不會依據開始時間篩選。必須是 RFC3339 時間戳記，並包含強制時區偏移，例如 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z。您可以提供毫秒數，但系統會忽略。如果已設定 timeMin，timeMax 必須大於 timeMin。
timeMin	datetime	事件結束時間的下限 (不含)，用於篩選資料。(非必要) 預設不會依結束時間篩選。必須是 RFC3339 時間戳記，並包含強制時區偏移，例如 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z。您可以提供毫秒數，但系統會忽略。如果已設定 timeMax，timeMin 必須小於 timeMax。
timeZone	string	回應中使用的時區。(非必要) 預設為日曆的時區。
updatedMin	datetime	事件上次修改時間的下限 (以 RFC3339 時間戳記表示)，用於篩選條件。指定後，系統一律會納入自此時間點起刪除的項目，不論 showDeleted 為何。(非必要) 預設不會依上次修改時間篩選。

授權

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

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

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

要求主體

請勿透過此方法提供要求主體。

回應

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

{
  "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
  ]
}

屬性名稱	值	說明	附註
kind	string	珍藏內容的類型 (「calendar#events」)。
etag	etag	集合的 ETag。
summary	string	日曆的標題。唯讀。
description	string	日曆說明。唯讀。
updated	datetime	日曆的上次修改時間 (以 RFC3339 時間戳記表示)。唯讀。
timeZone	string	日曆的時區。唯讀。
accessRole	string	使用者對這個日曆的存取權角色。這個唯讀設定檔可能的值包括： 「none」：使用者沒有存取權。 「freeBusyReader」：使用者有有空/忙碌資訊的讀取權。 「reader」：使用者具有日曆的讀取權限。私人活動會向具有讀取權限的使用者顯示，但活動詳細資料會隱藏。 「writer」：使用者具備日曆的讀取和寫入權限。私人活動會顯示給擁有編輯者存取權的使用者，且可查看活動詳細資料。 「owner」：使用者擁有日曆的擁有權。這個角色具備「作者」角色的所有權限，並可查看及操作 ACL。
defaultReminders[]	list	已驗證使用者日曆上的預設提醒事項。這些提醒適用於這個日曆中未明確覆寫的所有活動 (也就是未將 reminders.useDefault 設為 True)。
defaultReminders[].method	string	提醒事項使用的提醒方法。可能的值包括： 「email」- 系統會透過電子郵件傳送提醒。 「popup」- 透過 UI 彈出式視窗傳送提醒。 新增提醒時必須提供。	可寫入
defaultReminders[].minutes	integer	活動開始前幾分鐘，系統應觸發提醒的時間點。有效值介於 0 到 40320 (4 週以分鐘為單位) 之間。 新增提醒時必須提供。	可寫入
nextPageToken	string	用於存取此結果下一頁的符記。如果沒有其他結果，則會省略，並提供 nextSyncToken。
items[]	list	日曆中的活動清單。
nextSyncToken	string	權杖會在稍後用於擷取自這項結果傳回以來變更的項目。如果還有其他結果，則會省略，並提供 nextPageToken。

試試看！

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