要求
HTTP 要求
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
參數
參數名稱 | 值 | 說明 |
---|---|---|
路徑參數 | ||
calendarId |
string |
日曆 ID。如要擷取日曆 ID,請呼叫 calendarList.list 方法。如果要存取目前登入使用者的主要日曆,請使用「primary 」關鍵字。
|
選用查詢參數 | ||
alwaysIncludeEmail |
boolean |
已淘汰並忽略。 |
eventTypes |
string |
要傳回的事件類型。選用設定。您可以重複使用這個參數,用來傳回不同類型的事件。如未設定,系統會傳回所有事件類型。
可接受的值如下:
|
iCalUID |
string |
以 icalendar 格式指定要在回應中提供的事件 ID。選用設定。如要依據 icalendar ID 搜尋活動,請使用這個選項。 |
maxAttendees |
integer |
回應中包含的參與者人數上限。如果與會者人數超過指定人數,系統只會傳回參與者。選填。 |
maxResults |
integer |
單一結果網頁上傳回的事件數量上限。結果網頁上的事件數量可能會小於這個值,或是完全不顯示,即使還有其他事件符合查詢也一樣。回應中的 nextPageToken 欄位的非空白可以偵測到不完整的網頁。預設值為 250 個事件。頁面大小的事件數量不得超過 2,500 個。選填。
|
orderBy |
string |
結果中傳回的事件順序。選用設定。預設值為未指定的穩定順序。 可接受的值如下:
|
pageToken |
string |
用於指定要傳回哪個結果頁面的權杖。選填。 |
privateExtendedProperty |
string |
指定以 propertyName=value 形式指定的延伸屬性限制。僅符合私有地產。此參數可能會多次重複,以傳回符合所有指定限制的事件。 |
q |
string |
使用任意文字搜尋字詞,即可在下列欄位中尋找符合這些字詞的事件:
此外,這些搜尋字詞還會比對預先定義的關鍵字,以及所有顯示標題的翻譯,包括工作地點、不在辦公室和專注時間活動。舉例來說,如果您搜尋「辦公室」或「臺灣」,就會傳回「 |
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 一併指定,以確保用戶端狀態的一致性。這些是:
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 |
使用者對這個日曆的存取權角色。唯讀。可能的值包括:
|
|
defaultReminders[] |
list |
已驗證使用者的日曆預設提醒。這些提醒會套用到這個日曆中所有未明確覆寫的活動 (即未將 reminders.useDefault 設為 True)。 |
|
defaultReminders[].method |
string |
這則提醒使用的方法。可能的值包括:
新增提醒時必填。 |
可寫入 |
defaultReminders[].minutes |
integer |
活動開始前的分鐘數。有效值介於 0 到 40320 (以分鐘為單位) 之間。 新增提醒時必填。 |
可寫入 |
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
使用 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,針對有效資料呼叫這個方法,然後查看回應。