扩展属性
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
活动资源的字段涵盖了与活动相关联的最常见数据,例如地点、开始时间等,但应用可能希望存储特定于其使用情形的其他元数据。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
限制
- 属性键的大小上限为 44 个字符,键较长的属性会被悄然舍弃。
- 属性值的最大大小为 1024 个字符,如果属性值的长度超过此限制,系统会默默地将其截断。
- 一个事件最多可以包含 300 个属性,总大小(键大小 + 值大小)不得超过 32KB。这 300 个属性包括共享属性和私有属性,涵盖活动的所有“副本”。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[],[],null,["# Extended properties\n\nThe fields of the [Events resources](/workspace/calendar/v3/reference/events)\ncover the most common data associated with an\nevent, such as location, start time, etc, but applications may want to store\nadditional metadata specific to their use case. The Calendar API provides the\nability to set hidden key-value pairs with an event, called\n[extended properties](/workspace/calendar/v3/reference/events#extendedProperties).\nExtended properties make it easy to store application-specific data for an event\nwithout having to utilize an external database.\n\nVisibility\n----------\n\nThere are two types of extended properties available: private and shared.\nShared properties are visible and editable by all attendees of an event, while\nprivate properties are set on one attendee's local \"copy\" of the event. More\nconcretely, private properties are specific to the `calendarId` and `eventId`\nused in the request, while shared properties will be shown regardless of the\n`calendarId` used in the request.\n\nAdd \\& update properties\n------------------------\n\nExtended properties are set on the Events resource, and like other fields can be\nset in [insert](/workspace/calendar/v3/reference/events/insert),\n[update](/workspace/calendar/v3/reference/events/update), and\n[patch](/workspace/calendar/v3/reference/events/patch) requests.\nUsing patch requests is the preferred\nmethod, as it allows you to manipulate some properties while leaving others\nuntouched. Adding a new property with the same key will overwrite any existing\nproperties with the same key. The following example shows setting a private\nproperty: \n\n```text\nPATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId\n``` \n\n {\n \"extendedProperties\": {\n \"private\": {\n \"petsAllowed\": \"yes\"\n }\n }\n }\n\nDelete properties\n-----------------\n\nAny properties not included in an update request will be deleted, but a better\napproach is to make a patch request to set the value to null. The following\nexample shows deleting a private property: \n\n```text\nPATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId\n``` \n\n {\n \"extendedProperties\": {\n \"private\": {\n \"petsAllowed\": null\n }\n }\n }\n\nSearch properties\n-----------------\n\nYou can search events based on the values on their extended properties using an\n[Events.list](/workspace/calendar/v3/reference/events/list) request.\nSet the field\n[privateExtendedProperty](/workspace/calendar/v3/reference/events/list#privateExtendedProperty)\nor\n[sharedExtendedProperty](/workspace/calendar/v3/reference/events/list#sharedExtendedProperty)\nto a constraint in the format `propertyName=value`,\nwhich searches against private and shared properties respectively. The following\nexample returns events with the private property `petsAllowed=yes`: \n\n```\nGET https://www.googleapis.com/calendar/v3/calendars/calendarId/events\n ?privateExtendedProperty=petsAllowed%3Dyes\n```\n\nYou can repeat these fields multiple times and the constraints are OR'ed\ntogether, so events only need to match one of the constraints to be returned.\nThe following example finds events with either the private property\n`petsAllowed=yes` or `isOutside=yes`: \n\n```\nGET https://www.googleapis.com/calendar/v3/calendars/calendarId/events\n ?privateExtendedProperty=petsAllowed%3Dyes\n &privateExtendedProperty=isOutside%3Dyes\n```\n\nBe aware that constraints on private and shared properties are AND'ed together\nhowever, so events must match both sets of constraints in order to be returned.\nThe following example finds events with the private property `petsAllowed=yes`\nand the public property `createdBy=myApp`: \n\n```\nGET https://www.googleapis.com/calendar/v3/calendars/calendarId/events\n ?privateExtendedProperty=petsAllowed%3Dyes\n &sharedExtendedProperty=createdBy%3DmyApp\n```\n\nLimits\n------\n\n1. The maximum size of a property's key is 44 characters, and properties with longer keys will be silently dropped.\n2. The maximum size of a property's value is 1024 characters, and properties with longer values will be silently truncated.\n3. An event can have up to 300 properties totaling up to 32kB in size (keys size + value size). These 300 properties include shared and private properties, across all \"copies\" of the event."]]