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 |
事件的顏色。此 ID 參照了顏色定義 event 區段中的項目 (請參閱 顏色端點)。選填。 |
可寫入 |
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 與先前要求中的 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 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
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 日曆網頁使用者介面中,這個活動的絕對連結。唯讀。 | |
iCalUID |
string |
RFC5545 中定義的事件專屬 ID。可用於識別跨日曆系統的事件,且在透過 import 方法匯入事件時必須提供。 請注意, |
|
id |
string |
事件的不透明 ID。建立新的單一或週期性活動時,您可以指定活動 ID。提供的 ID 必須遵循以下規則:
如果您未指定 ID,伺服器會自動產生 ID。 請注意, |
可寫入 |
kind |
string |
資源類型 (「calendar#event 」)。 |
|
location |
string |
活動的地理位置,以任意形式顯示。選填。 | 可寫入 |
locked |
boolean |
是否為鎖定的活動副本,您無法變更主要活動欄位「摘要」、「說明」、「位置」、「開始」、「end」等主要活動欄位或「重複週期」預設值為 False。唯讀。 | |
organizer |
object |
活動發起人。如果發起人也是參與者,系統會在 attendees 中以不同的項目表示,並將 organizer 欄位設為 True。如要變更發起人,請使用移動作業。唯讀 (匯入事件時除外)。 |
可寫入 |
organizer.displayName |
string |
發起人的姓名 (如有)。 | 可寫入 |
organizer.email |
string |
發起人的電子郵件地址 (如有)。請務必提供符合 RFC5322 規定的有效電子郵件地址。 | 可寫入 |
organizer.id |
string |
發起人的個人資料 ID (如有)。 | |
organizer.self |
boolean |
發起人是否與活動副本出現在哪個日曆上。唯讀。預設值為 False。 | |
originalStartTime |
nested object |
以週期性活動來說,這是指根據週期性活動 ID 識別的週期性事件中,這個事件的開始時間。它可明確識別週期性活動系列中的例項,即使執行個體移動到不同的時間也一樣。不可變更。 | |
originalStartTime.date |
date |
如果這是全天活動,請採用「yyyy-mm-dd」格式的日期。 | 可寫入 |
originalStartTime.dateTime |
datetime |
採用合併的日期時間值 (根據 RFC3339 格式) 表示的時間。除非在 timeZone 中明確指定時區,否則必須使用時區偏移。 |
可寫入 |
originalStartTime.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
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 |
已驗證使用者的活動提醒資訊。請注意,變更提醒並不會同時變更相關活動的 updated 屬性。 |
|
reminders.overrides[] |
list |
如果活動未使用預設提醒,這裡會列出該活動專屬的提醒;如未設定,則表示尚未設定任何提醒。覆寫提醒數量上限為 5 個。 | 可寫入 |
reminders.overrides[].method |
string |
這項提醒使用的方法。可能的值包括:
新增提醒時為必填。 |
可寫入 |
reminders.overrides[].minutes |
integer |
活動開始時間前的分鐘數,以顯示提醒。有效值介於 0 到 40320 之間 (4 週以分鐘為單位)。 新增提醒時為必填。 |
可寫入 |
reminders.useDefault |
boolean |
是否要將日曆的預設提醒套用至活動。 | 可寫入 |
sequence |
integer |
其序號。 | 可寫入 |
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 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
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 |
工作地點的類型。可能的值包括:
新增工作地點屬性時為必填。 |
可寫入 |
方法
- 刪除
- 刪除活動。
- 取得
- 根據活動的 Google 日曆 ID 傳回活動。如要使用 i 行事曆 ID 擷取事件,請使用
iCalUID
參數呼叫 event.list 方法。 - import
- 匯入活動。這項作業可用於在日曆中新增現有活動的私人副本。只能匯入
eventType
為default
的事件。已淘汰的行為:匯入非
default
事件時,其類型會變更為default
,任何事件類型專屬屬性都會遭到捨棄。 - 插入
- 建立活動。
- instances
- 傳回指定週期性事件的例項。
- list
- 傳回特定日曆中的活動。
- 移動
- 將活動移至其他日曆,例如變更活動主辦者。請注意,只能移動
default
個事件。無法移動birthday
、focusTime
、fromGmail
、outOfOffice
和workingLocation
事件。 - 修補程式
- 更新活動。這個方法支援 patch 語意。請注意,每個修補要求都會耗用三個配額單位;偏好使用
get
,後面加上update
。您指定的欄位值會取代現有的值。未指定要求中的欄位會維持不變。陣列欄位 (如有指定) 會覆寫現有陣列;就會捨棄先前的所有陣列元素。 - quickAdd
- 根據簡單的文字字串建立事件。
- 更新
- 更新活動。這個方法不支援修補語意,且一律會更新整個事件資源。如要進行部分更新,請執行
get
,然後使用 Etag 執行update
,以確保不可部分完成。 - 手錶
- 留意「活動」資源的異動。