本頁面由 Cloud Translation API 翻譯而成。

Events: list

傳回特定日曆上的事件。立即試用或查看範例。

要求

HTTP 要求

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

參數

參數名稱	值	說明
路徑參數
`calendarId`	`string`	日曆 ID。如要擷取日曆 ID，請呼叫 calendarList.list 方法。如要存取目前登入使用者的主要日曆，請使用「`primary`」字詞。
選用的查詢參數
`alwaysIncludeEmail`	`boolean`	已淘汰並略過。
`eventTypes`	`string`	要傳回的事件類型。選用設定。這個參數可以重複多次，以傳回不同類型的事件。如未設定，則會傳回所有事件類型。可接受的值為：「`default`」：定期活動。「`focusTime`」：專注時間活動。「`fromGmail`」：Gmail 中的活動。「`outOfOffice`」：不在辦公室的活動。「`workingLocation`」：工作地點活動。
`iCalUID`	`string`	以 icalendar 格式指定要在回應中提供的活動 ID。選用設定。如果您要透過 icalendar ID 搜尋活動，請使用這個選項。
`maxAttendees`	`integer`	回應參與者的人數上限。如果參與者人數超過指定人數，系統只會傳回參與者。選用。
`maxResults`	`integer`	單一結果網頁上傳回的事件數量上限。結果網頁中的事件數量可能少於這個值，或者根本不存在，即使有更多與查詢相符的事件也一樣。系統可以透過回應中的 `nextPageToken` 欄位 (非空白) 偵測不完整的網頁。預設值為 250 個事件。頁面大小不可超過 2500 個事件。選用。
`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` 這些搜尋字詞也會比對預先定義的關鍵字，並與所有工作地點翻譯名稱 (包括工作地點、外出和專注時間活動) 進行比對。舉例來說，您可以搜尋「Office」或「Bureau」傳回類型為 `officeLocation` 的工作地點活動，搜尋「不在辦公室」或「Abwesend」會傳回不在辦公室的活動。選填。
`sharedExtendedProperty`	`string`	已指定為 resourceName=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`」- 使用者擁有日曆的擁有權。這個角色具備寫入者角色的所有權限，並能查看和操控 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?

試試看！

使用下方的 APIs Explorer，針對即時資料呼叫這個方法，看看會有什麼結果。