Events: import

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

匯入事件。這項操作可用於將現有活動的私人副本新增到日曆中。 立即試用或查看範例。

要求

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

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

要求主體

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

資源名稱 值 說明 Notes
必要屬性
end nested object 活動的 (專屬) 結束時間。如果是週期性活動，這是指第一個執行個體的結束時間。
iCalUID string 事件專屬 ID，如 RFC5545 所定義。這項功能可用來識別跨日曆系統的不同活動，且在透過 import 方法匯入活動時，也必須使用這個欄位。

請注意，iCalUID 和 id 並不相同，且在建立事件時應提供其中一個。語意的不同之處在於，在週期性事件中，單一事件的所有例項都會有不同的 id，而這些事件都共用相同的 iCalUID。如要使用其 iCalUID 擷取事件，請使用 ID 參數呼叫 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 與其他參與者的日曆活動之間共用的資源。 可寫入
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 時區資料庫名稱，例如「歐洲/蘇黎世」)。如果是週期性活動，則此為必填欄位，並指定展開週期所在的時區。如果是單一事件，這個欄位為選填，表示活動開始/結束的自訂時區。 可寫入
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 用戶端程式庫。

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 針對即時資料呼叫這個方法，並查看回應。