日历 API 提供了不同类型的活动资源,有关详情,请参阅关于活动。
有关此类资源的方法列表,请参阅本页面的结尾部分。
资源表示法
{ "kind": "calendar#event", "etag": etag, "id": string, "status": string, "htmlLink": string, "created": datetime, "updated": datetime, "summary": string, "description": string, "location": string, "colorId": string, "creator": { "id": string, "email": string, "displayName": string, "self": boolean }, "organizer": { "id": string, "email": string, "displayName": string, "self": boolean }, "start": { "date": date, "dateTime": datetime, "timeZone": string }, "end": { "date": date, "dateTime": datetime, "timeZone": string }, "endTimeUnspecified": boolean, "recurrence": [ string ], "recurringEventId": string, "originalStartTime": { "date": date, "dateTime": datetime, "timeZone": string }, "transparency": string, "visibility": string, "iCalUID": string, "sequence": integer, "attendees": [ { "id": string, "email": string, "displayName": string, "organizer": boolean, "self": boolean, "resource": boolean, "optional": boolean, "responseStatus": string, "comment": string, "additionalGuests": integer } ], "attendeesOmitted": boolean, "extendedProperties": { "private": { (key): string }, "shared": { (key): string } }, "hangoutLink": string, "conferenceData": { "createRequest": { "requestId": string, "conferenceSolutionKey": { "type": string }, "status": { "statusCode": string } }, "entryPoints": [ { "entryPointType": string, "uri": string, "label": string, "pin": string, "accessCode": string, "meetingCode": string, "passcode": string, "password": string } ], "conferenceSolution": { "key": { "type": string }, "name": string, "iconUri": string }, "conferenceId": string, "signature": string, "notes": string, }, "gadget": { "type": string, "title": string, "link": string, "iconLink": string, "width": integer, "height": integer, "display": string, "preferences": { (key): string } }, "anyoneCanAddSelf": boolean, "guestsCanInviteOthers": boolean, "guestsCanModify": boolean, "guestsCanSeeOtherGuests": boolean, "privateCopy": boolean, "locked": boolean, "reminders": { "useDefault": boolean, "overrides": [ { "method": string, "minutes": integer } ] }, "source": { "url": string, "title": string }, "workingLocationProperties": { "type": string, "homeOffice": (value), "customLocation": { "label": string }, "officeLocation": { "buildingId": string, "floorId": string, "floorSectionId": string, "deskId": string, "label": string } }, "outOfOfficeProperties": { "autoDeclineMode": string, "declineMessage": string }, "focusTimeProperties": { "autoDeclineMode": string, "declineMessage": string, "chatStatus": string }, "attachments": [ { "fileUrl": string, "title": string, "mimeType": string, "iconLink": string, "fileId": string } ], "eventType": string }
属性名称 | 值 | 说明 | 备注 |
---|---|---|---|
anyoneCanAddSelf |
boolean |
确定任何人都可以邀请自己参加活动(已弃用)。可选。默认值为 False。 | 可写入 |
attachments[] |
list |
活动的文件附件。 如需修改附件,应将 每个活动最多可包含 25 个附件 |
|
attachments[].fileId |
string |
附加文件的 ID。只读。 对于 Google 云端硬盘文件,这是 Drive API 中相应 |
|
attachments[].fileUrl |
string |
附件的网址链接。 添加 Google 云端硬盘文件时,请采用与 Drive API 中 添加附件时必填。 |
可写入 |
attachments[].iconLink |
string |
附件图标的网址链接。只能针对自定义第三方附件修改此字段。 | |
attachments[].mimeType |
string |
附件的互联网媒体类型(MIME 类型)。 | |
attachments[].title |
string |
附件标题。 | |
attendeesOmitted |
boolean |
是否代表参会者。检索事件时,这可能是由于 maxAttendee 查询参数指定的限制导致的。更新活动时,此操作只能用于更新参与者的回复。可选。默认值为 False。 |
可写入 |
attendees[] |
list |
活动的参加者。请参阅有参加者的活动指南,详细了解如何与其他日历用户安排活动。服务账号需要使用全网域授权来填充参与者列表。 | 可写入 |
attendees[].additionalGuests |
integer |
额外入住人数。可选。默认值为 0。 | 可写入 |
attendees[].comment |
string |
参加者的回复评论。可选。 | 可写入 |
attendees[].displayName |
string |
参加者的姓名(如果有)。可选。 | 可写入 |
attendees[].email |
string |
参加者的电子邮件地址(如果有)。添加参加者时,此字段必须显示。它必须是符合 RFC5322 规范的有效电子邮件地址。 添加参加者时必填。 |
可写入 |
attendees[].id |
string |
参加者的个人资料 ID(如果有)。 | |
attendees[].optional |
boolean |
此参与者是否为可选的参加者。可选。默认值为 False。 | 可写入 |
attendees[].organizer |
boolean |
参加者是否为活动的组织者。只读。默认值为 False。 | |
attendees[].resource |
boolean |
参加者是否为资源。只有在首次将参加者添加到活动中时才能进行设置。后续修改将被忽略。可选。默认值为 False。 | 可写入 |
attendees[].responseStatus |
string |
参加者的响应状态。可能的值包括:
|
可写入 |
attendees[].self |
boolean |
此条目是否代表显示此活动副本的日历。只读。默认值为 False。 | |
colorId |
string |
活动的颜色。这是一个 ID,它引用了颜色定义的 event 部分中的条目(请参阅 颜色端点)。可选。 |
可写入 |
conferenceData |
nested object |
与会议相关的信息,例如 Google Meet 会议的详细信息。如需创建新的会议详细信息,请使用 createRequest 字段。如需保留您的更改,请记得针对所有事件修改请求将 conferenceDataVersion 请求参数设置为 1 。 |
可写入 |
conferenceData.conferenceId |
string |
会议的 ID。 开发者可以用其跟踪会议,但不应该向用户显示。 对于每种会议解决方案类型,ID 值的形成方式会有所不同:
|
|
conferenceData.conferenceSolution |
nested object |
会议解决方案,例如 Google Meet。 未针对创建请求失败的会议进行设置。 必须提供 |
|
conferenceData.conferenceSolution.iconUri |
string |
此解决方案的用户可见图标。 | |
conferenceData.conferenceSolution.key |
nested object |
可唯一标识此活动的会议解决方案的键。 | |
conferenceData.conferenceSolution.key.type |
string |
会议解决方案类型。 如果客户端遇到不熟悉或空的类型,它应该仍然能够显示入口点。不过,这样应该会禁止修改。 可能的值包括:
|
|
conferenceData.conferenceSolution.name |
string |
此解决方案的用户可见名称。未本地化。 | |
conferenceData.createRequest |
nested object |
生成新会议并将其附加到活动的请求。数据是异步生成的。如需了解数据是否存在,请检查 status 字段。必须提供 |
|
conferenceData.createRequest.conferenceSolutionKey |
nested object |
会议解决方案,例如 Hangouts 或 Google Meet。 | |
conferenceData.createRequest.conferenceSolutionKey.type |
string |
会议解决方案类型。 如果客户端遇到不熟悉或空的类型,它应该仍然能够显示入口点。不过,这样应该会禁止修改。 可能的值包括:
|
|
conferenceData.createRequest.requestId |
string |
客户端为此请求生成的唯一 ID。 客户端应针对每个新请求重新生成此 ID。如果提供的 ID 与上一个请求的 ID 相同,该请求将被忽略。 |
|
conferenceData.createRequest.status |
nested object |
会议创建请求的状态。 | |
conferenceData.createRequest.status.statusCode |
string |
会议创建请求的当前状态。只读。 可能的值包括:
|
|
conferenceData.entryPoints[] |
list |
各个会议入口点的相关信息,例如网址或电话号码。 所有这些都必须属于同一会议。 必须提供 |
|
conferenceData.entryPoints[].accessCode |
string |
用于加入会议的访问代码。长度上限为 128 个字符。 创建新的会议数据时,请仅填充与会议服务提供商所用术语相符的 { 可选。 |
|
conferenceData.entryPoints[].entryPointType |
string |
会议入口点的类型。 可能的值包括:
|
|
conferenceData.entryPoints[].label |
string |
URI 的标签。对最终用户可见。未本地化。长度上限为 512 个字符。 示例:
可选。 |
|
conferenceData.entryPoints[].meetingCode |
string |
用于加入会议的会议代码。长度上限为 128 个字符。 创建新的会议数据时,请仅填充与会议服务提供商所用术语相符的 { 可选。 |
|
conferenceData.entryPoints[].passcode |
string |
用于加入会议的密码。长度上限为 128 个字符。 创建新的会议数据时,请仅填充与会议服务提供商所用术语相符的 { |
|
conferenceData.entryPoints[].password |
string |
用于访问会议的密码。长度上限为 128 个字符。 创建新的会议数据时,请仅填充与会议服务提供商所用术语相符的 { 可选。 |
|
conferenceData.entryPoints[].pin |
string |
用于访问会议的 PIN 码。长度上限为 128 个字符。 创建新的会议数据时,请仅填充与会议服务提供商所用术语相符的 { 可选。 |
|
conferenceData.entryPoints[].uri |
string |
入口点的 URI。长度上限为 1300 个字符。 格式:
|
|
conferenceData.notes |
string |
向用户显示的其他备注(如域管理员的说明、法律声明)。可以包含 HTML。长度上限为 2048 个字符。可选。 | |
conferenceData.signature |
string |
会议数据的签名。 在服务器端生成。 未针对创建请求失败的会议进行设置。 对于有待处理创建请求的会议的可选参数。 |
|
created |
datetime |
事件的创建时间(以 RFC3339 时间戳表示)。只读。 | |
creator |
object |
活动的创建者。只读。 | |
creator.displayName |
string |
创作者的姓名(如果有)。 | |
creator.email |
string |
创建者的电子邮件地址(如果有)。 | |
creator.id |
string |
创作者的个人资料 ID(如果有)。 | |
creator.self |
boolean |
创建者对应于显示此活动副本的日历。只读。默认值为 False。 | |
description |
string |
活动的说明。可以包含 HTML。可选。 | 可写入 |
end |
nested object |
事件的(不含)结束时间。对于周期性活动,这是指第一次活动的结束日期。 | |
end.date |
date |
日期,格式为“yyyy-mm-dd”(如果是全天活动)。 | 可写入 |
end.dateTime |
datetime |
时间,采用日期-时间组合值的形式(格式符合 RFC3339 标准)。除非在 timeZone 中明确指定时区,否则必须指定时区偏移量。 |
可写入 |
end.timeZone |
string |
时间所指定的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”)。对于周期性活动,此字段是必填字段,用于指定重复周期对应的时区。对于单个活动,此字段是可选的,表示活动开始/结束的自定义时区。 | 可写入 |
endTimeUnspecified |
boolean |
是否确实未指定结束时间。即使将此属性设为 True,仍会出于兼容性原因而提供结束时间。默认值为 False。 | |
etag |
etag |
资源的 ETag。 | |
eventType |
string |
事件的特定类型。活动创建后,您将无法修改此设置。可能的值包括:
|
可写入 |
extendedProperties |
object |
事件的扩展属性。 | |
extendedProperties.private |
object |
此日历上显示的活动副本的专用属性。 | 可写入 |
extendedProperties.private.(key) |
string |
私有属性的名称和相应值。 | |
extendedProperties.shared |
object |
在其他参加者的活动副本之间共享的属性日历。 | 可写入 |
extendedProperties.shared.(key) |
string |
共享属性的名称及相应值。 | |
focusTimeProperties |
nested object |
专注时间事件数据。当 eventType 为 focusTime 时使用。 |
可写入 |
focusTimeProperties.autoDeclineMode |
string |
是否拒绝与专注时间活动重叠的会议邀请。有效值为 declineNone ,表示不会拒绝任何会议邀请;declineAllConflictingInvitations ,表示与活动冲突的所有会议邀请都会被拒绝;和 declineOnlyNewConflictingInvitations ,这表示系统仅会拒绝在专注时间活动进行期间收到的有冲突的新会议邀请。 |
|
focusTimeProperties.chatStatus |
string |
用于在 Chat 和相关产品中标记用户的状态。可以是 available 或 doNotDisturb 。 |
|
focusTimeProperties.declineMessage |
string |
用于设置 Google 日历是否自动拒绝现有活动或新邀请的回复消息。 | |
gadget |
object |
用于扩展此事件的小工具。小工具已被弃用;此结构仅用于返回生日日历元数据。 | |
gadget.display |
string |
小工具的显示模式。已弃用。可能的值包括:
|
可写入 |
gadget.height |
integer |
小工具的高度(以像素为单位)。高度必须是大于 0 的整数。可选。已弃用。 | 可写入 |
gadget.iconLink |
string |
小工具的图标网址。网址架构必须是 HTTPS。已弃用。 | 可写入 |
gadget.link |
string |
小工具的网址。网址架构必须是 HTTPS。已弃用。 | 可写入 |
gadget.preferences |
object |
偏好设置。 | 可写入 |
gadget.preferences.(key) |
string |
偏好设置名称和相应的值。 | |
gadget.title |
string |
小工具的标题。已弃用。 | 可写入 |
gadget.type |
string |
小工具的类型。已弃用。 | 可写入 |
gadget.width |
integer |
小工具的宽度(以像素为单位)。宽度必须是大于 0 的整数。可选。已弃用。 | 可写入 |
guestsCanInviteOthers |
boolean |
除组织者以外的参与者是否可以邀请他人参加活动。可选。默认值为 True。 | 可写入 |
guestsCanModify |
boolean |
组织者以外的参与者是否可以修改活动。可选。默认值为 False。 | 可写入 |
guestsCanSeeOtherGuests |
boolean |
组织者以外的参加者是否可以看到活动的参加者。可选。默认值为 True。 | 可写入 |
hangoutLink |
string |
与此活动相关联的 Google 环聊的绝对链接。只读。 | |
htmlLink |
string |
Google 日历网页界面中指向此活动的绝对链接。只读。 | |
iCalUID |
string |
RFC5545 中定义的事件唯一标识符。此属性用于对日历系统上的活动进行唯一标识,并且在通过 import 方法导入活动时必须提供。 请注意, |
|
id |
string |
事件的不透明标识符。在创建新的单个活动或周期性活动时,您可以指定这些活动的 ID。提供的 ID 必须遵循以下规则:
如果您不指定 ID,服务器将自动生成。 请注意, |
可写入 |
kind |
string |
资源的类型(“calendar#event ”)。 |
|
location |
string |
事件的地理位置,以自由格式文本表示。可选。 | 可写入 |
locked |
boolean |
活动副本是否为锁定的活动副本,无法对主要活动字段“summary”“description”“location”“start”“end”进行更改或“重复周期”。默认值为 False。只读。 | |
organizer |
object |
活动的组织者。如果组织者同时也是参加者,则系统会在 attendees 中通过单独的条目来指明这一点,并将 organizer 字段设为 True。要更改组织者,请使用移动操作。只读(导入事件时除外)。 |
可写入 |
organizer.displayName |
string |
组织者的姓名(如果有)。 | 可写入 |
organizer.email |
string |
组织者的电子邮件地址(如果有)。它必须是符合 RFC5322 规范的有效电子邮件地址。 | 可写入 |
organizer.id |
string |
组织者的个人资料 ID(如果有)。 | |
organizer.self |
boolean |
组织者是否对应于显示此活动副本的日历。只读。默认值为 False。 | |
originalStartTime |
nested object |
对于周期性活动的实例,根据由重复事件 ID 标识的周期性活动中的重复数据,此活动开始的时间。它唯一标识周期性事件系列中的实例,即使实例已移到其他时间也是如此。固定不变。 | |
originalStartTime.date |
date |
日期,格式为“yyyy-mm-dd”(如果是全天活动)。 | 可写入 |
originalStartTime.dateTime |
datetime |
时间,采用日期-时间组合值的形式(格式符合 RFC3339 标准)。除非在 timeZone 中明确指定时区,否则必须指定时区偏移量。 |
可写入 |
originalStartTime.timeZone |
string |
时间所指定的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”)。对于周期性活动,此字段是必填字段,用于指定重复周期对应的时区。对于单个活动,此字段是可选的,表示活动开始/结束的自定义时区。 | 可写入 |
outOfOfficeProperties |
nested object |
不在办公室活动数据。当 eventType 为 outOfOffice 时使用。 |
可写入 |
outOfOfficeProperties.autoDeclineMode |
string |
是否拒绝与“不在办公室”活动重叠的会议邀请。有效值为 declineNone ,表示不会拒绝任何会议邀请;declineAllConflictingInvitations ,表示与活动冲突的所有会议邀请都会被拒绝;和 declineOnlyNewConflictingInvitations 选项,这意味着系统仅会拒绝在“不在办公室”活动期间到达的新的有冲突的会议邀请。 |
|
outOfOfficeProperties.declineMessage |
string |
用于设置 Google 日历是否自动拒绝现有活动或新邀请的回复消息。 | |
privateCopy |
boolean |
如果此政策设为 True,系统会停用事件传播。请注意,它与私享活动属性不同。可选。不可变。默认值为 False。 | |
recurrence[] |
list |
周期性活动的 RRULE、EXRULE、RDATE 和 EXDATE 行的列表(如 RFC5545 中所指定)。请注意,此字段不允许使用 DTSTART 和 DTEND 行;在 start 和 end 字段中指定事件的开始和结束时间。对于单一活动或周期性活动,此字段会被忽略。 |
可写入 |
recurringEventId |
string |
对于周期性活动的实例,此字段是实例所属的周期性活动的 id 。固定不变。 |
|
reminders |
object |
针对经过身份验证的用户的活动提醒的相关信息。请注意,更改提醒不会同时更改所属活动的 updated 属性。 |
|
reminders.overrides[] |
list |
如果活动没有使用默认提醒,那么系统会列出特定于该活动的提醒;如果未设置,则表示没有为该活动设置提醒。覆盖提醒的数量上限为 5。 | 可写入 |
reminders.overrides[].method |
string |
此提醒使用的方法。可能的值包括:
添加提醒时必填。 |
可写入 |
reminders.overrides[].minutes |
integer |
在事件开始前多少分钟应触发提醒。有效值介于 0 到 40320 之间(4 周的分钟数)。 添加提醒时必填。 |
可写入 |
reminders.useDefault |
boolean |
日历的默认提醒是否适用于相应活动。 | 可写入 |
sequence |
integer |
序号与 icalendar 相同。 | 可写入 |
source |
object |
创建事件的来源。例如,网页、电子邮件或可通过采用 HTTP 或 HTTPS 架构的网址识别的任何文档。只有活动的创建者可以查看或修改。 | |
source.title |
string |
该来源的标题;例如网页标题或电子邮件主题。 | 可写入 |
source.url |
string |
指向资源的来源网址。网址架构必须是 HTTP 或 HTTPS。 | 可写入 |
start |
nested object |
事件的开始时间(含边界值)。对于周期性活动,这是第一次活动开始时间。 | |
start.date |
date |
日期,格式为“yyyy-mm-dd”(如果是全天活动)。 | 可写入 |
start.dateTime |
datetime |
时间,采用日期-时间组合值的形式(格式符合 RFC3339 标准)。除非在 timeZone 中明确指定时区,否则必须指定时区偏移量。 |
可写入 |
start.timeZone |
string |
时间所指定的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”)。对于周期性活动,此字段是必填字段,用于指定重复周期对应的时区。对于单个活动,此字段是可选的,表示活动开始/结束的自定义时区。 | 可写入 |
status |
string |
事件的状态。可选。可能的值包括:
|
可写入 |
summary |
string |
活动的标题。 | 可写入 |
transparency |
string |
相应活动是否屏蔽了日历上的时间。可选。可能的值包括:
|
可写入 |
updated |
datetime |
主要事件数据的上次修改时间(以 RFC3339 时间戳表示)。更新活动提醒不会造成此更改。只读。 | |
visibility |
string |
活动的公开范围。可选。可能的值包括:
|
可写入 |
workingLocationProperties |
nested object |
工作地点活动数据。 | 可写入 |
workingLocationProperties.customLocation |
object |
如果存在,则指定用户正在自定义位置工作。 | 可写入 |
workingLocationProperties.customLocation.label |
string |
用于其他信息的可选额外标签。 | 可写入 |
workingLocationProperties.homeOffice |
any value |
如果存在,则指定用户在家工作。 | 可写入 |
workingLocationProperties.officeLocation |
object |
如果存在,则指定用户是在办公室工作的。 | 可写入 |
workingLocationProperties.officeLocation.buildingId |
string |
可选的建筑物标识符。此 ID 应引用组织的“资源”数据库中的建筑物 ID。 | 可写入 |
workingLocationProperties.officeLocation.deskId |
string |
可选的桌面标识符。 | 可写入 |
workingLocationProperties.officeLocation.floorId |
string |
可选的楼层标识符。 | 可写入 |
workingLocationProperties.officeLocation.floorSectionId |
string |
可选的楼层分区标识符。 | 可写入 |
workingLocationProperties.officeLocation.label |
string |
在 Google 日历网页版和移动版客户端中显示的 Office 名称。我们建议您在组织的“资源”数据库中引用建筑物名称。 | 可写入 |
workingLocationProperties.type |
string |
工作地点的类型。可能的值包括:
添加工作地点属性时必填。 |
可写入 |
方法
- delete
- 删除活动。
- get
- 根据活动的 Google 日历 ID 返回活动。如要使用 i 日历 ID 检索活动,请使用
iCalUID
参数调用 events.list 方法。 - 导入
- 导入事件。此操作会将现有活动的不公开副本添加到日历。只能导入
eventType
为default
的事件。已弃用的行为:如果导入了非
default
事件,其类型将更改为default
,并且该事件可能具有的任何特定于事件类型的属性都将被丢弃。 - insert
- 创建事件。
- 实例
- 返回指定周期性活动的实例。
- list
- 返回指定日历上的活动。
- 移动
- 将活动移至其他日历,例如更改活动的组织者。请注意,只能移动
default
事件;无法移动“outOfOffice
”、“focusTime
”、“workingLocation
”和“fromGmail
”事件。 - patch
- 更新活动。此方法支持补丁语义。请注意,每个补丁请求消耗三个配额单元:首选使用
get
,后跟update
。您指定的字段值会替换现有值。您未在请求中指定的字段将保持不变。数组字段(如果指定)会覆盖现有的数组;这会舍弃之前的所有数组元素 - quickAdd
- 根据简单的文本字符串创建事件。
- update
- 更新活动。此方法不支持补丁语义,并且始终更新整个事件资源。如需执行部分更新,请执行
get
,然后使用 etag 执行update
,以确保原子性。 - 手表
- 留意“活动”资源的更改。