要求
HTTP 要求
POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events
參數
參數名稱 | 值 | 說明 |
---|---|---|
路徑參數 | ||
calendarId |
string |
日曆 ID。如要擷取日曆 ID,請呼叫 calendarList.list 方法。如要存取目前登入使用者的主要日曆,請使用「primary 」關鍵字。
|
選用查詢參數 | ||
conferenceDataVersion |
integer |
API 用戶端支援的會議資料版本號碼。版本 0 會假設不支援會議資料,並忽略事件主體中的會議資料。版本 1 支援複製 ConferenceData,以及使用 conferenceData 的 createRequest 欄位建立新會議。預設值為 0。可接受的值介於 0 到 1 (包含這兩者) 之間。 |
maxAttendees |
integer |
回應中可納入的出席者人數上限。如果出席者人數超過指定數量,系統只會傳回參與者。選用。 |
sendNotifications |
boolean |
已淘汰,請改用 sendUpdates。 是否要傳送新事件建立通知。請注意,即使您將值設為 false ,系統仍可能會傳送部分電子郵件。預設為 false 。 |
sendUpdates |
string |
是否傳送新活動建立通知。請注意,部分電子郵件可能仍會傳送。預設為 false 。可接受的值如下:
|
supportsAttachments |
boolean |
執行操作的 API 用戶端是否支援事件附件。選用設定。預設值為 False。 |
授權
這項要求需要至少具備下列其中一個範圍的授權:
範圍 |
---|
https://www.googleapis.com/auth/calendar |
https://www.googleapis.com/auth/calendar.events |
詳情請參閱「驗證和授權」頁面。
要求主體
在要求主體中,請提供具有下列屬性的 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 |
與會者的回覆狀態。可能的值包括:
|
可寫入 |
birthdayProperties |
nested object |
生日或特殊活動資料。如果 eventType 為 "birthday" ,則會使用此屬性。不可變更。 |
可寫入 |
birthdayProperties.type |
string |
生日或特殊活動類型。可能的值包括:
"birthday" 的活動。活動建立後即無法變更類型。 |
可寫入 |
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」)。這個欄位適用於週期性活動,且為必填欄位,用來指定週期性活動的擴充時區。對於單一事件,這個欄位是選用的,可用於指定事件開始/結束時間的自訂時區。 | 可寫入 |
eventType |
string |
事件的具體類型。這項設定在活動建立後即無法變更。可能的值包括:
|
可寫入 |
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。 | 可寫入 |
id |
string |
事件的不明瞭識別碼。建立新的單一或週期性活動時,您可以指定活動 ID。提供的 ID 必須遵循下列規則:
如果您未指定 ID,系統會自動產生 ID。 請注意, |
可寫入 |
location |
string |
活動的地理位置,以任意形式顯示。選填。 | 可寫入 |
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 |
其序號。 | 可寫入 |
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 |
事件的瀏覽權限。選用設定。可能的值包括:
|
可寫入 |
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 |
工作地點類型。可能的值包括:
新增工作地點屬性時必須使用。 |
可寫入 |
回應
如果成功的話,這個方法會在回應內文中傳回 Events 資源。
範例
注意:這個方法適用的程式語言眾多,我們只在此提供部分程式碼範例,完整的支援語言清單請參閱用戶端程式庫頁面。
Java
使用 Java 用戶端程式庫。
// Refer to the Java quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/java // Change the scope to CalendarScopes.CALENDAR and delete any stored // credentials. Event event = new Event() .setSummary("Google I/O 2015") .setLocation("800 Howard St., San Francisco, CA 94103") .setDescription("A chance to hear more about Google's developer products."); DateTime startDateTime = new DateTime("2015-05-28T09:00:00-07:00"); EventDateTime start = new EventDateTime() .setDateTime(startDateTime) .setTimeZone("America/Los_Angeles"); event.setStart(start); DateTime endDateTime = new DateTime("2015-05-28T17:00:00-07:00"); EventDateTime end = new EventDateTime() .setDateTime(endDateTime) .setTimeZone("America/Los_Angeles"); event.setEnd(end); String[] recurrence = new String[] {"RRULE:FREQ=DAILY;COUNT=2"}; event.setRecurrence(Arrays.asList(recurrence)); EventAttendee[] attendees = new EventAttendee[] { new EventAttendee().setEmail("lpage@example.com"), new EventAttendee().setEmail("sbrin@example.com"), }; event.setAttendees(Arrays.asList(attendees)); EventReminder[] reminderOverrides = new EventReminder[] { new EventReminder().setMethod("email").setMinutes(24 * 60), new EventReminder().setMethod("popup").setMinutes(10), }; Event.Reminders reminders = new Event.Reminders() .setUseDefault(false) .setOverrides(Arrays.asList(reminderOverrides)); event.setReminders(reminders); String calendarId = "primary"; event = service.events().insert(calendarId, event).execute(); System.out.printf("Event created: %s\n", event.getHtmlLink());
Python
使用 Python 用戶端程式庫。
# Refer to the Python quickstart on how to setup the environment: # https://developers.google.com/calendar/quickstart/python # Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any # stored credentials. event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'}, ], 'reminders': { 'useDefault': False, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10}, ], }, } event = service.events().insert(calendarId='primary', body=event).execute() print 'Event created: %s' % (event.get('htmlLink'))
PHP
使用 PHP 用戶端程式庫。
// Refer to the PHP quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/php // Change the scope to Google_Service_Calendar::CALENDAR and delete any stored // credentials. $event = new Google_Service_Calendar_Event(array( 'summary' => 'Google I/O 2015', 'location' => '800 Howard St., San Francisco, CA 94103', 'description' => 'A chance to hear more about Google\'s developer products.', 'start' => array( 'dateTime' => '2015-05-28T09:00:00-07:00', 'timeZone' => 'America/Los_Angeles', ), 'end' => array( 'dateTime' => '2015-05-28T17:00:00-07:00', 'timeZone' => 'America/Los_Angeles', ), 'recurrence' => array( 'RRULE:FREQ=DAILY;COUNT=2' ), 'attendees' => array( array('email' => 'lpage@example.com'), array('email' => 'sbrin@example.com'), ), 'reminders' => array( 'useDefault' => FALSE, 'overrides' => array( array('method' => 'email', 'minutes' => 24 * 60), array('method' => 'popup', 'minutes' => 10), ), ), )); $calendarId = 'primary'; $event = $service->events->insert($calendarId, $event); printf('Event created: %s\n', $event->htmlLink);
小茹
使用 Ruby 用戶端程式庫。
event = Google::Apis::CalendarV3::Event.new( summary: 'Google I/O 2015', location: '800 Howard St., San Francisco, CA 94103', description: 'A chance to hear more about Google\'s developer products.', start: Google::Apis::CalendarV3::EventDateTime.new( date_time: '2015-05-28T09:00:00-07:00', time_zone: 'America/Los_Angeles' ), end: Google::Apis::CalendarV3::EventDateTime.new( date_time: '2015-05-28T17:00:00-07:00', time_zone: 'America/Los_Angeles' ), recurrence: [ 'RRULE:FREQ=DAILY;COUNT=2' ], attendees: [ Google::Apis::CalendarV3::EventAttendee.new( email: 'lpage@example.com' ), Google::Apis::CalendarV3::EventAttendee.new( email: 'sbrin@example.com' ) ], reminders: Google::Apis::CalendarV3::Event::Reminders.new( use_default: false, overrides: [ Google::Apis::CalendarV3::EventReminder.new( reminder_method: 'email', minutes: 24 * 60 ), Google::Apis::CalendarV3::EventReminder.new( reminder_method: 'popup', minutes: 10 ) ] ) ) result = client.insert_event('primary', event) puts "Event created: #{result.html_link}"
.NET
使用 .NET 用戶端程式庫。
// Refer to the .NET quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/dotnet // Change the scope to CalendarService.Scope.Calendar and delete any stored // credentials. Event newEvent = new Event() { Summary = "Google I/O 2015", Location = "800 Howard St., San Francisco, CA 94103", Description = "A chance to hear more about Google's developer products.", Start = new EventDateTime() { DateTime = DateTime.Parse("2015-05-28T09:00:00-07:00"), TimeZone = "America/Los_Angeles", }, End = new EventDateTime() { DateTime = DateTime.Parse("2015-05-28T17:00:00-07:00"), TimeZone = "America/Los_Angeles", }, Recurrence = new String[] { "RRULE:FREQ=DAILY;COUNT=2" }, Attendees = new EventAttendee[] { new EventAttendee() { Email = "lpage@example.com" }, new EventAttendee() { Email = "sbrin@example.com" }, }, Reminders = new Event.RemindersData() { UseDefault = false, Overrides = new EventReminder[] { new EventReminder() { Method = "email", Minutes = 24 * 60 }, new EventReminder() { Method = "sms", Minutes = 10 }, } } }; String calendarId = "primary"; EventsResource.InsertRequest request = service.Events.Insert(newEvent, calendarId); Event createdEvent = request.Execute(); Console.WriteLine("Event created: {0}", createdEvent.HtmlLink);
Go
使用 Go 用戶端程式庫。
// Refer to the Go quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/go // Change the scope to calendar.CalendarScope and delete any stored credentials. event := &calendar.Event{ Summary: "Google I/O 2015", Location: "800 Howard St., San Francisco, CA 94103", Description: "A chance to hear more about Google's developer products.", Start: &calendar.EventDateTime{ DateTime: "2015-05-28T09:00:00-07:00", TimeZone: "America/Los_Angeles", }, End: &calendar.EventDateTime{ DateTime: "2015-05-28T17:00:00-07:00", TimeZone: "America/Los_Angeles", }, Recurrence: []string{"RRULE:FREQ=DAILY;COUNT=2"}, Attendees: []*calendar.EventAttendee{ &calendar.EventAttendee{Email:"lpage@example.com"}, &calendar.EventAttendee{Email:"sbrin@example.com"}, }, } calendarId := "primary" event, err = srv.Events.Insert(calendarId, event).Do() if err != nil { log.Fatalf("Unable to create event. %v\n", err) } fmt.Printf("Event created: %s\n", event.HtmlLink)
JavaScript
// Refer to the JavaScript quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/js // Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any // stored credentials. var event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles' }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles' }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'} ], 'reminders': { 'useDefault': false, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10} ] } }; var request = gapi.client.calendar.events.insert({ 'calendarId': 'primary', 'resource': event }); request.execute(function(event) { appendPre('Event created: ' + event.htmlLink); });
Node.js
使用 Node.js 用戶端程式庫。
// Refer to the Node.js quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/node // Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any // stored credentials. var event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'}, ], 'reminders': { 'useDefault': false, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10}, ], }, }; calendar.events.insert({ auth: auth, calendarId: 'primary', resource: event, }, function(err, event) { if (err) { console.log('There was an error contacting the Calendar service: ' + err); return; } console.log('Event created: %s', event.htmlLink); });
試試看!
您可以使用下方的 API Explorer,針對即時資料呼叫這個方法,然後查看回應。