扩展属性

Events 资源的字段涵盖与事件相关联的最常见数据，例如地点、开始时间等，但应用可能需要存储特定于其用例的其他元数据。Calendar API 支持为事件设置隐藏的键值对，称为扩展属性。借助扩展属性，您可以轻松存储事件的应用专用数据，而无需使用外部数据库。

公开范围

可用的扩展属性有两种类型：私享和共享。 共享属性对活动的所有参加者都是可见且可修改的，而私享属性则是在某位参加者的本地活动“副本”中设置的。更具体地说，私有属性仅适用于请求中使用的 calendarId 和 eventId，而无论请求中使用的 calendarId 如何，系统都会显示共享属性。

添加和更新房源

扩展属性是在 Events 资源上设置的，与其他字段一样，可以在 insert、update 和 patch 请求中进行设置。使用补丁请求是首选方法，因为您可以操控某些属性，同时不影响其他属性。添加具有相同键的新媒体资源会覆盖具有相同键的所有现有媒体资源。以下示例展示了如何设置私有属性：

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

删除媒体资源

更新请求中未包含的任何媒体资源都会被删除，但更好的方法是发出补丁请求，将值设为 null。以下示例展示了如何删除私有媒体资源：

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

不过请注意，私有属性和共享属性的约束条件会联接起来，因此事件必须同时符合这两组约束条件才能返回。以下示例会查找具有私有属性 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 个属性，总大小不得超过 32KB（键大小 + 值大小）。这 300 个属性包括事件的所有“副本”中的共享属性和私有属性。