擴充屬性

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

顯示設定

擴充屬性分為兩種:私人和共用。共用屬性可供活動的所有參與者查看及編輯,而私人屬性則會在參與者對活動的「副本」中設定。具體來說,私人屬性專屬於在要求中使用的 calendarIdeventId,而共用屬性則會不受在要求中使用的 calendarId 影響而顯示。

新增及更新房源

擴充屬性會在「事件」資源上設定,並可像其他欄位一樣,在插入更新修補要求中設定。使用修補要求是首選方法,因為您可以操作部分屬性,同時保留其他屬性不變。新增相同鍵的新資源,會覆寫任何具有相同鍵的現有資源。以下範例說明如何設定私人資源:

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 要求,根據事件的擴充屬性值搜尋事件。將欄位 privateExtendedPropertysharedExtendedProperty 設為 propertyName=value 格式的限制條件,分別針對私人和共用屬性進行搜尋。以下範例會傳回使用私人屬性 petsAllowed=yes 的事件:

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

您可以重複使用這些欄位,且限制條件會以 OR 連接,因此事件只需要符合其中一個限制條件即可傳回。以下範例會找出含有私人資源 petsAllowed=yesisOutside=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 個屬性包括共用和私人屬性,涵蓋事件的所有「副本」。