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。 可接受的值為 0 到 1 (含頭尾)。
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 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必要欄位，用於指定重複期間展開的時區。如果是單一活動，此為選填欄位，用來表示活動開始/結束的自訂時區。 可寫入
extendedProperties.private object 只有這個日曆的活動副本僅限使用的屬性。 可寫入
extendedProperties.shared object 其他參與者的活動副本共用的屬性日曆。 可寫入
focusTimeProperties nested object 專注時間事件資料。當 eventType 為 focusTime 時使用。 可寫入
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 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必要欄位，用於指定重複期間展開的時區。如果是單一活動，此為選填欄位，用來表示活動開始/結束的自訂時區。 可寫入
outOfOfficeProperties nested object 不在辦公室的事件資料。當 eventType 為 outOfOffice 時使用。 可寫入
recurrence[] list 週期性事件的 RRULE、EXRULE、RDATE 和 EXDATE 行清單，如 RFC5545 所指定。請注意，這個欄位不允許使用 DTSTART 和 DTEND 行；事件的開始與結束時間是在 start 和 end 欄位中指定。單一活動或週期性活動例項時，系統會略過這個欄位。 可寫入
reminders.overrides[] list 如果活動未使用預設提醒，這裡會列出該活動專屬的提醒；如未設定，則表示尚未設定任何提醒。覆寫提醒數量上限為 5 個。 可寫入
reminders.overrides[].method string 這項提醒使用的方法。可能的值包括：
  • 「email」- 系統會透過電子郵件傳送提醒。
  • 「popup」- 系統會透過使用者介面彈出式視窗傳送提醒。

新增提醒時為必填。

 可寫入
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 事件的狀態。選用設定。可能的值包括：
  • 「confirmed」- 已確認活動。此為預設狀態。
  • 「tentative」- 活動暫定已確認。
  • 「cancelled」- 活動已取消 (已刪除)。只有在指定 syncToken 或 updatedMin 或 showDeleted 旗標設為 true 時，list 方法才會傳回取消的事件。get 方法一律會傳回這些結果。

    取消狀態代表兩個不同狀態，具體取決於事件類型：

    1. 如果已取消的週期性事件發生已取消的例外狀況，代表系統不再向使用者顯示這個執行個體。客戶應在父項週期性活動的生命週期儲存這些事件。

      如果例外狀況遭取消，id、recurringEventId 和 originalStartTime 欄位的值才一定會填入值。其他欄位可能會留空。

    2. 而所有其他取消的活動則代表已刪除的活動。用戶端應移除已在本機同步處理的副本。這些取消的活動最終會消失，因此請勿持續使用。

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

    在發起人日曆中，已取消的活動會持續顯示活動詳細資料 (摘要、地點等)，方便您還原 (取消刪除)。同樣地，使用者受邀和手動移除的活動仍會提供詳細資料。不過，將 showDeleted 設為 false 的漸進式同步處理要求不會傳回這些詳細資料。

    如果活動有變更主辦方 (例如透過移動作業)，但原始發起人不在參與者清單中，系統會將已取消的活動留在已取消的活動後方，活動只能填入 id 欄位。

 可寫入
summary string 活動名稱。 可寫入
transparency string 活動是否在日曆上造成時段限制。選用設定。可能的值包括：
  • 「opaque」- 預設值。這個活動確實會在日曆上封鎖時段。等同於在日曆 UI 中將「我的顯示狀態」設為「忙碌」。
  • 「transparent」- 活動不會在日曆上浪費時間。等同於在日曆 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 用戶端程式庫。

event = client.get_event('primary', 'eventId')
event.summary = 'Appointment at Somewhere'
result = client.update_event('primary', event.id, event)
print result.updated

試試看！

使用下方的 APIs Explorer，針對即時資料呼叫這個方法，看看會有什麼結果。