Events

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
  },
  "attachments": [
    {
      "fileUrl": string,
      "title": string,
      "mimeType": string,
      "iconLink": string,
      "fileId": string
    }
  ],
  "eventType": string
}
属性名称 说明 备注
anyoneCanAddSelf boolean 所有人是否可以邀请自己参加活动(已弃用)。(可选)默认值为 False。 可写入
attachments[] list 活动的文件附件。

如需修改附件,应将 supportsAttachments 请求参数设置为 true

每个活动最多可包含 25 个附件。

attachments[].fileId string 附加文件的 ID。只读。

对于 Google 云端硬盘文件,这是 Drive API 中相应 Files 资源条目的 ID。

attachments[].fileUrl string 指向附件的网址链接。

如需添加 Google 云端硬盘文件附件,请使用与 Drive API 中 Files 资源的 alternateLink 属性相同的格式。

添加附件时必填。

可写入
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 参加者的回复状态。可能的值包括:
  • needsAction”- 参加者尚未回复邀请(推荐用于新活动)。
  • declined”- 参加者已拒绝邀请。
  • tentative”- 参加者已暂时接受邀请。
  • accepted”- 参加者已接受邀请。
可写入
attendees[].self boolean 此条目是否代表显示活动副本的日历。只读。默认值为 False。
colorId string 活动的颜色。这是一个 ID,用于引用颜色定义的 event 部分中的条目(请参阅颜色端点)。可选。 可写入
conferenceData nested object 与会议相关的信息,例如 Google Meet 会议的详细信息。如需创建新的会议详细信息,请使用 createRequest 字段。若要保留更改,请务必针对所有事件修改请求将 conferenceDataVersion 请求参数设置为 1 可写入
conferenceData.conferenceId string 会议的 ID。

可供开发者用来跟踪会议,不应向用户显示。

每种会议解决方案类型的 ID 值采用不同的格式:

  • eventHangout:未设置 ID。(此会议类型已弃用。)
  • eventNamedHangout:ID 是 Hangouts 的名称。(此会议类型已弃用。)
  • hangoutsMeet:ID 是由 10 个字母组成的会议代码,例如 aaa-bbbb-ccc
  • addOn:ID 由第三方提供商定义。
可选。

conferenceData.conferenceSolution nested object 会议解决方案,例如 Google Meet。

为创建请求失败的会议取消设置。

至少需要 conferenceSolution 和至少一个 entryPoint,或者 createRequest

conferenceData.conferenceSolution.iconUri string 此解决方案的用户可见图标。
conferenceData.conferenceSolution.key nested object 可以唯一标识此活动的会议解决方案的键。
conferenceData.conferenceSolution.key.type string 会议解决方案类型。

如果客户端遇到不熟悉或空的类型,则应该仍然可以显示入口点。不过,您应禁止进行修改。

可能的值包括:

  • 适用于个人用户的环聊"eventHangout"(已弃用;现有活动可能会显示此会议解决方案类型,但无法创建新会议)
  • 适用于 Google Workspace 传统版 Hangouts 用户的 "eventNamedHangout"(已弃用;现有活动可能会显示此会议解决方案类型,但无法创建新会议)
  • "hangoutsMeet" 版 Google Meet (http://meet.google.com)
  • "addOn",适用于第三方会议服务提供商

conferenceData.conferenceSolution.name string 此解决方案的用户可见名称。未本地化。
conferenceData.createRequest nested object 请求生成新会议并将其附加到活动中。数据是异步生成的。如需了解数据是否存在,请查看 status 字段。

至少需要 conferenceSolution 和至少一个 entryPoint,或者 createRequest

conferenceData.createRequest.conferenceSolutionKey nested object 会议解决方案,例如 Hangouts 或 Google Meet。
conferenceData.createRequest.conferenceSolutionKey.type string 会议解决方案类型。

如果客户端遇到不熟悉或空的类型,则应该仍然可以显示入口点。不过,您应禁止进行修改。

可能的值包括:

  • 适用于个人用户的环聊"eventHangout"(已弃用;现有活动可能会显示此会议解决方案类型,但无法创建新会议)
  • 适用于 Google Workspace 传统版 Hangouts 用户的 "eventNamedHangout"(已弃用;现有活动可能会显示此会议解决方案类型,但无法创建新会议)
  • "hangoutsMeet" 版 Google Meet (http://meet.google.com)
  • "addOn",适用于第三方会议服务提供商

conferenceData.createRequest.requestId string 此请求由客户生成的唯一 ID。

客户端应为每个新请求重新生成此 ID。如果提供的 ID 与上一个请求相同,则忽略该请求。

conferenceData.createRequest.status nested object 会议创建请求的状态。
conferenceData.createRequest.status.statusCode string 会议创建请求的当前状态。只读。

可能的值包括:

  • "pending":会议创建请求仍在处理中。
  • "success":会议创建请求成功,入口点会被填充。
  • "failure":会议创建请求失败,没有入口点。

conferenceData.entryPoints[] list 有关具体会议入口点的信息,例如网址或电话号码。

所有会议都必须属于同一场会议。

至少需要 conferenceSolution 和至少一个 entryPoint,或者 createRequest

conferenceData.entryPoints[].accessCode string 用于访问会议的访问代码。长度上限为 128 个字符。

创建新的会议数据时,请仅填充 {meetingCodeaccessCodepasscodepasswordpin} 字段(与会议服务提供商使用的术语匹配)的子集。系统应仅显示已填充的字段。

可选。

conferenceData.entryPoints[].entryPointType string 会议入口点的类型。

可能的值包括:

  • "video" - 通过 HTTP 加入会议。一个会议可以有 0 个或 1 个 video 入口点。
  • "phone" - 通过拨号加入会议。一个会议可以有零个或多个 phone 入口点。
  • "sip" - 通过 SIP 加入会议。一个会议可以有 0 个或 1 个 sip 入口点。
  • "more" - 进一步的会议加入说明,例如额外的电话号码。一个会议可以有 0 个或 1 个 more 入口点。只有 more 入口点的会议不是有效的会议。

conferenceData.entryPoints[].label string URI 的标签。向最终用户显示。未本地化。长度上限为 512 个字符。

示例:

  • 对于 video:meet.google.com/aaa-bbbb-ccc
  • phone:+1 123 268 2601
  • 对于 sip:12345678@altostrat.com
  • 对于“more”:不应填充

可选。

conferenceData.entryPoints[].meetingCode string 用于访问会议的会议代码。长度上限为 128 个字符。

创建新的会议数据时,请仅填充 {meetingCodeaccessCodepasscodepasswordpin} 字段(与会议服务提供商使用的术语匹配)的子集。系统应仅显示已填充的字段。

可选。

conferenceData.entryPoints[].passcode string 用于访问会议的密码。长度上限为 128 个字符。

创建新的会议数据时,请仅填充 {meetingCodeaccessCodepasscodepasswordpin} 字段(与会议服务提供商使用的术语匹配)的子集。系统应仅显示已填充的字段。

conferenceData.entryPoints[].password string 用于访问会议的密码。长度上限为 128 个字符。

创建新的会议数据时,请仅填充 {meetingCodeaccessCodepasscodepasswordpin} 字段(与会议服务提供商使用的术语匹配)的子集。系统应仅显示已填充的字段。

可选。

conferenceData.entryPoints[].pin string 用于访问会议的 PIN 码。长度上限为 128 个字符。

创建新的会议数据时,请仅填充 {meetingCodeaccessCodepasscodepasswordpin} 字段(与会议服务提供商使用的术语匹配)的子集。系统应仅显示已填充的字段。

可选。

conferenceData.entryPoints[].uri string 入口点的 URI。长度上限为 1300 个字符。

格式:

  • 对于 videohttp:https: 架构是必需的。
  • 对于 phone,必须提供 tel: 架构。URI 应包含整个拨号序列(例如,tel:+12345678900,,,123456789;1234)。
  • 对于 sip,必须提供 sip: 架构,例如 sip:12345678@myprovider.com。
  • 对于 morehttp:https: 架构是必需的。

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 活动的具体类型。只读。可能的值包括:
  • default”- 常规事件或未进一步指定。
  • outOfOffice”- 不在办公室活动。
  • focusTime”- 一个专注时间活动。
extendedProperties object 事件的扩展属性。
extendedProperties.private object 仅此日历中显示的活动副本的私有属性。 可写入
extendedProperties.private.(key) string 私有属性的名称和对应值。
extendedProperties.shared object 在其他参加者的日历上的活动副本之间共享的属性。 可写入
extendedProperties.shared.(key) string 共享媒体资源的名称及其对应的值。
gadget object 用于扩展此事件的小工具。小工具已弃用;此结构仅用于返回生日日历元数据。
gadget.display string 小工具的显示模式。已弃用。可能的值包括:
  • icon”- 小工具在日历视图中显示在活动标题的旁边。
  • chip”- 点击事件时,小工具会显示。
可写入
gadget.height integer 小工具的高度(以像素为单位)。高度必须是大于 0 的整数。(可选)已弃用。 可写入
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。 可写入
iCalUID string RFC5545 中定义的事件唯一标识符。它用于跨日历系统唯一标识活动,并且在通过 import 方法导入活动时必须提供。

请注意,iCalUIDid 不完全相同,在创建事件时只应提供其中一个。它们在语义上的一个区别在于,在周期性事件中,一个事件的所有发生实例都有不同的 id,但它们全部共用相同的 iCalUID。如需使用事件的 iCalUID 检索事件,请使用 iCalUID 参数调用 events.list 方法。如需使用事件的 id 检索事件,请调用 events.get 方法。

id string 事件的不透明标识符。创建新的单个活动或周期性活动时,您可以指定其 ID。提供的 ID 必须遵循以下规则:
  • ID 中允许使用的字符是 base32 十六进制编码中使用的字符,即小写字母 a-v 和数字 0-9,请参阅 RFC2938 中的第 3.1.2 节
  • ID 的长度必须介于 5 到 1024 个字符之间
  • 每个日历的 ID 必须是唯一的
由于系统的全局性,我们无法保证在创建事件时能够检测到 ID 冲突。为最大限度地降低冲突风险,我们建议使用既定的 UUID 算法(如 RFC4122 中所述的算法)。

如果您未指定 ID,服务器便会自动生成。

请注意,icalUIDid 不完全相同,在创建事件时只应提供其中一个。它们在语义上的一个区别在于,在周期性事件中,一个事件的所有发生实例都有不同的 id,但它们全部共用相同的 icalUID

可写入
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 行;startend 字段中指定了事件开始时间和结束时间。对于单个活动或周期性活动的实例,此字段将被省略。 可写入
recurringEventId string 对于周期性活动的实例,这是该实例所属的周期性事件的 id。固定不变。
reminders object 与经过身份验证的用户的活动提醒相关的信息。
reminders.overrides[] list 如果活动未使用默认提醒,则系统会列出专门针对该活动的提醒;如果未设置,则表示没有为此事件设置任何提醒。替换提醒的数量上限为 5 个。 可写入
reminders.overrides[].method string 此提醒使用的方法。可能的值包括:
  • email”- 提醒会通过电子邮件发送。
  • popup”- 提醒通过界面弹出式窗口发送。

添加提醒时必填。

可写入
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 活动的状态。(可选)可能的值包括:
  • confirmed”- 活动已确认。这是默认状态。
  • tentative”- 活动已暂时确认。
  • cancelled”- 活动已取消(已删除)。只有在增量同步(指定了 syncTokenupdatedMin)或 showDeleted 标志设置为 true 时,list 方法才会返回已取消的事件。get 方法始终会返回这些对象。

    “取消”状态表示两种不同的状态(具体取决于事件类型):

    1. 未取消的周期性活动中一旦取消,则表明此实例不应再呈现给用户。客户端应在父级周期性事件的生命周期内存储这些事件。

      取消的异常只能保证为 idrecurringEventIdoriginalStartTime 字段填充值。其他字段可能为空。

    2. 所有其他取消的活动都代表已删除的活动。客户端应移除其本地同步的副本。这类取消的活动最终会消失,因此请勿无限期地提供这些活动信息。

      删除的事件只能保证填充 id 字段。

    在组织者的日历中,已取消的活动会继续显示活动详细信息(摘要、地点等),以便恢复(取消删除)活动。同样地,邀请用户以及手动移除的活动仍会继续提供详细信息。但是,如果 showDeleted 设置为 false,增量同步请求不会返回这些详细信息。

    如果某个活动更改组织者(例如通过移动操作),而原始组织者不在参加者列表中,则取消的活动会被取消,只保证填充 id 字段。

可写入
summary string 活动的标题。 可写入
transparency string 活动是否阻止了日历上的时间。(可选)可能的值包括:
  • opaque”- 默认值。该活动在日历上会屏蔽时间。这相当于在日历界面中将状态显示为设置为忙碌
  • transparent”- 活动不会阻止日历上的时间。等同于在 Google 日历界面中将状态显示为设置为有空
可写入
updated datetime 事件的最后修改时间(以 RFC3339 时间戳的形式表示)。只读。
visibility string 活动的公开范围。(可选)可能的值包括:
  • default”- 对日历中的活动使用默认公开范围。这是默认值。
  • public”- 活动为公开活动,并且日历的所有读者都可以看到活动详情。
  • private”- 活动为私人状态,只有活动参加者才能查看活动详情。
  • confidential”- 活动为私密活动。提供此值是为了确保兼容性。
可写入

方法

delete
删除活动。
get
根据 Google 日历 ID 返回活动。若要使用 iCalendar ID 检索活动,请使用 iCalUID 参数调用 events.list 方法
导入
导入事件。此操作用于将现有活动的私有副本添加到日历。
插入
创建活动。
实例
返回指定周期性事件的实例。
list
返回指定日历上的活动。
移动
将活动移至其他日历,例如更改活动的组织者。
补丁程序
更新事件。此方法支持补丁语义。请注意,每个修补请求消耗三个配额单元;首选使用 get,后跟 update。您指定的字段值会替换现有值。未在请求中指定的字段保持不变。如果指定数组字段,则覆盖现有数组;这会舍弃之前的所有数组元素。
快速添加
根据简单的文本字符串创建事件。
update
更新事件。
手表
留意事件资源的变化。