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，並且支援使用 meetData 的 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 活動的顏色。這是參照色彩定義 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」：提醒會透過使用者介面彈出式視窗傳送。

新增提醒時必填。

 可寫入
reminders.overrides[].minutes integer 活動開始前的分鐘數。有效值介於 0 到 40320 (以分鐘為單位) 之間。

新增提醒時必填。

 可寫入
reminders.useDefault boolean 是否要將日曆的預設提醒套用至活動。 可寫入
sequence integer 序號如 i Calendar。 可寫入
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」：該活動已取消 (刪除)。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」：這是私人活動。因為相容性因素，系統會提供這個值。
 可寫入

回應

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

示例

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

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

使用 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，針對有效資料呼叫這個方法，然後查看回應。