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 已指定為 resourceName=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

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

要求主體

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

回應

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

{
  "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」：使用者擁有這個日曆。這個角色具有 writer 角色的所有權限，並可查看及操作 ACL。
defaultReminders[] list 已驗證使用者日曆上的預設提醒事項。這些提醒適用於這個日曆中未明確覆寫的所有活動 (也就是未將 reminders.useDefault 設為 True)。
defaultReminders[].method string 提醒事項使用的提醒方法。可能的值包括：
  • 「email」：系統會透過電子郵件傳送提醒。
  • 「popup」：系統會透過使用者介面彈出式視窗傳送提醒。

新增提醒時必填。

 可寫入
defaultReminders[].minutes integer 活動開始前幾分鐘，系統應觸發提醒的時間點。有效值介於 0 到 40320 (4 週以分鐘為單位) 之間。

新增提醒時為必填。

 可寫入
nextPageToken string 存取此結果下一頁的權杖。如果沒有其他結果，則會省略，並提供 nextSyncToken。
items[] list 日曆上的活動清單。
nextSyncToken string 權杖會在稍後用於擷取自結果傳回以來變更的項目。如果還有其他結果，則會省略，並提供 nextPageToken。

範例

注意：這個方法適用的程式語言眾多，我們只在此提供部分程式碼範例，完整的支援語言清單請參閱用戶端程式庫頁面。

Java

使用 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

使用 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

PHP

使用 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 用戶端程式庫。

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?

試試看！

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