擴充屬性

Events 資源的欄位涵蓋與活動相關的最常見資料，例如地點、開始時間等，但應用程式可能想儲存特定用途的其他中繼資料。Calendar API 可讓您為活動設定隱藏的鍵/值組合，稱為擴充屬性。擴充屬性可讓您輕鬆儲存事件的應用程式專屬資料，不必使用外部資料庫。

顯示設定

擴充屬性有兩種：私人和共用。 活動的所有參與者都能查看及編輯共用屬性，而私人屬性則會設定在活動的「副本」中，只有該參與者能存取。具體來說，私人屬性專屬於要求中使用的 calendarId 和 eventId，而共用屬性則會顯示，無論要求中使用哪個 calendarId 都一樣。

新增及更新房源

擴充屬性是在 Events 資源上設定，與其他欄位一樣，可以在 insert、update 和 patch 要求中設定。建議使用 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」privateExtendedProperty或「sharedExtendedProperty」sharedExtendedProperty欄位設為 propertyName=value 格式的限制，分別搜尋私人和共用屬性。以下範例會傳回具有私有屬性 petsAllowed=yes 的事件：

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

您可以多次重複這些欄位，且限制會以 OR 運算子合併，因此只要事件符合其中一項限制，就會傳回。以下範例會找出具有私有屬性 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 個屬性包括活動所有「副本」的共用和私人屬性。