Events: insert

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立事件。立即試用或查看範例。

要求

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。

可接受的值如下：
  • 「all」：所有邀請對像都會收到通知。
  • 「externalOnly」：僅向非 Google 日曆邀請對象傳送通知。
  • 「none」：未傳送通知。
supportsAttachments boolean 執行作業的 API 用戶端是否支援事件附件。選用，預設值為 False。

授權

此要求需要至少具備下列其中一個範圍的授權：

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

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

要求主體

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

資源名稱 值 說明 Notes
必要屬性
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」：參與者已接受邀請。
 可寫入
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 與其他參與者的日曆活動之間共用的資源。 可寫入
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。 可寫入
id string 事件的不透明 ID。建立新的單一或週期性活動時，您可以指定活動 ID。提供的 ID 必須遵守下列規則：
  • ID 中可以使用的字元是 base32 十六進位編碼字元 (也就是小寫英文字母 a-v 和數字 0-9)，請參閱 RFC2938 中的第 3.1.2 節
  • ID 的長度必須介於 5 到 1024 個字元之間
  • 每個日曆的 ID 不得重複
由於系統的全面發布，我們不保證能在建立事件時偵測 ID 衝突。為了降低衝突的風險，建議您使用既定的 UUID 演算法 (如 RFC4122 中所述)。

如果您沒有指定 ID，則伺服器會自動產生。

請注意，icalUID 和 id 並不相同，且在建立事件時應提供其中一個。語意的不同之處在於，在週期性事件中，單一事件的所有例項都會有不同的 id，而這些事件都共用相同的 icalUID。

 可寫入
location string 以任意形式文字顯示活動的地理位置。選用。 可寫入
originalStartTime.date date 如果日期是全天活動，日期格式為「yyyy-mm-dd」。 可寫入
originalStartTime.dateTime datetime 時間，以日期/時間值合併顯示 (根據 RFC3339 的格式)。除非在 timeZone 中明確指定時區，否則必須設定時區偏移。 可寫入
originalStartTime.timeZone string 指定時間的時區。(格式為 IANA 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必填欄位，並指定展開週期所在的時區。如果是單一事件，這個欄位為選填，表示活動開始/結束的自訂時區。 可寫入
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 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必填欄位，並指定展開週期所在的時區。如果是單一事件，這個欄位為選填，表示活動開始/結束的自訂時區。 可寫入
status string 活動的狀態。選用，可能的值包括：
  • 「confirmed」：已確認活動。此為預設狀態。
  • "tentative" - 暫定活動。
  • 「cancelled」：活動已取消 (已刪除)。list 方法只會在漸進式同步處理作業 (指定 syncToken 或 updatedMin 時) 或 showDeleted 旗標設為 true 時，傳回已取消的事件。get 方法一律會傳回這些方法。

    視狀態類型而定，取消狀態可呈現兩種不同的狀態：

    1. 已取消的週期性活動中已取消的例外狀況，表示系統不應再對使用者顯示這個執行個體。客戶應在上層週期性事件的生命週期內儲存這些事件。

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

    2. 所有其他已取消的活動都代表已刪除的活動。用戶端應移除本機同步處理的複本。這類取消的活動最終會消失，因此請把握時間，避免造成這種情況。

      系統僅會確保刪除的已填入 id 欄位。

    在主辦人的日曆上，已取消的活動仍會顯示活動詳細資訊 (摘要、地點等)，方便使用者恢復活動。同樣地，使用者受邀及手動移除的活動仍會繼續提供詳細資訊。不過，將 showDeleted 設為 false 的漸進式同步處理要求不會傳回這些詳細資料。

    如果活動變更了主辦人 (例如透過移動作業)，但原始發起人不在與會者名單中，那麼系統會將已離開的活動取消，並只保證獲得 id 欄位。

 可寫入
summary string 活動的名稱。 可寫入
transparency string 活動是否封鎖了日曆上的時間。選用，可能的值包括：
  • 「opaque」：預設值。此活動確實封鎖了日曆上的時間。這相當於在日曆 UI 中將「顯示為」顯示為 [忙碌]。
  • 「transparent」：活動不會封鎖日曆上的時間。這相當於在日曆 UI 中將 [顯示為] 設為 [有空]。
 可寫入
visibility string 活動顯示設定。選用，可能的值包括：
  • 「default」：使用日曆上活動的預設顯示設定。這是預設值。
  • 「public」：這是公開的活動，日曆的所有讀者都可以查看活動詳細資訊。
  • 「private」：這是私人活動，只有活動參與者可以查看活動詳細資訊。
  • 「confidential」：這是私人活動。基於相容性考量，系統提供了這個值。
 可寫入

回應

如果成功，此方法會在回應主體中傳回 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

使用 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

使用 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);
});

試試看！

使用 APIs Explorer 針對即時資料呼叫這個方法，並查看回應。