创建事件
如果您对组织者的 Google 日历具有写入权限,则可以使用 Events: insert
方法添加活动。
此方法会将活动直接添加到组织者的日历中,与添加邀请的设置无关。
添加参加者
使用此方法,您还可以将参加者的电子邮件地址添加到活动的 attendees
属性中,从而将其添加到同一活动中。组织者将来对活动所做的任何更改都会传达给参加者。
参加者会从组织者的电子邮件地址收到邀请。Google 日历用户会在电子邮件和/或日历中收到邀请,具体取决于他们在 Google 日历设置中的活动设置:
- 如果他们采用
From everyone
设置,系统会将活动直接添加到他们的日历中 - 如果成员具有
Only if the sender is known
设置,且他们之前与组织者有过互动、组织者同属一个组织或者组织者在其 Google 通讯录中,则系统会将活动直接添加到其日历中。如果不认识组织者,他们可以点击邀请电子邮件中的是或不确定,然后点击我认识此发件人或回复。然后将活动添加到他们的日历中 - 如果用户的设置为
When I respond in email
,则直到用户通过点击邀请电子邮件中的是、不确定或否做出回复之前,所有邀请都不会添加到他们的日历中。
如需详细了解如何将邀请添加到 Google 日历,请参阅在 Google 日历中管理邀请。
请勿使用 attendees[].responseStatus
属性将参加者的响应设置为 needsAction
以外的任何内容。预先填充参加者的回复不会自动将事件添加到用户的日历中。
直接在参加者的日历中显示活动
如需根据参与者可能拥有的任何设置直接在 Google 日历参与者的日历中显示活动,您可以设置参与者的回复或直接在参与者的日历中导入活动的副本。对于这两种方法,您都需要对参加者的日历拥有写入权限;如果您没有,请考虑将组织者添加到参加者的联系人中,这可能需要对参加者的联系人的写入权限。
设置参加者的回复
要设置参加者对活动的回复,请按以下步骤操作:
- 在 Google 日历组织者的日历中创建活动并添加参加者(见上文)。
- 使用
Events: update
方法将参加者的回复设置为accepted
或tentative
。您必须拥有参加者日历的写入权限。活动可能要略有延迟才会显示在参加者的日历上。详细了解如何使用Events: update
方法。
此方法会将事件添加到参加者的日历中,但参加者可能仍会在其电子邮件中看到横幅,提示您邀请是由一个之前不认识的电子邮件地址发送的。
直接在参加者的日历中导入活动的副本
如需将活动副本导入参加者的日历中,请按以下步骤操作:
- 如果您对组织者的 Google 日历具有写入权限,请使用
Events: import
方法导入活动的副本。 - 使用
Events: import
在参加者的日历中导入同一活动的其他副本。您必须拥有参加者日历的写入权限。请为组织者和参加者的副本使用相同的活动 ID (iCalUID
),并确保在参加者的副本中指定组织者。
使用此方法,参加者可以在其日历中查看活动,但不会收到 Google 日历发送的邀请电子邮件。
将组织者添加到参加者的联系人中
如果您没有参加者的凭据,则可以指示参加者或其组织提前将组织者的电子邮件地址添加到其 Google 通讯录中,以便直接在他们的日历中显示活动。新创建的联系人可能需要稍微延迟才能生效。
- 让 Google 日历用户将组织者添加到其 Google 通讯录中。
- 如果参加者属于某个组织,您可以要求组织的管理员以编程方式将电子邮件地址添加到其用户的联系人。请让管理员启用全网域授权、模拟用户并使用
People: createContact
方法为每个用户创建联系人,以确保将来来自这些电子邮件地址的邀请自动显示在其用户的日历中。 - 如果您有权访问参与者的联系人,还可以使用
People: createContact
方法将组织者的电子邮件地址添加到参与者的联系人中。
通过电子邮件地址邀请用户
如果您没有组织者的 Google 日历的写入权限,或者您不希望公开组织者的电子邮件地址,请使用 iCalendar 协议 (RFC-5545) 通过 .ICS 文件邀请电子邮件地址用户。
如果参加者是采用 Only if the sender
is known
设置的 Google 日历用户,并且之前未与自己熟悉的地址互动过或未记录过该地址,则只有在点击我认识这位发送者或回复活动邀请后,邀请才会添加到他们的日历中。
提供链接以便用户添加活动
或者,如果您希望 Google 日历用户更轻松地将某个活动添加为一次性活动,而无需持续对其进行更新,您可以提供包含预填充活动的链接,供用户自行添加。此方法会在用户的日历上创建一个不同的活动,除非您有权访问用户的日历,否则无法更新活动。
请使用以下链接模板:
https://calendar.google.com/calendar/r/eventedit?action=TEMPLATE&dates=20230325T224500Z%2F20230326T001500Z&stz=Europe/Brussels&etz=Europe/Brussels&details=EVENT_DESCRIPTION_HERE&location=EVENT_LOCATION_HERE&text=EVENT_TITLE_HERE
方法是更新以下信息:
- 开始和结束日期和时间:请使用 ISO 8601 格式。在上面的示例中,替换
20230325T224500Z
和20230326T001500Z
。 - 开始和结束时区:采用 IANA 时区数据库名称的格式。
请将时区放在
stz
和etz
字段中。 - 活动说明:必须经过网址编码。
- 活动地点:必须经过网址编码。
- 活动标题:必须经过网址编码。
示例
让我们考虑一下构建预约服务以帮助用户进行商家预约的示例。当用户进行预约时,您希望自己的服务向预订者及商家的 Google 日历添加活动。
为了提供最佳用户体验,我们建议商家向其日历授予写入权限,以便将活动直接添加到商家的日历中(创建活动),并邀请预订者参加活动(添加参加者)。为确保预订者能够在日历中看到活动并收到提醒,请通知他们查看电子邮件,并在预订后立即回复“是”。他们回复活动后,系统会根据其通知设置收到来自 Google 日历的活动通知。
如果您想将活动直接添加到预订者的日历中,请告知预订者将用于接收邀请的电子邮件地址添加到其联系人中。或者,您可以请求预订者向其日历的写入权限,以程序化方式代表他们回复(设置参与者的回复),并向他们发送有关已确认预订的电子邮件通知。
如果企业不想公开其电子邮件地址,可使用用户专属电子邮件地址,通过电子邮件地址将活动发送给预订者(通过电子邮件地址邀请用户)。
事件传播
下图说明了动态因素。首先,Jack 在他的主日历上创建了一个活动(因此拥有组织者的副本)。然后,他邀请了大提琴课程组的辅助日历和活动设置 Only if the sender is known
的 Susan。参与者会在大提琴课组辅助日历上创建参与者的副本,如果 Susan 认识 Jack,则会在 Susan 的日历上创建副本,否则,当她回复或表明自己认识 Jack 时,则会创建参与者的副本。当 Susan 响应时,RSVP 更改会传播回组织者,并使用 Susan 的响应更新组织者的副本。对组织者的活动副本所做的更改随后会传播到其他参加者。
共享事件属性
创建活动的日历是组织者日历。此日历拥有共享的活动信息,包括 ID、开始和结束时间、摘要和说明。在组织者日历中更新此信息后,相应更改会传播到参加者的副本中。
私人活动属性
并非所有事件副本都会共享所有信息。某些属性是私有属性,例如提醒、colorId
、透明度或 extendedProperties.private
属性。这些属性由参加者的设置控制,而不是由组织者日历控制。
参加者还可以更改活动的共享属性。但是,这些更改只会反映在它们自己的副本上,如果组织者进行更改,可能会丢失。
从参加者传播回组织者的唯一事件更改是参加者的响应状态(存储在 attendees[].responseStatus
属性中)。