Events: instances

傳回指定週期性活動的執行個體。 立即試用或查看範例。

要求

HTTP 要求

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

參數

參數名稱 值 說明
路徑參數
calendarId string 日曆 ID。如要擷取日曆 ID，請呼叫 calendarList.list 方法。如果要存取目前登入使用者的主要日曆，請使用「primary」關鍵字。
eventId string 週期性事件 ID。
自選查詢參數
alwaysIncludeEmail boolean 已淘汰並忽略。即使沒有實際電子郵件地址，系統一律會在發起人、建立者和參與者的 email 欄位中傳回值。也就是說，系統會提供產生的無效值。
maxAttendees integer 回應的參與者人數上限。如果參與者人數超過指定人數，系統只會傳回參與者。選填。
maxResults integer 單一結果網頁上傳回的事件數量上限。預設值為 250 個事件。網頁大小不得超過 2500 個活動。選填。
originalStart string 結果中執行個體的原始開始時間。選填。
pageToken string 指定要傳回哪個結果網頁的權杖。選填。
showDeleted boolean 是否要在結果中納入已刪除的事件 (status 等於「cancelled」)。如果 singleEvents 為 False，系統仍會包含已取消的週期性活動活動。選用設定。預設值為「False」。
timeMax datetime 事件開始時間的上下限 (不含)，用來篩選事件。選用設定。預設不會依照開始時間進行篩選。必須是含必要時區偏移的 RFC3339 時間戳記。
timeMin datetime 事件結束時間的下限 (含) 做為篩選依據。選用設定。預設不會依照結束時間進行篩選。必須是含必要時區偏移的 RFC3339 時間戳記。
timeZone string 回應中使用的時區。選用設定。預設值為日曆的時區。

授權

這項要求允許至少具有下列其中一項範圍的授權：

範圍
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 instances of a specific recurring event
String pageToken = null;
do {
  Events events =
      service.events().instances('primary', 'eventId').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().instances(calendarId='primary', eventId='eventId',
                                      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->instances('primary', "eventId");

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->instances('primary', "eventId",
        $optParams);
  } else {
    break;
  }
}

Ruby

使用 Ruby 用戶端程式庫。

page_token = nil
begin
  result = client.list_event_instances('primary', 'eventId')
  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，針對即時資料呼叫這個方法，然後查看回應。