Calendar 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": { "homeOffice": (value), "customLocation": { "label": string }, "officeLocation": { "buildingId": string, "floorId": string, "floorSectionId": string, "deskId": string, "label": 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 与上一个请求相同,则忽略该请求。 |
|
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 |
共享媒体资源的名称及其对应的值。 | |
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”或“recurrence”进行任何更改。默认值为 False。只读。 | |
organizer |
object |
活动组织者。如果组织者也是参加者,则会在 attendees 中通过单独的条目来指明,并将 organizer 字段设为 True。要更改组织者,请使用移动操作。只读,导入事件时除外。 |
可写入 |
organizer.displayName |
string |
组织者的姓名(如果有)。 | 可写入 |
organizer.email |
string |
组织者的电子邮件地址(如果有)。必须是符合 RFC5322 规定的有效电子邮件地址。 | 可写入 |
organizer.id |
string |
组织者的个人资料 ID(如果有)。 | |
organizer.self |
boolean |
活动组织者是否对应于活动副本所在的日历。只读。默认值为 False。 | |
originalStartTime |
nested object |
对于周期性活动的实例,指的是根据周期性事件中的周期性事件的重复性数据,该事件的开始时间。它可在周期性活动系列中唯一标识实例,即使实例已移到其他时间也是如此。固定不变。 | |
originalStartTime.date |
date |
如果日期为全天活动,则日期格式为“yyyy-mm-dd”。 | 可写入 |
originalStartTime.dateTime |
datetime |
时间,采用日期时间组合值格式(遵循 RFC3339 格式)。除非在 timeZone 中明确指定时区,否则必须提供时区偏移量。 |
可写入 |
originalStartTime.timeZone |
string |
指定时间的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”。)对于周期性活动,此字段是必填字段,并用于指定展开重复活动的时区。对于单个活动,此字段是可选的,表示活动开始/结束时间的自定义时区。 | 可写入 |
privateCopy |
boolean |
如果此政策设为 True,系统会停用事件传播。请注意,它与不公开事件属性不同。(可选)不可变。默认值为 False。 | |
recurrence[] |
list |
周期性活动的 RRULE、EXRULE、RDATE 和 EXDATE 行列表(如 RFC5545 中所指定)。请注意,此字段不允许使用 DTSTART 和 DTEND 行;start 和 end 字段中指定了事件开始时间和结束时间。对于单个活动或周期性活动的实例,此字段将被省略。 |
可写入 |
recurringEventId |
string |
对于周期性活动的实例,这是该实例所属的周期性事件的 id 。固定不变。 |
|
reminders |
object |
与经过身份验证的用户的活动提醒相关的信息。 | |
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。 | |
workingLocationProperties.officeLocation.deskId |
string |
可选的任意桌面标识符。 | |
workingLocationProperties.officeLocation.floorId |
string |
可选的任意楼层标识符。 | |
workingLocationProperties.officeLocation.floorSectionId |
string |
可选的任意楼层分区标识符。 | |
workingLocationProperties.officeLocation.label |
string |
(可选)用于提供更多信息的额外标签。 |
方法
- delete
- 删除活动。
- get
- 根据 Google 日历 ID 返回活动。若要使用 iCalendar ID 检索活动,请使用
iCalUID
参数调用 events.list 方法。 - 导入
- 导入事件。此操作用于将现有活动的私有副本添加到日历。
- 插入
- 创建活动。
- 实例
- 返回指定周期性事件的实例。
- list
- 返回指定日历上的活动。
- 移动
- 将活动移至其他日历,例如更改活动的组织者。
- 补丁程序
- 更新事件。此方法支持补丁语义。请注意,每个修补请求消耗三个配额单元;首选使用
get
,后跟update
。您指定的字段值会替换现有值。未在请求中指定的字段保持不变。如果指定数组字段,则覆盖现有数组;这会舍弃之前的所有数组元素。 - 快速添加
- 根据简单的文本字符串创建事件。
- update
- 更新事件。此方法不支持补丁语义,并且始终更新整个事件资源。如需执行部分更新,请使用 etag 执行
get
,后跟update
,以确保原子性。 - 手表
- 留意事件资源的变化。