本頁面由 Cloud Translation API 翻譯而成。

事件類型

本頁說明 eventType 屬性，以及 Google 日曆 API 中可用的事件類型規格。

Google 日曆可讓使用者建立一般活動，以及針對特定用途設計的活動，並附加自訂屬性。

您可以在 API 的下列位置找到事件類型：

所有事件都會隨 eventType 傳回。
建立或更新事件資源時，需要設定 eventType。如果未設定，系統會使用 'default' 類型。
您可以在 Events:list 呼叫中指定 eventTypes，以列出特定類型的事件。如果沒有指定類型，系統就會傳回所有事件類型。
您可以在 Events:watch 呼叫中指定 eventTypes，以便訂閱特定類型事件的更新內容。如果未指定類型，要求會訂閱所有事件類型。

預設事件

系統會建立 default 事件類型的活動，並用做 Google 日曆 API 的主要資源之一。這些事件支援多種屬性，可用於進一步自訂事件。

請參閱「建立活動」一文，開始使用 Google 日曆活動。

生日

生日是一年一度的特殊全天活動。

使用者可以在 Google 日曆中手動建立生日活動。此外，當使用者在 Google 聯絡人中新增使用者並輸入對方的生日和其他重要日期後，生日資訊就會同步至 Google 日曆。使用者的生日也會從其 Google 帳戶個人資料同步至 Google 日曆。

Google 日曆 API 支援 get、instances 和 list 方法，可用於讀取生日活動。eventTypes 可設為 'birthday'，只列出生日活動。如果未指定類型，系統會將生日與所有其他事件類型一併列出。

在傳回的 Event 物件中，檢查 birthdayProperties 欄位，進一步瞭解這項特殊事件。birthdayProperties 包含下列欄位：

type：此特殊事件的類型，可能是生日、紀念日或其他重要日期。
customTypeName：使用者為此特殊事件指定的標籤。如果 type 設為 'custom'，就會填入這個值。
contact：與這項特殊事件連結的聯絡人資源名稱 (如果有的話)。格式為 'people/c12345'，可用於從 People API 擷取聯絡人詳細資料。

這個 API 可讓您使用 insert 方法建立生日活動，並遵循下列規格：

eventType 已設為 'birthday'。
start 和 end 欄位需要定義全天活動，時間範圍必須是整天。
visibility 欄位值必須為 'private'。
transparency 欄位值必須為 'transparent'。
需要每年重複，也就是說 recurrence 欄位必須是 'RRULE:FREQ=YEARLY'。2 月 29 日的生日事件必須採用下列重複規則：'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'。
可以包含 colorId、summary 和 reminders。
可包含 birthdayProperties。如果指定了 type，則必須為 'birthday'，且 customTypeName 和 contact 都必須為空白。
無法包含任何其他事件屬性。

這個 API 可讓您使用 update 和 patch 方法，更新生日事件的 colorId、summary 和 reminders。您也可以更新 start 和 end 欄位，變更活動日期。在這種情況下，新值必須定義全天活動，活動時間必須橫跨整整一天。如果生日活動已連結至 contact，或是其 type 為 'self'，就無法更新生日活動的時間詳細資料。

Google Calendar API 不允許使用自訂 birthdayProperties 建立生日活動，或更新這些屬性。您可以使用 People API 編輯重要日期，系統會將變更內容同步至 Google 日曆。同樣地，使用者也可以在 Google 帳戶個人資料中編輯自己的生日，系統會將生日資訊同步至 Google 日曆。

如果要求嘗試以不支援的方式建立或更新生日，將會失敗。在這種情況下，請檢查錯誤訊息，找出問題所在。

這個 API 支援生日事件的 import 作業，但事件會匯入為預設事件。換句話說，eventType 會是 'default'。

API 支援 watch 方法，可訂閱 Google 日曆上的生日活動變更。eventTypes 可設為 'birthday'，以便訂閱生日活動的更新內容。如果未指定類型，系統就會訂閱所有事件類型，包括生日。

您可以使用 Google 日曆 API 的 delete 方法刪除生日活動。從 Google 日曆中刪除生日活動不會影響 Google 聯絡人或 Google 帳戶個人資料中的資料。

系統不支援使用 move 或 update 方法變更生日活動的主辦人。

Gmail 中的活動

由 Gmail 自動產生的活動具有 'fromGmail' 事件類型。

Google Calendar API 不允許使用 insert 方法建立這類活動。

這個 API 可使用 update 和 patch 方法更新 colorId、reminders、visibility、transparency、status、attendees、private 和 shared 擴充屬性。

這個 API 支援 get 和 list 方法，可讀取 Gmail 中的事件。eventTypes 可設為 'fromGmail'，只列出由 Gmail 產生的事件。如果未指定類型，系統就會將 Gmail 中的活動與所有其他活動類型一併列出。

這個 API 支援 watch 方法，可訂閱 Google 日曆中 Gmail 活動的變更。如果未指定類型，系統就會訂閱所有事件類型，包括 'fromGmail'。

您可以使用 Google Calendar API 的 delete 方法刪除 Gmail 中的活動。

系統不支援使用 move 或 update 方法，透過 Gmail 變更活動主辦人。

專注時間、不在辦公室狀態和工作地點

您可以使用 Google Calendar API 建立及管理顯示 Google 日曆使用者狀態的活動。

這些功能僅適用於主要日曆，且僅供部分 Google 日曆使用者使用。詳情請參閱「管理專注時間、不在辦公室狀態和工作地點事件」。

探索 Google Apps Script 中的事件類型

Google Apps Script 是一種以 JavaScript 為基礎的雲端指令碼設計語言，可讓您建構與 Google Workspace 整合的業務應用程式。您可以在以瀏覽器為基礎的程式碼編輯器中開發指令碼，並在 Google 伺服器上儲存及執行這些指令碼。如要開始使用 Apps Script 傳送要求至 Google Calendar API，請參閱 Google Apps Script 快速入門。

以下說明如何使用 Google Calendar API 做為 Google Apps Script 中的進階服務，讀取及管理事件。如需 Google Calendar API 資源和方法的完整清單，請參閱參考說明文件。

建立及設定指令碼

前往 script.google.com/create 建立指令碼。
在左側窗格中，點選「服務」旁的「新增服務」圖示。
選取「Google Calendar API」，然後按一下「新增」。
啟用後，API 會顯示在左側窗格中。您可以在編輯器中使用 Calendar 關鍵字，列出 API 中的可用方法和類別。

(選用) 更新 Google Cloud 專案

每個 Google Apps Script 專案都有一個關聯的 Google Cloud 專案。指令碼可以使用 Google Apps Script 自動建立的預設專案。如果您想使用自訂 Google Cloud 專案，請參閱「切換至其他標準 Cloud 專案」。設定 Google Cloud 專案後，請選取左側的「編輯器」圖示，返回程式碼編輯器。

在指令碼中新增程式碼

以下程式碼範例說明如何列出、讀取及建立具有不同 eventType 值的事件。

將下列程式碼貼到程式碼編輯器中。

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

更改下列內容：

CALENDAR_ID：要擷取及建立活動的日曆電子郵件地址。這個常數最初會設為 'primary'，這是用來存取已登入使用者主要日曆的關鍵字。變更這個值可讓您讀取您有權存取的其他使用者日曆上的活動。
EVENT_ID：事件 ID。您可以呼叫 Events:list 擷取事件 ID。

執行程式碼範例

在程式碼編輯器上方，從下拉式選單中選取要執行的函式，然後按一下「Run」。
首次執行時，系統會提示您授權存取權。查看並允許 Apps Script 存取您的日曆。
您可以在視窗底部的「Execution Log」中，檢查指令碼執行結果。