扩展属性

活动资源的字段涵盖了与活动相关联的最常见数据，例如地点、开始时间等，但应用可能希望存储特定于其使用情形的其他元数据。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 请求，将相应的值设置为 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

您可以多次重复这些字段，并且这些限制会通过 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 个属性，总大小（键大小 + 值大小）不得超过 32KB。这 300 个属性包括活动的所有“副本”中的共享属性和私有属性。