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

事件類型

本頁說明 eventType 屬性，以及 Google Calendar API 提供的事件類型規格。

Google 日曆可讓使用者建立一般活動，以及專為特定用途設計且具備自訂屬性的活動。

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

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

預設活動

系統會建立 default 事件類型，並將其做為 Google Calendar API 的主要資源之一。這些事件支援各種屬性，可用於進一步自訂事件。

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

生日

生日是每年都會重複的全天特別活動。

使用者可以在 Google 日曆中手動建立生日活動。此外，使用者在 Google 聯絡人中新增聯絡人並加入生日和其他重要日期後，這些資訊就會同步到 Google 日曆。系統也會將使用者的生日從 Google 帳戶個人資料同步到 Google 日曆。

Google Calendar API 支援 get、instances 和 list 方法，可讀取生日活動。eventTypes 可以設為 'birthday'，只列出生日活動。如果沒有指定類型，生日就會與所有其他活動類型一起列出。

在傳回的 Event 物件中，檢查 birthdayProperties 欄位，進一步瞭解這項特別活動。birthdayProperties 具有以下欄位：

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

您可以使用 insert 方法，並按照下列規格，透過 API 建立生日活動：

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 Calendar API 的 delete 方法。從 Google 日曆刪除生日活動，不會影響 Google 聯絡人或 Google 帳戶個人資料中的資料。

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

Gmail 中的活動

從 Gmail 自動產生的活動會顯示 'fromGmail' 事件類型。

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

您可以使用 update 和 patch 方法，透過 API 更新 colorId、reminders、visibility、transparency、status、attendees、private 和 shared 擴充屬性。

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

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

如要刪除 Gmail 中的活動，請使用 Google Calendar API 的 delete 方法。

系統不支援使用 move 或 update 方法，變更 Gmail 中活動的主辦者。

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

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

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

探索 Google Apps Script 中的事件類型

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

下列操作說明介紹如何使用 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/workspace/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/workspace/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/workspace/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。

執行程式碼範例

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