扩展属性

“Events”资源的字段涵盖与事件相关的大部分常见数据，例如位置和开始时间，但应用可能需要存储特定于其用例的其他元数据。借助 Google 日历 API，您可以为事件设置隐藏的键值对， 称为 扩展属性。 借助扩展属性，您可以轻松存储事件的应用专用数据，而无需使用外部数据库。

公开范围

扩展属性有两种类型：私有属性和共享属性。 共享属性对事件的所有参与者可见且可供其修改，而私有属性是在参与者的事件本地副本中设置的。更具体地说，私有属性特定于请求中使用的 calendarId 和 eventId，而共享属性则无论请求中使用哪个 calendarId 都会显示。

添加和更新属性

扩展属性是在 Events 资源中设置的，与其他字段一样，可以在 events.insert、 events.update 和 events.patch 请求中设置。 建议使用 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

您可以多次重复这些字段，并且系统会使用 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 个属性包括事件的所有副本中的共享属性和私有属性。