Calendar API 提供多種活動資源,詳情請參閱活動簡介。
如需本資源的方法清單,請見本頁結尾。
資源表示法
{ "kind": "calendar#event", "etag": etag, "id": string, "status": string, "htmlLink": string, "created": datetime, "updated": datetime, "summary": string, "description": string, "location": string, "colorId": string, "creator": { "id": string, "email": string, "displayName": string, "self": boolean }, "organizer": { "id": string, "email": string, "displayName": string, "self": boolean }, "start": { "date": date, "dateTime": datetime, "timeZone": string }, "end": { "date": date, "dateTime": datetime, "timeZone": string }, "endTimeUnspecified": boolean, "recurrence": [ string ], "recurringEventId": string, "originalStartTime": { "date": date, "dateTime": datetime, "timeZone": string }, "transparency": string, "visibility": string, "iCalUID": string, "sequence": integer, "attendees": [ { "id": string, "email": string, "displayName": string, "organizer": boolean, "self": boolean, "resource": boolean, "optional": boolean, "responseStatus": string, "comment": string, "additionalGuests": integer } ], "attendeesOmitted": boolean, "extendedProperties": { "private": { (key): string }, "shared": { (key): string } }, "hangoutLink": string, "conferenceData": { "createRequest": { "requestId": string, "conferenceSolutionKey": { "type": string }, "status": { "statusCode": string } }, "entryPoints": [ { "entryPointType": string, "uri": string, "label": string, "pin": string, "accessCode": string, "meetingCode": string, "passcode": string, "password": string } ], "conferenceSolution": { "key": { "type": string }, "name": string, "iconUri": string }, "conferenceId": string, "signature": string, "notes": string, }, "gadget": { "type": string, "title": string, "link": string, "iconLink": string, "width": integer, "height": integer, "display": string, "preferences": { (key): string } }, "anyoneCanAddSelf": boolean, "guestsCanInviteOthers": boolean, "guestsCanModify": boolean, "guestsCanSeeOtherGuests": boolean, "privateCopy": boolean, "locked": boolean, "reminders": { "useDefault": boolean, "overrides": [ { "method": string, "minutes": integer } ] }, "source": { "url": string, "title": string }, "workingLocationProperties": { "type": string, "homeOffice": (value), "customLocation": { "label": string }, "officeLocation": { "buildingId": string, "floorId": string, "floorSectionId": string, "deskId": string, "label": string } }, "outOfOfficeProperties": { "autoDeclineMode": string, "declineMessage": string }, "focusTimeProperties": { "autoDeclineMode": string, "declineMessage": string, "chatStatus": string }, "attachments": [ { "fileUrl": string, "title": string, "mimeType": string, "iconLink": string, "fileId": string } ], "eventType": string }
資源名稱 | 值 | 說明 | 附註 |
---|---|---|---|
anyoneCanAddSelf |
boolean |
是否允許任何人邀請自己參加活動 (已不適用)。選用設定。預設值為「False」。 | 可寫入 |
attachments[] |
list |
活動的檔案附件。 如要修改附件, 每個活動最多只能有 25 個附件 |
|
attachments[].fileId |
string |
附件檔案的 ID。唯讀。 以 Google 雲端硬碟檔案來說,這是指 Drive API 中相應 |
|
attachments[].fileUrl |
string |
附件的網址連結。 如要新增 Google 雲端硬碟檔案附件,格式與 Drive API 中 新增附件時必填。 |
可寫入 |
attachments[].iconLink |
string |
附件圖示的網址連結。您只能針對自訂第三方連結修改這個欄位。 | |
attachments[].mimeType |
string |
附件的網際網路媒體類型 (MIME 類型)。 | |
attachments[].title |
string |
附件標題。 | |
attendeesOmitted |
boolean |
活動表中是否省略參與者。擷取事件時,原因可能是 maxAttendee 查詢參數指定的限制。更新活動時,這只能用來更新參與者的回覆。選用設定。預設值為「False」。 |
可寫入 |
attendees[] |
list |
活動的參與者。如要進一步瞭解如何與其他日曆使用者安排活動,請參閱有參與者的活動指南。服務帳戶必須使用全網域授權委派功能,才能填入參與者清單。 | 可寫入 |
attendees[].additionalGuests |
integer |
其他房客人數。選用設定。預設值為 0。 | 可寫入 |
attendees[].comment |
string |
參與者的回覆註解。選用。 | 可寫入 |
attendees[].displayName |
string |
參與者姓名 (如果有的話)。選用。 | 可寫入 |
attendees[].email |
string |
參與者的電子郵件地址 (如果有的話)。新增參與者時,必須填寫這個欄位。必須是符合 RFC5322 規定的有效電子郵件地址。 新增參與者時必填。 |
可寫入 |
attendees[].id |
string |
參與者的個人資料 ID (如有)。 | |
attendees[].optional |
boolean |
是否自由參加。選用設定。預設值為「False」。 | 可寫入 |
attendees[].organizer |
boolean |
與會者是否為活動發起人。唯讀。預設值為「False」。 | |
attendees[].resource |
boolean |
參與者是否為資源。只有在首次加入活動與會者時才能設定。後續的修改作業將遭到忽略。選用設定。預設值為「False」。 | 可寫入 |
attendees[].responseStatus |
string |
參與者的回覆狀態。可能的值包括:
|
可寫入 |
attendees[].self |
boolean |
這個項目是否代表顯示該活動副本的日曆。唯讀。預設值為「False」。 | |
colorId |
string |
活動的顏色。這是參照色彩定義 event 區段中項目的 ID (請參閱「 色彩端點」)。選用。 |
可寫入 |
conferenceData |
nested object |
會議相關資訊,例如 Google Meet 會議的詳細資料。如要建立新的會議詳細資料,請使用 createRequest 欄位。如要保存變更,請記得為所有事件修改要求將 conferenceDataVersion 要求參數設為 1 。 |
可寫入 |
conferenceData.conferenceId |
string |
會議的 ID。 開發人員可以用來追蹤會議,不應向使用者顯示。 每種會議解決方案類型的 ID 值格式不盡相同:
|
|
conferenceData.conferenceSolution |
nested object |
會議解決方案,例如 Google Meet。 已為建立要求失敗的會議取消設定。 必須提供 |
|
conferenceData.conferenceSolution.iconUri |
string |
使用者看到的解決方案圖示。 | |
conferenceData.conferenceSolution.key |
nested object |
用來識別此活動會議解決方案的關鍵。 | |
conferenceData.conferenceSolution.key.type |
string |
會議解決方案類型。 如果用戶端遇到陌生或空白的類型,應仍可顯示進入點。但應禁止修改。 可能的值包括:
|
|
conferenceData.conferenceSolution.name |
string |
使用者看到的解決方案名稱。未本地化。 | |
conferenceData.createRequest |
nested object |
發起新會議並附加到活動中的要求。資料是以非同步方式產生。如要確認資料是否存在,請查看 status 欄位。必須提供 |
|
conferenceData.createRequest.conferenceSolutionKey |
nested object |
會議解決方案,例如 Hangouts 或 Google Meet。 | |
conferenceData.createRequest.conferenceSolutionKey.type |
string |
會議解決方案類型。 如果用戶端遇到陌生或空白的類型,應仍可顯示進入點。但應禁止修改。 可能的值包括:
|
|
conferenceData.createRequest.requestId |
string |
用戶端針對此要求產生的專屬 ID。 用戶端應針對每個新要求重新產生這組 ID。如果提供的 ID 與前一項要求相同,系統就會忽略該要求。 |
|
conferenceData.createRequest.status |
nested object |
會議建立要求的狀態。 | |
conferenceData.createRequest.status.statusCode |
string |
會議建立要求的目前狀態。唯讀。 可能的值包括:
|
|
conferenceData.entryPoints[] |
list |
個別會議進入點的相關資訊,例如網址或電話號碼。 所有參與者都必須加入同一場會議。 必須提供 |
|
conferenceData.entryPoints[].accessCode |
string |
用來存取會議的存取碼。長度上限為 128 個半形字元。 建立新的會議資料時,請僅填入與會議提供者所用術語相符的 { 選用。 |
|
conferenceData.entryPoints[].entryPointType |
string |
會議進入點的類型。 可能的值為:
|
|
conferenceData.entryPoints[].label |
string |
URI 的標籤。向使用者顯示。未本地化。長度上限為 512 個半形字元。 例如:
選用。 |
|
conferenceData.entryPoints[].meetingCode |
string |
用來存取會議的會議代碼。長度上限為 128 個半形字元。 建立新的會議資料時,請僅填入與會議提供者所用術語相符的 { 選用。 |
|
conferenceData.entryPoints[].passcode |
string |
用來存取會議的密碼。長度上限為 128 個半形字元。 建立新的會議資料時,請僅填入與會議提供者所用術語相符的 { |
|
conferenceData.entryPoints[].password |
string |
存取會議的密碼。長度上限為 128 個半形字元。 建立新的會議資料時,請僅填入與會議提供者所用術語相符的 { 選用。 |
|
conferenceData.entryPoints[].pin |
string |
用來存取會議的 PIN 碼。長度上限為 128 個半形字元。 建立新的會議資料時,請僅填入與會議提供者所用術語相符的 { 選用。 |
|
conferenceData.entryPoints[].uri |
string |
進入點的 URI。長度上限為 1300 個半形字元。 格式:
|
|
conferenceData.notes |
string |
向使用者顯示的其他附註 (例如網域管理員提供的指示、法律聲明)。可以包含 HTML。長度上限為 2048 個半形字元。選用。 | |
conferenceData.signature |
string |
會議資料簽名。 在伺服器端產生。 已為建立要求失敗的會議取消設定。 如果會議有待處理的建立要求,則為選填屬性。 |
|
created |
datetime |
事件建立時間 (以 RFC3339 時間戳記表示)。唯讀。 | |
creator |
object |
活動建立者。唯讀。 | |
creator.displayName |
string |
創作者的名稱 (如有)。 | |
creator.email |
string |
創作者的電子郵件地址 (如有)。 | |
creator.id |
string |
創作者的個人資料 ID (如有)。 | |
creator.self |
boolean |
建立者是否對應至顯示該活動副本的日曆。唯讀。預設值為「False」。 | |
description |
string |
活動的說明。可以包含 HTML。選用。 | 可寫入 |
end |
nested object |
(不含) 活動的結束時間。如果是週期性活動,這是指第一次活動的結束時間。 | |
end.date |
date |
如果這是全天活動,則使用「yyyy-mm-dd」格式的日期。 | 可寫入 |
end.dateTime |
datetime |
時間,以合併的日期時間值表示 (格式符合 RFC3339 的格式)。除非在 timeZone 中明確指定時區,否則必須設定時區偏移。 |
可寫入 |
end.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,此為必要欄位,並指定重複週期的時區。如果是單一活動,此欄位為選填欄位,表示活動開始/結束的自訂時區。 | 可寫入 |
endTimeUnspecified |
boolean |
是否真的未指定結束時間。即使這項屬性設為 True,但基於相容性考量,系統仍會提供結束時間。預設值為「False」。 | |
etag |
etag |
資源的 ETag。 | |
eventType |
string |
事件的特定類型。事件建立後就無法修改。可能的值包括:
|
可寫入 |
extendedProperties |
object |
事件的擴充屬性。 | |
extendedProperties.private |
object |
屬於這個日曆上活動副本的私人資源。 | 可寫入 |
extendedProperties.private.(key) |
string |
私有屬性的名稱和對應的值。 | |
extendedProperties.shared |
object |
在其他參與者的日曆上共用活動副本的資源。 | 可寫入 |
extendedProperties.shared.(key) |
string |
共用屬性的名稱和對應的值。 | |
focusTimeProperties |
nested object |
專注時間事件資料。當 eventType 為 focusTime 時使用。 |
可寫入 |
focusTimeProperties.autoDeclineMode |
string |
是否要拒絕重疊時間活動的會議邀請。有效的值為 declineNone ,表示不會拒絕任何會議邀請;declineAllConflictingInvitations :代表所有與活動衝突的衝突會議邀請都會遭到拒絕;而 declineOnlyNewConflictingInvitations ,代表只有在「專注時間」活動進行時才會發起的新會議邀請不會遭到拒絕。 |
|
focusTimeProperties.chatStatus |
string |
在 Chat 和相關產品中標示使用者的狀態。可以是 available 或 doNotDisturb 。 |
|
focusTimeProperties.declineMessage |
string |
Google 日曆自動拒絕現有活動或新邀請時,設定的回應訊息。 | |
gadget |
object |
擴充這個事件的小工具。已淘汰小工具;這個結構僅用於傳回生日日曆中繼資料。 | |
gadget.display |
string |
小工具的顯示模式。已淘汰,可能的值包括:
|
可寫入 |
gadget.height |
integer |
小工具的高度 (像素)。高度須為大於 0 的整數。選用設定。已淘汰。 | 可寫入 |
gadget.iconLink |
string |
小工具的圖示網址。網址配置必須是 HTTPS。已淘汰。 | 可寫入 |
gadget.link |
string |
小工具的網址。網址配置必須是 HTTPS。已淘汰。 | 可寫入 |
gadget.preferences |
object |
。 | 可寫入 |
gadget.preferences.(key) |
string |
偏好設定名稱和對應值。 | |
gadget.title |
string |
小工具的標題。已淘汰。 | 可寫入 |
gadget.type |
string |
小工具的類型。已淘汰。 | 可寫入 |
gadget.width |
integer |
小工具的寬度 (以像素為單位)。寬度必須是大於 0 的整數。選用設定。已淘汰。 | 可寫入 |
guestsCanInviteOthers |
boolean |
發起人以外的與會者能否邀請他人參加活動。選用設定。預設值為「True」。 | 可寫入 |
guestsCanModify |
boolean |
發起人以外的與會者能否修改活動。選用設定。預設值為「False」。 | 可寫入 |
guestsCanSeeOtherGuests |
boolean |
發起人以外的與會者是否能查看活動的參與者。選用設定。預設值為「True」。 | 可寫入 |
hangoutLink |
string |
與這個活動相關聯的 Google Hangouts 絕對連結。唯讀。 | |
htmlLink |
string |
Google 日曆網頁版 UI 中這項活動的絕對連結。唯讀。 | |
iCalUID |
string |
如 RFC5545 中定義的事件專屬 ID。可用於識別日曆系統中的所有活動,而且必須在透過 import 方法匯入活動時提供。 請注意, |
|
id |
string |
事件的不易解讀 ID。建立新的單一或週期性活動時,您可以指定活動 ID。提供的 ID 必須遵循下列規則:
如果您未指定 ID,伺服器會自動產生這個 ID。 請注意, |
可寫入 |
kind |
string |
資源的類型 (「calendar#event 」)。 |
|
location |
string |
活動的地理位置,以任意形式顯示。選用。 | 可寫入 |
locked |
boolean |
如果不對主要活動欄位「摘要」、「說明」、「位置」、「開始」、「結束」或「重複週期」修改,這是否屬於已鎖定的活動副本,因此無法修改。預設值為「False」。唯讀。 | |
organizer |
object |
活動的發起人。如果發起人同時也是與會者,attendees 中會以獨立項目表示,並將 organizer 欄位設為 True。如要變更發起人,請使用「移動」作業。唯讀 (匯入事件時除外)。 |
可寫入 |
organizer.displayName |
string |
發起人的姓名 (如果有的話)。 | 可寫入 |
organizer.email |
string |
主辦人的電子郵件地址 (如果有的話)。必須是符合 RFC5322 規定的有效電子郵件地址。 | 可寫入 |
organizer.id |
string |
發起人的個人資料 ID (如有)。 | |
organizer.self |
boolean |
發起人是否對應到顯示該活動副本的日曆。唯讀。預設值為「False」。 | |
originalStartTime |
nested object |
如果是週期性活動的執行個體,此事件會根據週期性 EventId 識別的週期性活動中的週期資料計算而啟動的時間。唯一可用於識別週期性活動系列中的執行個體,即使執行個體移至不同時間也一樣。不可變更。 | |
originalStartTime.date |
date |
如果這是全天活動,則使用「yyyy-mm-dd」格式的日期。 | 可寫入 |
originalStartTime.dateTime |
datetime |
時間,以合併的日期時間值表示 (格式符合 RFC3339 的格式)。除非在 timeZone 中明確指定時區,否則必須設定時區偏移。 |
可寫入 |
originalStartTime.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,此為必要欄位,並指定重複週期的時區。如果是單一活動,此欄位為選填欄位,表示活動開始/結束的自訂時區。 | 可寫入 |
outOfOfficeProperties |
nested object |
不在辦公室的事件資料。當 eventType 為 outOfOffice 時使用。 |
可寫入 |
outOfOfficeProperties.autoDeclineMode |
string |
是否要拒絕重疊「不在辦公室」活動的會議邀請。有效值為 declineNone ,表示不會拒絕任何會議邀請;declineAllConflictingInvitations :代表所有與活動衝突的衝突會議邀請都會遭到拒絕;以及 declineOnlyNewConflictingInvitations ,代表只有在「不在辦公室」活動時抵達的新衝突會議邀請會遭到拒絕。 |
|
outOfOfficeProperties.declineMessage |
string |
Google 日曆自動拒絕現有活動或新邀請時,設定的回應訊息。 | |
privateCopy |
boolean |
如果設為 True,系統會停用事件傳播。請注意,這與私人活動屬性不同。選用設定。不可變動。預設值為「False」。 | |
recurrence[] |
list |
週期性活動的 RRULE、EXRULE、RDATE 和 EXDATE 行清單,如 RFC5545 所示。請注意,這個欄位中不允許使用 DTSTART 和 DTEND 行;活動開始和結束時間是在 start 和 end 欄位中指定。如果是單次活動或週期性活動,系統會省略這個欄位。 |
可寫入 |
recurringEventId |
string |
如果是週期性活動的執行個體,這是此執行個體所屬週期性活動的 id 。不可變更。 |
|
reminders |
object |
已驗證使用者的活動提醒相關資訊。 | |
reminders.overrides[] |
list |
如果活動未使用預設提醒,這裡會列出該活動專屬的提醒;如未設定,則表示沒有為該活動設定提醒。覆寫提醒數量上限為 5 個。 | 可寫入 |
reminders.overrides[].method |
string |
這則提醒使用的方法。可能的值包括:
新增提醒時必填。 |
可寫入 |
reminders.overrides[].minutes |
integer |
活動開始前的分鐘數。有效值介於 0 到 40320 (以分鐘為單位) 之間。 新增提醒時必填。 |
可寫入 |
reminders.useDefault |
boolean |
是否要將日曆的預設提醒套用至活動。 | 可寫入 |
sequence |
integer |
序號如 i Calendar。 | 可寫入 |
source |
object |
建立事件的來源。例如網頁、電子郵件訊息或任何含 HTTP 或 HTTPS 通訊協定的網址所辨識的文件。只有活動建立者才能查看或修改。 | |
source.title |
string |
來源標題,例如網頁標題或電子郵件主旨。 | 可寫入 |
source.url |
string |
指向資源的來源網址。網址配置必須是 HTTP 或 HTTPS。 | 可寫入 |
start |
nested object |
活動的開始時間 (含)。如果是週期性活動,這是指第一次活動的開始時間。 | |
start.date |
date |
如果這是全天活動,則使用「yyyy-mm-dd」格式的日期。 | 可寫入 |
start.dateTime |
datetime |
時間,以合併的日期時間值表示 (格式符合 RFC3339 的格式)。除非在 timeZone 中明確指定時區,否則必須設定時區偏移。 |
可寫入 |
start.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,此為必要欄位,並指定重複週期的時區。如果是單一活動,此欄位為選填欄位,表示活動開始/結束的自訂時區。 | 可寫入 |
status |
string |
活動的狀態。選用設定。可能的值包括:
|
可寫入 |
summary |
string |
活動的名稱。 | 可寫入 |
transparency |
string |
活動是否封鎖日曆上的時間。選用設定。可能的值包括:
|
可寫入 |
updated |
datetime |
事件的上次修改時間 (以 RFC3339 時間戳記表示)。唯讀。 | |
visibility |
string |
活動的顯示設定。選用設定。可能的值包括:
|
可寫入 |
workingLocationProperties |
nested object |
工作地點事件資料。 | 可寫入 |
workingLocationProperties.customLocation |
object |
如果有的話,請指定使用者是從自訂位置工作。 | 可寫入 |
workingLocationProperties.customLocation.label |
string |
選填的額外標籤,可提供更多詳細資訊。 | 可寫入 |
workingLocationProperties.homeOffice |
any value |
如果有指定使用者在家工作,請指定使用者在家工作。 | 可寫入 |
workingLocationProperties.officeLocation |
object |
如果有,指出使用者是在辦公室工作。 | 可寫入 |
workingLocationProperties.officeLocation.buildingId |
string |
選用的建築物 ID。以便參照機構資源資料庫中的建築物 ID。 | 可寫入 |
workingLocationProperties.officeLocation.deskId |
string |
選用的桌面 ID。 | 可寫入 |
workingLocationProperties.officeLocation.floorId |
string |
選填的樓層 ID。 | 可寫入 |
workingLocationProperties.officeLocation.floorSectionId |
string |
選填的樓層版面 ID。 | 可寫入 |
workingLocationProperties.officeLocation.label |
string |
顯示在日曆網頁和 Google 行動服務用戶端中的辦公室名稱。建議您在機構的資源資料庫中參考建築物名稱。 | 可寫入 |
workingLocationProperties.type |
string |
工作地點類型。可能的值包括:
新增工作地點屬性時為必填。 |
可寫入 |
方法
- 刪除
- 刪除活動。
- get
- 根據 Google 日曆 ID 傳回活動。如要使用 icalendar ID 擷取事件,請使用
iCalUID
參數呼叫events.list 方法。 - import
- 匯入活動。這項作業是用來將現有活動的私人副本新增至日曆。只能匯入
eventType
為default
的事件。淘汰行為:如果匯入非
default
事件,其類型會變更為default
,且可能捨棄該事件的任何事件類型專屬屬性。 - 插入
- 建立活動。
- 執行個體
- 傳回指定週期性活動的執行個體。
- list
- 傳回指定日曆上的活動。
- 移動
- 將活動移到其他日曆,例如變更活動發起人。請注意,只能移動
default
事件;無法移動outOfOffice
、focusTime
和workingLocation
事件。 - 修補程式
- 更新活動。這個方法支援修補語意。請注意,每個修補程式要求都會耗用三個配額單位;建議使用
get
,後面加上update
。您指定的欄位值會取代現有的值。您在要求中指定的欄位維持不變。陣列欄位 (如有指定) 會覆寫現有的陣列;這項操作會捨棄任何先前的陣列元素。 - quickAdd
- 根據簡單的文字字串建立事件。
- 更新
- 更新活動。這個方法不支援修補語意,且一律會更新整個事件資源。如要進行部分更新,請先執行
get
,然後使用 etag 執行update
,以確保不可分割性。 - 智慧手錶
- 留意活動資源的變更。