扩展属性

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

公开范围

扩展属性有两种类型:私有和共享。 活动的所有参加者都可以查看和修改共享属性,而私有属性则设置在参加者本地的活动“副本”中。更具体地说,私有属性特定于请求中使用的 calendarIdeventId,而无论请求中使用的是哪个 calendarId,系统都会显示共享属性。

添加和更新房源

扩展属性是在 Events 资源上设置的,与其他字段一样,可以在 insertupdatepatch 请求中设置。建议使用 PATCH 请求,因为这样您可以在不影响其他属性的情况下操控部分属性。添加具有相同键的新属性会覆盖具有相同键的所有现有属性。以下示例展示了如何设置私有属性:

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

删除媒体资源

未包含在更新请求中的任何属性都将被删除,但更好的方法是发出 PATCH 请求以将相应值设置为 null。以下示例展示了如何删除私有属性:

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 个属性,总大小(键大小 + 值大小)不得超过 32KB。这 300 个属性包括共享属性和私有属性,涵盖活动的所有“副本”。