更新活動。這個方法不支援修補語意,且一律會更新整個事件資源。如要進行部分更新,請執行 get
,然後使用 Etag 執行 update
,以確保不可部分完成。
立即試用或查看範例。
要求
HTTP 要求
PUT https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
參數
參數名稱 | 值 | 說明 |
---|---|---|
路徑參數 | ||
calendarId |
string |
日曆 ID。如要擷取日曆 ID,請呼叫 calendarList.list 方法。如要存取目前登入使用者的主要日曆,請使用「primary 」字詞。
|
eventId |
string |
事件 ID。 |
選用的查詢參數 | ||
alwaysIncludeEmail |
boolean |
已淘汰並略過。發起人、創作者和參與者的 email 欄位一律會傳回值,即使沒有可用的實際電子郵件地址也一樣 (亦即所產生的無效值)。
|
conferenceDataVersion |
integer |
API 用戶端支援的會議資料版本編號。版本 0 假設會議資料不支援,且會忽略活動內文中的會議資料。版本 1 支援複製 ConferenceData,以及使用會議資料的 createRequest 欄位建立新會議。預設值為 0。
可接受的值為 0 到 1 (含頭尾)。
|
maxAttendees |
integer |
回應參與者的人數上限。如果參與者人數超過指定人數,系統只會傳回參與者。選用。 |
sendNotifications |
boolean |
已淘汰,請改用 sendUpdates。 是否要傳送活動更新通知 (例如說明說明異動等)。請注意,即使將值設為 false ,部分電子郵件仍可能送出。預設為 false 。
|
sendUpdates |
string |
應該收到活動更新通知的邀請對象 (例如標題變更等)。
可接受的值為:
|
supportsAttachments |
boolean |
API 用戶端執行作業是否支援事件附件。選用設定。預設值為 False。 |
授權
這項要求需要授權,且至少要有下列其中一個範圍:
範圍 |
---|
https://www.googleapis.com/auth/calendar |
https://www.googleapis.com/auth/calendar.events |
詳情請參閱「驗證與授權」網頁。
要求主體
在要求主體中,提供事件資源並附上以下屬性:
屬性名稱 | 值 | 說明 | 附註 |
---|---|---|---|
必要屬性 | |||
end |
nested object |
事件的結束時間 (不含)。如果是週期性活動,則這是指第一個活動的結束時間。 | |
start |
nested object |
事件的開始時間 (含首尾)。如果是週期性活動,這是指第一個例項的開始時間。 | |
選用屬性 | |||
anyoneCanAddSelf |
boolean |
是否任何人都能邀請自己參加活動 (已淘汰)。選用設定。預設值為 False。 | 可寫入 |
attachments[].fileUrl |
string |
附件的網址連結。 如要新增 Google 雲端硬碟檔案附件,格式與 Drive API 中 新增附件時必填。 |
可寫入 |
attendees[] |
list |
活動的參與者。如要進一步瞭解如何與其他日曆使用者安排活動,請參閱與參與者的活動指南。服務帳戶必須使用全網域授權委派功能,才能填入參與者清單。 | 可寫入 |
attendees[].additionalGuests |
integer |
其他房客人數。選用設定。預設值為 0。 | 可寫入 |
attendees[].comment |
string |
參與者的回覆留言。選填。 | 可寫入 |
attendees[].displayName |
string |
參與者的姓名 (如有)。選填。 | 可寫入 |
attendees[].email |
string |
參與者的電子郵件地址 (如有)。新增與會者時,必須提供這個欄位。請務必提供符合 RFC5322 規定的有效電子郵件地址。 新增與會者時必須填寫此欄位。 |
可寫入 |
attendees[].optional |
boolean |
此人是否為自由參加。選用設定。預設值為 False。 | 可寫入 |
attendees[].resource |
boolean |
參與者是否為資源。只有在參與者首次加入活動時才能設定。系統會忽略後續的修改。選用設定。預設值為 False。 | 可寫入 |
attendees[].responseStatus |
string |
參與者的回覆狀態。可能的值包括:
|
可寫入 |
attendeesOmitted |
boolean |
活動的代表是否省略參與者。擷取事件時,可能是因為 maxAttendee 查詢參數指定的限制所致。更新活動時,這只能用來更新參與者的回覆。選用設定。預設值為 False。 |
可寫入 |
colorId |
string |
事件的顏色。此 ID 參照了顏色定義 event 區段中的項目 (請參閱 顏色端點)。選填。 |
可寫入 |
conferenceData |
nested object |
會議相關資訊,例如 Google Meet 會議的詳細資料。如要建立新的會議詳細資料,請使用「createRequest 」欄位。如要保留變更,請記得將所有事件修改要求的 conferenceDataVersion 要求參數設為 1 。 |
可寫入 |
description |
string |
活動的說明。可包含 HTML。選填。 | 可寫入 |
end.date |
date |
如果這是全天活動,請採用「yyyy-mm-dd」格式的日期。 | 可寫入 |
end.dateTime |
datetime |
採用合併的日期時間值 (根據 RFC3339 格式) 表示的時間。除非在 timeZone 中明確指定時區,否則必須使用時區偏移。 |
可寫入 |
end.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
extendedProperties.private |
object |
只有這個日曆的活動副本僅限使用的屬性。 | 可寫入 |
extendedProperties.shared |
object |
其他參與者的活動副本共用的屬性日曆。 | 可寫入 |
focusTimeProperties |
nested object |
專注時間事件資料。當 eventType 為 focusTime 時使用。 |
可寫入 |
gadget.display |
string |
小工具的顯示模式。已淘汰,可能的值包括:
|
可寫入 |
gadget.height |
integer |
小工具的高度 (像素)。高度必須是大於 0 的整數。選用設定。已淘汰。 | 可寫入 |
gadget.iconLink |
string |
小工具的圖示網址。網址配置必須是 HTTPS。已淘汰。 | 可寫入 |
gadget.link |
string |
小工具的網址。網址配置必須是 HTTPS。已淘汰。 | 可寫入 |
gadget.preferences |
object |
。 | 可寫入 |
gadget.title |
string |
小工具的標題。已淘汰。 | 可寫入 |
gadget.type |
string |
小工具的類型。已淘汰。 | 可寫入 |
gadget.width |
integer |
小工具的寬度 (單位為像素)。寬度必須是大於 0 的整數。選用設定。已淘汰。 | 可寫入 |
guestsCanInviteOthers |
boolean |
主辦單位以外的參與者是否能邀請其他人參加活動。選用設定。預設值為 True。 | 可寫入 |
guestsCanModify |
boolean |
主辦單位以外的與會者能否修改活動。選用設定。預設值為 False。 | 可寫入 |
guestsCanSeeOtherGuests |
boolean |
主辦人以外的與會者是否能查看活動的參與者。選用設定。預設值為 True。 | 可寫入 |
location |
string |
活動的地理位置,以任意形式顯示。選填。 | 可寫入 |
originalStartTime.date |
date |
如果這是全天活動,請採用「yyyy-mm-dd」格式的日期。 | 可寫入 |
originalStartTime.dateTime |
datetime |
採用合併的日期時間值 (根據 RFC3339 格式) 表示的時間。除非在 timeZone 中明確指定時區,否則必須使用時區偏移。 |
可寫入 |
originalStartTime.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
outOfOfficeProperties |
nested object |
不在辦公室的事件資料。當 eventType 為 outOfOffice 時使用。 |
可寫入 |
recurrence[] |
list |
週期性事件的 RRULE、EXRULE、RDATE 和 EXDATE 行清單,如 RFC5545 所指定。請注意,這個欄位不允許使用 DTSTART 和 DTEND 行;事件的開始與結束時間是在 start 和 end 欄位中指定。單一活動或週期性活動例項時,系統會略過這個欄位。 |
可寫入 |
reminders.overrides[] |
list |
如果活動未使用預設提醒,這裡會列出該活動專屬的提醒;如未設定,則表示尚未設定任何提醒。覆寫提醒數量上限為 5 個。 | 可寫入 |
reminders.overrides[].method |
string |
這項提醒使用的方法。可能的值包括:
新增提醒時為必填。 |
可寫入 |
reminders.overrides[].minutes |
integer |
活動開始時間前的分鐘數,以顯示提醒。有效值介於 0 到 40320 之間 (4 週以分鐘為單位)。 新增提醒時為必填。 |
可寫入 |
reminders.useDefault |
boolean |
是否將日曆的預設提醒套用至活動。 | 可寫入 |
sequence |
integer |
其序號。 | 可寫入 |
source.title |
string |
來源標題;例如網頁或電子郵件主旨 | 可寫入 |
source.url |
string |
指向資源的來源網址。網址配置必須為 HTTP 或 HTTPS。 | 可寫入 |
start.date |
date |
如果這是全天活動,請採用「yyyy-mm-dd」格式的日期。 | 可寫入 |
start.dateTime |
datetime |
採用合併的日期時間值 (根據 RFC3339 格式) 表示的時間。除非在 timeZone 中明確指定時區,否則必須使用時區偏移。 |
可寫入 |
start.timeZone |
string |
指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「歐洲/蘇黎世」)。如果是週期性活動,則此為必要欄位,用於指定重複期間展開的時區。如果是單一活動,此為選填欄位,用來表示活動開始/結束的自訂時區。 | 可寫入 |
status |
string |
事件的狀態。選用設定。可能的值包括:
|
可寫入 |
summary |
string |
活動名稱。 | 可寫入 |
transparency |
string |
活動是否在日曆上造成時段限制。選用設定。可能的值包括:
|
可寫入 |
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 |
工作地點的類型。可能的值包括:
新增工作地點屬性時為必填。 |
可寫入 |
回應
如果成功,這個方法會在回應主體中傳回事件資源。
範例
注意:這個方法適用的程式語言眾多,我們只在此提供部分程式碼範例,完整的支援語言清單請參閱用戶端程式庫頁面。
Java
使用 Java 用戶端程式庫。
import com.google.api.services.calendar.Calendar; import com.google.api.services.calendar.model.Event; // ... // Initialize Calendar service with valid OAuth credentials Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials) .setApplicationName("applicationName").build(); // Retrieve the event from the API Event event = service.events().get("primary", "eventId").execute(); // Make a change event.setSummary("Appointment at Somewhere"); // Update the event Event updatedEvent = service.events().update("primary", event.getId(), event).execute(); System.out.println(updatedEvent.getUpdated());
Python
使用 Python 用戶端程式庫。
# First retrieve the event from the API. event = service.events().get(calendarId='primary', eventId='eventId').execute() event['summary'] = 'Appointment at Somewhere' updated_event = service.events().update(calendarId='primary', eventId=event['id'], body=event).execute() # Print the updated date. print updated_event['updated']
PHP
使用 PHP 用戶端程式庫。
// First retrieve the event from the API. $event = $service->events->get('primary', 'eventId'); $event->setSummary('Appointment at Somewhere'); $updatedEvent = $service->events->update('primary', $event->getId(), $event); // Print the updated date. echo $updatedEvent->getUpdated();
小茹
使用 Ruby 用戶端程式庫。
event = client.get_event('primary', 'eventId') event.summary = 'Appointment at Somewhere' result = client.update_event('primary', event.id, event) print result.updated
試試看!
使用下方的 APIs Explorer,針對即時資料呼叫這個方法,看看會有什麼結果。