Events: import

匯入活動。這項作業用於將現有活動的私人副本新增至日曆。您只能匯入 eventType 為 default 的事件。

已淘汰的行為：如果匯入非 default 事件，系統會將其類型變更為 default，並捨棄可能有的任何事件類型專屬屬性。

立即試用。

要求

HTTP 要求

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events/import

參數

參數名稱 值 說明
路徑參數
calendarId string 日曆 ID。如要擷取日曆 ID，請呼叫 calendarList.list 方法。如要存取目前登入使用者的主要日曆，請使用「primary」關鍵字。
選用查詢參數
conferenceDataVersion integer API 用戶端支援的會議資料版本號碼。版本 0 假設不支援會議資料，並忽略活動主體中的會議資料。第 1 版支援複製 ConferenceData，以及使用 conferenceData 的 createRequest 欄位建立新會議。預設值為 0。 可接受介於 0 到 1 (包含這兩者) 之間的值。
supportsAttachments boolean 執行作業的 API 用戶端是否支援事件附件。(選用步驟) 預設值為 False。

授權

這項要求需要至少下列其中一個範圍的授權：

範圍
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.owned

詳情請參閱「驗證和授權」頁面。

要求主體

在要求內容中，請提供具有下列屬性的 Events 資源：

屬性名稱 值 說明 附註
必要屬性
end nested object 活動的結束時間 (不包含在內)。如果是週期性活動，這是指第一個例項的結束時間。
iCalUID string 符合 RFC5545 定義的事件專屬 ID。這個 ID 可用來在不同日曆系統中找出特定事件，透過 import 方法匯入事件時，必須提供這個 ID。

請注意，iCalUID 和 id 並不相同，建立事件時只能提供其中一個。兩者語意上的差異之一是，在週期性活動中，一個活動的所有例項都有不同的 id，但都共用相同的 iCalUID。如要使用 iCalUID 擷取事件，請使用 iCalUID 參數呼叫 events.list 方法。如要使用 id 擷取事件，請呼叫 events.get 方法。
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 活動的顏色。這是指顏色定義的 event 區段中的項目 ID (請參閱 顏色端點)。選填。 可寫入
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 專注時間活動資料。如果 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 活動的地理位置，格式不限。選填。 可寫入
organizer object 活動主辦人。如果主辦人也是與會者，attendees 中會顯示個別項目，且 organizer 欄位會設為 True。如要變更主辦人，請使用「移動」作業。唯讀，匯入活動時除外。 可寫入
organizer.displayName string 主辦者的名稱 (如有)。 可寫入
organizer.email string 主辦人的電子郵件地址 (如有)。必須是符合 RFC5322 規範的有效電子郵件地址。 可寫入
originalStartTime.date date 如果這是全天活動，則為日期，格式為「yyyy-mm-dd」。 可寫入
originalStartTime.dateTime datetime 時間，以合併的日期時間值表示 (格式符合 RFC3339)。除非在 timeZone 中明確指定時區，否則必須提供時區偏移量。 可寫入
originalStartTime.timeZone string 指定時間的時區。(格式為 IANA 時區資料庫名稱，例如「Europe/Zurich」)。如果是週期性活動，這個欄位為必填，並指定週期性活動展開的時區。如果是單一活動，這個欄位為選填，可指出活動開始/結束的自訂時區。 可寫入
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」：透過 UI 彈出式視窗傳送提醒。

新增提醒時必須填寫。

 可寫入
reminders.overrides[].minutes integer 提醒通知應在活動開始前幾分鐘觸發。有效值介於 0 和 40320 (4 週，以分鐘為單位)。

新增提醒時必須填寫。

 可寫入
reminders.useDefault boolean 日曆的預設提醒事項是否適用於活動。 可寫入
sequence integer iCalendar 格式的序號。 可寫入
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」- 活動已取消 (已刪除)。只有在增量同步時 (指定 syncToken 或 updatedMin 時)，或 showDeleted 旗標設為 true 時，list 方法才會傳回已取消的活動。get 方法一律會傳回這些項目。

    「已取消」狀態代表兩種不同情況，視活動類型而定：

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

      取消的例外狀況只保證會填入 id、recurringEventId 和 originalStartTime 欄位的值。其他欄位可能會空白。

    2. 其他取消的活動則代表已刪除的活動。請客戶移除本機同步處理的副本。這類取消的活動最終會消失，因此請勿依賴這些活動。

      系統只保證會填入已刪除事件的 id 欄位。

    在主辦者的日曆中，取消的活動仍會顯示活動詳細資料 (摘要、地點等)，方便主辦者還原 (取消刪除) 活動。同樣地，使用者受邀參加但手動移除的活動，仍會提供詳細資料。不過，如果將 showDeleted 設為 false，增量同步要求就不會傳回這些詳細資料。

    如果活動變更主辦人 (例如透過「移動」作業)，且原始主辦人不在參與者清單中，系統會留下已取消的活動，且只會填入 id 欄位。

 可寫入
summary string 活動名稱。 可寫入
transparency string 活動是否會占用日曆上的時間。(選用步驟) 可能的值包括：
  • 「opaque」- 預設值。活動會封鎖日曆上的時間。這相當於在日曆使用者介面中，將「顯示為」設定為「忙碌」。
  • 「transparent」：活動不會在日曆上封鎖時間。這相當於在日曆使用者介面中，將「顯示為」設定為「有空」。
 可寫入
visibility string 活動的顯示設定。(選用步驟) 可能的值包括：
  • 「default」：使用日曆中活動的預設瀏覽權限。這是預設值。
  • 「public」- 活動為公開，日曆的所有讀者都能查看活動詳細資料。
  • 「private」- 活動為私人活動，只有活動參與者可以查看活動詳細資料。
  • 「confidential」- 活動為私人活動。提供這個值是為了相容性。
 可寫入

回應

如果成功的話，這個方法會在回應內文中傳回 Events 資源。

試試看！

您可以使用下方的 API Explorer，針對即時資料呼叫這個方法，然後查看回應。