匯入事件。這個作業可將現有活動的私人副本新增至日曆。您只能匯入 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 |
事件專屬 ID,如 RFC5545 中所定義。這項 ID 可用於在日曆系統中唯一識別事件,並須在透過import方法匯入事件時提供。 請注意, |
|
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 時區資料庫名稱,例如「Europe/Zurich」)。這個欄位適用於週期性活動,且為必填欄位,用來指定週期性活動的擴充時區。對於單一事件,這個欄位是選用的,可用於指定事件開始/結束時間的自訂時區。 | 可寫入 |
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 |
活動的地理位置,格式為自由格式文字。選填。 | 可寫入 |
organizer |
object |
活動主辦人。如果主辦人也是與會者,attendees 中會有個別的項目,且 organizer 欄位設為 True。如要變更主辦人,請使用「move」運算子。唯讀,但匯入事件時除外。 |
可寫入 |
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 |
如 RFC5545 所述,這是重複事件的 RRULE、EXRULE、RDATE 和 EXDATE 列清單。請注意,這個欄位不允許使用 DTSTART 和 DTEND 行;事件開始和結束時間已在 start 和 end 欄位中指定。對於單一事件或週期性事件的個例,則省略這個欄位。 |
可寫入 |
reminders.overrides[] |
list |
如果活動未使用預設提醒,這裡會列出該活動專屬的提醒事項;如果未設定提醒事項,則表示系統未為此活動設定提醒事項。覆寫提醒的數量上限為 5 個。 | 可寫入 |
reminders.overrides[].method |
string |
提醒事項使用的提醒方法。可能的值包括:
新增提醒時必填。 |
可寫入 |
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 |
事件的狀態。選用設定。可能的值包括:
|
可寫入 |
summary |
string |
事件的名稱。 | 可寫入 |
transparency |
string |
活動是否會在日曆上阻擋時間。選用設定。可能的值包括:
|
可寫入 |
visibility |
string |
事件的瀏覽權限。選用設定。可能的值包括:
|
可寫入 |
回應
如果成功的話,這個方法會在回應內文中傳回 Events 資源。
範例
注意:這個方法適用的程式語言眾多,我們只在此提供部分程式碼範例,完整的支援語言清單請參閱用戶端程式庫頁面。
Java
使用 Java 用戶端程式庫。
import com.google.api.services.calendar.Calendar; import com.google.api.services.calendar.model.Event; import com.google.api.services.calendar.model.EventAttendee; import com.google.api.services.calendar.model.EventDateTime; import com.google.api.client.util.DateTime; import java.util.Date; // ... // Initialize Calendar service with valid OAuth credentials Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials) .setApplicationName("applicationName").build(); // Create and initialize a new event (could also retrieve an existing event) Event event = new Event(); event.setICalUID("originalUID"); Event.Organizer organizer = new Event.Organizer(); organizer.setEmail("organizerEmail"); organizer.setDisplayName("organizerDisplayName"); event.setOrganizer(organizer); ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>(); attendees.add(new EventAttendee().setEmail("attendeeEmail")); // ... event.setAttendees(attendees); Date startDate = new Date(); Date endDate = new Date(startDate.getTime() + 3600000); DateTime start = new DateTime(startDate, TimeZone.getTimeZone("UTC")); event.setStart(new EventDateTime().setDateTime(start)); DateTime end = new DateTime(endDate, TimeZone.getTimeZone("UTC")); event.setEnd(new EventDateTime().setDateTime(end)); // Import the event into a calendar Event importedEvent = service.events().calendarImport('primary', event).execute(); System.out.println(importedEvent.getId());
Python
使用 Python 用戶端程式庫。
event = { 'summary': 'Appointment', 'location': 'Somewhere', 'organizer': { 'email': 'organizerEmail', 'displayName': 'organizerDisplayName' }, 'start': { 'dateTime': '2011-06-03T10:00:00.000-07:00' }, 'end': { 'dateTime': '2011-06-03T10:25:00.000-07:00' }, 'attendees': [ { 'email': 'attendeeEmail', 'displayName': 'attendeeDisplayName', }, # ... ], 'iCalUID': 'originalUID' } imported_event = service.events().import_(calendarId='primary', body=event).execute() print imported_event['id']
PHP
使用 PHP 用戶端程式庫。
$event = new Google_Service_Calendar_Event(); $event->setSummary('Appointment'); $event->setLocation('Somewhere'); $start = new Google_Service_Calendar_EventDateTime(); $start->setDateTime('2011-06-03T10:00:00.000-07:00'); $event->setStart($start); $end = new Google_Service_Calendar_EventDateTime(); $end->setDateTime('2011-06-03T10:25:00.000-07:00'); $event->setEnd($end); $attendee1 = new Google_Service_Calendar_EventAttendee(); $attendee1->setEmail('attendeeEmail'); // ... $attendees = array($attendee1, // ..., ); $event->attendees = $attendees; $organizer = new Google_Service_Calendar_EventOrganizer(); $organizer->setEmail('organizerEmail'); $organizer->setDisplayName('organizerDisplayName'); $event->setOrganizer($organizer); $event->setICalUID('originalUID'); $importedEvent = $service->events->import('primary', $event); echo $importedEvent->getId();
小茹
使用 Ruby 用戶端程式庫。
event = Google::Apis::CalendarV3::Event.new( summary: 'Appointment', location: 'Somewhere', organizer: { email: 'organizerEmail', display_name: 'organizerDisplayName' }, start: { date_time: '2011-06-03T10:00:00.000-07:00' }, end: { date_time: '2011-06-03T10:25:00.000-07:00' }, attendees: [ { email: 'attendeeEmail', display_name: 'attendeeDisplayName', }, # ... ], i_cal_uid: 'originalUID' ) result = client.import_event('primary', event) print result.id
試試看!
您可以使用下方的 API Explorer,針對即時資料呼叫這個方法,然後查看回應。