Events: update

更新活動。這個方法不支援修補語意,而且一律會更新整個事件資源。如要進行部分更新,請先執行 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。可接受的值為 01 (含頭尾)。
maxAttendees integer 回應的參與者人數上限。如果參與者人數超過指定人數,系統只會傳回參與者。選填。
sendNotifications boolean 已淘汰,請改用 sendUpdates

指定是否要傳送事件更新的通知 (例如說明變更等)。請注意,即使您將值設為 false,系統仍可能會傳送某些電子郵件。預設值為 false
sendUpdates string 應接收活動更新通知 (例如標題變更等) 的邀請對象。

可接受的值為:
  • all」:系統會將通知傳送給所有邀請對象。
  • externalOnly」:通知只會傳送給非 Google 日曆邀請對象。
  • none」:不傳送任何通知。如果是日曆遷移工作,請考慮改用 Events.import 方法。
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 中 Files 資源 alternateLink 屬性相同的格式。

新增附件時必須提供。

可寫入
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 參與者的回覆狀態。可能的值包括:
  • needsAction」:參與者尚未回覆邀請 (建議用於新活動)。
  • declined」:這名參與者已拒絕邀請。
  • tentative」:參與者已暫時接受邀請。
  • accepted」:這名參與者已接受邀請。
可寫入
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 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,則為必填欄位,並指定重複活動的時區。如果是單一活動,則為選填欄位,用來表示活動開始/結束的自訂時區。 可寫入
extendedProperties.private object 這個日曆上活動副本的私人屬性。 可寫入
extendedProperties.shared object 在其他參與者日曆的活動副本之間共用的屬性。 可寫入
focusTimeProperties nested object 專注時間事件資料。在 eventTypefocusTime 時使用。 可寫入
gadget.display string 小工具的顯示模式。已淘汰,可能的值包括:
  • icon」:在日曆檢視畫面中,這個小工具會顯示在活動標題旁邊。
  • chip」:按下事件後會顯示這個小工具。
可寫入
gadget.height integer 小工具的高度 (以像素為單位)。高度須為大於 0 的整數。選用設定。已淘汰。 可寫入
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 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,則為必填欄位,並指定重複活動的時區。如果是單一活動,則為選填欄位,用來表示活動開始/結束的自訂時區。 可寫入
outOfOfficeProperties nested object 「不在辦公室」的活動資料。在 eventTypeoutOfOffice 時使用。 可寫入
recurrence[] list 週期性事件的 RRULE、EXRULE、RDATE 和 EXDATE 行清單,如 RFC5545 中指定。請注意,這個欄位中不允許使用 DTSTART 和 DTEND 行;活動的開始和結束時間需在 startend 欄位中指定。若是單一活動或週期性活動,則會忽略這個欄位。 可寫入
reminders.overrides[] list 如果活動並未使用預設提醒,這裡會列出該活動專屬的提醒;如未設定,則會指出該活動尚未設定提醒。覆寫提醒數量上限為 5 個。 可寫入
reminders.overrides[].method string 這則提醒使用的方法。可能的值包括:
  • email」:系統會透過電子郵件傳送提醒。
  • popup」:會透過使用者介面彈出式視窗傳送提醒。

新增提醒時必須提供。

可寫入
reminders.overrides[].minutes integer 活動開始前的分鐘數,應在活動開始之前觸發。有效值介於 0 到 40320 (4 週以分鐘為單位) 之間。

新增提醒時必須提供。

可寫入
reminders.useDefault boolean 日曆的預設提醒是否適用於活動。 可寫入
sequence integer 每個 i Calendar 的序號。 可寫入
source.title string 來源的標題,例如網頁標題或電子郵件主旨。 可寫入
source.url string 指向資源的來源網址。網址配置必須是 HTTP 或 HTTPS。 可寫入
start.date date 如果是全天活動,日期,格式為「yyyy-mm-dd」。 可寫入
start.dateTime datetime 時間,採用合併日期時間值 (根據 RFC3339 格式化)。除非 timeZone 中明確指定時區,否則必須提供時區偏移。 可寫入
start.timeZone string 指定時間的時區。(格式為 IANA 時區資料庫名稱,例如「Europe/Zurich」)。如果是週期性活動,則為必填欄位,並指定重複活動的時區。如果是單一活動,則為選填欄位,用來表示活動開始/結束的自訂時區。 可寫入
status string 活動狀態。選用設定。可能的值包括:
  • confirmed」- 已確認活動。此為預設狀態。
  • tentative」:已暫時確認活動。
  • cancelled」:活動已取消 (已刪除)。list 方法只會在漸進式同步 (指定 syncTokenupdatedMin) 或 showDeleted 旗標設為 true 時傳回取消的事件。get 方法一律會傳回這些函式。

    根據事件類型,取消狀態代表兩種狀態:

    1. 因未取消週期性事件而取消的例外狀況,表示我們不應再向使用者顯示這個執行個體。用戶端應在父項週期性活動的生命週期中儲存這些事件。

      已取消的例外狀況保證將填入 idrecurringEventIdoriginalStartTime 欄位的值。其他欄位可能是空白的。

    2. 所有其他已取消的活動都代表已刪除的活動。用戶端應移除本機已同步處理的副本。這類取消的活動最終會消失,因此請勿無限期保留這些活動。

      已刪除的活動只能保證 id 欄位填入資料。

    發起人的日曆會繼續顯示已取消的活動,例如摘要、位置等,讓使用者可以還原 (取消刪除) 活動。同樣地,使用者受邀以及手動移除的活動仍會持續提供詳細資訊。不過,將 showDeleted 設為 false 的漸進式同步處理要求不會傳回這些詳細資料。

    如果活動變更主辦者 (例如透過移動作業),而原始發起人不在參與者名單中,就會在取消活動後離開,且保證只會填入 id 欄位。

可寫入
summary string 活動名稱。 可寫入
transparency string 該活動是否封鎖日曆上的時間。選用設定。可能的值包括:
  • opaque」- 預設值。該活動會在日曆上封鎖時間。這等同於在 Google 日曆 UI 中將「狀態顯示為」設為「忙碌」
  • transparent」- 活動未在日曆上封鎖時間。這等同於在 Google 日曆 UI 中將「狀態顯示方式」設為「有空」
可寫入
visibility string 活動的顯示設定。選用設定。可能的值包括:
  • default」:使用日曆上活動的預設顯示設定。這是預設值。
  • public」- 活動公開,且日曆的所有讀者都能看到活動詳細資訊。
  • private」:這是私人活動,只有活動參與者可以查看活動詳細資訊。
  • confidential」:這是私人活動。系統會基於相容性考量提供這個值。
可寫入
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 工作地點類型。可能的值包括:
  • homeOffice」- 使用者在家工作。
  • officeLocation」:使用者在辦公室工作。
  • customLocation」- 使用者從自訂位置工作。
所有詳細資料皆已指定於指定名稱的子欄位,但留空可能會留空。系統會忽略任何其他欄位。

新增工作地點屬性時為必填。

可寫入

回應

如果成功,這個方法會在回應主體中傳回事件資源

範例

注意:這個方法適用的程式語言眾多,我們只在此提供部分程式碼範例,完整的支援語言清單請參閱用戶端程式庫頁面

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

使用 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,針對即時資料呼叫這個方法,然後查看回應。