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，以及使用會議資料的 createRequest 欄位建立新會議。預設值為 0。 可接受的值為 0 到 1 (含頭尾)。
supportsAttachments boolean API 用戶端執行作業是否支援事件附件。選用設定。預設值為 False。

授權

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

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

詳情請參閱「驗證與授權」網頁。

要求主體

在要求主體中，提供事件資源並附上以下屬性：

屬性名稱 值 說明 附註
必要屬性
end nested object 事件的結束時間 (不含)。如果是週期性活動，則這是指第一個活動的結束時間。
iCalUID string RFC5545 中定義的事件專屬 ID。可用於識別跨日曆系統的事件，且在透過 import 方法匯入事件時必須提供。

請注意，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 事件的顏色。此 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 活動的地理位置，以任意形式顯示。選填。 可寫入
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 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必要欄位，用於指定重複期間展開的時區。如果是單一活動，此為選填欄位，用來表示活動開始/結束的自訂時區。 可寫入
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」- 此為私人活動。系統會基於相容性因素提供這個值。
 可寫入

回應

如果成功，這個方法會在回應主體中傳回事件資源。

範例

注意：這個方法適用的程式語言眾多，我們只在此提供部分程式碼範例，完整的支援語言清單請參閱用戶端程式庫頁面。

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

試試看！

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