擴充屬性

事件資源的欄位包含最常見的事件相關資料，例如位置、開始時間等，但應用程式可能需要儲存其用途專屬的其他中繼資料。Calendar API 能透過稱為「延伸屬性」的事件設定隱藏鍵/值組合。擴充屬性可讓您輕鬆儲存事件的應用程式特定資料，而不必使用外部資料庫。

顯示設定

可用的擴充屬性分為兩種類型：私人和共用。共用屬性可供活動的所有參與者查看和編輯，而私人屬性則可設為一名參與者的本機「副本」設定。具體來說，不公開屬性是針對要求中使用的 calendarId 和 eventId 所專有，而無論要求中使用的 calendarId 為何，都會顯示共用屬性。

新增及更新房源

擴充屬性是在事件資源上設定，就像其他欄位一樣，可在 insert、update 和 patch 要求中設定。建議您使用修補要求的方式，因為這樣您可以控制某些屬性，同時保留其他屬性。新增具有相同金鑰的新屬性會覆寫所有具有相同金鑰的現有屬性。以下範例說明如何設定私人屬性：

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

刪除屬性

任何未包含在更新要求中的屬性都會遭到刪除，但更好的方式是提出修補程式要求，將值設為空值。以下範例說明如何刪除私人屬性：

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

搜尋房源

您可以使用 Events.list 要求根據擴充屬性的值搜尋事件。將 privateExtendedProperty 或 sharedExtendedProperty 欄位設為以 propertyName=value 格式的限制，即可分別搜尋私人和共用屬性。以下範例傳回含有私人屬性 petsAllowed=yes 的事件：

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

您可以多次重複這些欄位，而且限制條件會一起進行，因此事件只需要符合其中一個限制條件即可傳回。以下範例會尋找含有私人屬性 petsAllowed=yes 或 isOutside=yes 的事件：

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

請注意，私人屬性和共用屬性的限制會以 AND 結合在一起，因此事件必須與兩組限制條件相符才能傳回。以下範例會尋找含有私人屬性 petsAllowed=yes 和公開屬性 createdBy=myApp 的事件：

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

限制

  1. 屬性鍵的大小上限為 44 個字元，含有較長索引鍵的屬性將自動捨棄，不另行通知。
  2. 屬性值的大小上限為 1024 個字元，且值較長的屬性會以無訊息的方式截斷。
  3. 一個事件最多可有 300 個屬性，大小總計為 32 KB (鍵大小 + 值大小)。這 300 項資源包含事件所有「副本」的共用和私人屬性。