扩展属性

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

公开范围

有两种扩展属性可用：私有和共享。共享属性对活动的所有参加者可见和修改，而不公开属性是在一个参加者的本地“副本”上设置的。具体而言，私有属性特定于请求中使用的 calendarId 和 eventId，而无论请求中使用的 calendarId 是什么，共享属性都会显示。

添加和更新媒体资源

扩展属性是在事件资源上设置的，与其他字段一样，可以在 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

您可以多次重复这些字段，且约束条件以 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 项属性包括活动的所有“副本”中的共享和不公开属性。