借助 Google Chat API,您可以将其他即时通讯平台中的数据导入到 Google Chat。您可以将其他即时通讯平台中的现有消息、附件、回应、会员资格和聊天室实体导入到相应的 Chat API 资源。您可以通过在导入模式下创建 Chat 聊天室并将数据导入这些聊天室来导入这些数据。此过程成功完成后,这些聊天室会成为标准 Chat 聊天室。
- 查看 API 用量限额并提前规划。
- 为 Chat 应用配置授权。
- 在导入模式下创建聊天室。
- 导入资源。
- 验证导入的资源。
- 协调导入的资源与源数据之间的差异。
- 完全导入模式。
- 在导入模式后授予对聊天室的访问权限。
前提条件
Apps 脚本
- 一个有权访问 Google Chat 的 Google Workspace 帐号。
- 一个已发布的 Chat 应用。如需构建 Chat 应用,请按照此quickstart进行操作。
Python
- Python 3.6 或更高版本
- pip 软件包管理工具
适用于 Python 的最新 Google 客户端库。如需安装或更新这些应用,请在命令行界面中运行以下命令:
pip3 install --upgrade google-api-python-client google-auth
已发布的 Chat 应用。如需创建和发布 Chat 应用,请参阅构建 Google Chat 应用。
为 Chat 应用配置的授权。Chat 应用必须在应用导入内容的任何网域中被委派的全网域授权,请参阅向 Chat 应用授权。
查看 API 用量限额并提前规划
将数据导入 Chat 所需的时间差异很大,具体取决于要导入的 Chat 资源数量。请提前规划,查看您的 Chat 应用的用量限额以及计划从源消息传递平台导入的数据量,以确定预计时间表。
在导入模式下创建聊天室
如需在导入模式下创建聊天室,请对 Space
资源调用 create
方法,并将 importMode
设置为 true
。为了保留源消息传递平台中等效空间实体的创建时间,您可以设置空间的 createTime
。此 createTime
必须设置为 2000 年 1 月 1 日至今的值。
记下您创建的空间的 name
,以便在后续步骤中将内容导入到聊天室时引用它。
从调用 create
方法开始,Chat 应用有 30 天的时间来将资源导入到聊天室、完成导入模式,以及使用 chat.import
范围授予对聊天室的访问权限。30 天后,Chat 应用仍可以通过标准 Chat API 成员资格范围创建成员资格。30 天后,如果聊天室仍处于导入模式,系统会自动将其删除,删除后将无法访问,也无法恢复。请提前查看 Chat 应用的用量限额,确保在此时间范围内将所有安排的资源导入 Chat。
以下示例展示了如何在导入模式下创建聊天室:
Apps 脚本
function createSpaceInImportMode() {
const space = Chat.Spaces.create({
spaceType: 'SPACE',
displayName: 'Import Mode Space',
importMode: true,
createTime: (new Date('January 1, 2000')).toJSON()
});
console.log(space.name);
}
Python
"""Create a space in import mode."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
result = (
service.spaces()
.create(
body={
'spaceType': 'SPACE',
'displayName': 'Import Mode Space',
'importMode': True,
'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
}
)
.execute()
)
print(result)
请替换以下内容:
EMAIL
:您通过全网域授权模拟的用户帐号的电子邮件地址。
导入资源
如需从其他消息传递平台导入资源,请在导入模式聊天室中创建 Google Chat 资源(例如消息、回应和附件)。在聊天室中创建资源时,您可以指定来自要迁移的消息平台的相关资源的数据。
信息
您的 Chat 应用可以使用自己的授权或者通过模拟来代表用户导入消息。(消息作者设置为模拟用户帐号。)如需了解详情,请参阅向 Chat 扩展应用授权。如需在导入模式空间中导入消息,请对 Message
资源调用 create
方法。为了保留来自源消息传递平台的原始消息的创建时间,您可以设置消息的 createTime
。此 createTime
必须设置为您之前设置的空间创建时间与当前时间之间的值。
同一聊天室中的消息不能包含相同的 createTime
,即使之前具有该时间的消息已被删除。
在导入模式聊天室中,包含第三方网址的消息无法在 Google Chat 中呈现链接预览。
在导入模式下创建消息时,聊天室不会通知任何用户,也不会向任何用户发送电子邮件,包括包含用户提及的消息。
以下示例展示了如何在“导入模式”聊天室中创建消息:
Python
"""Create a message in import mode space."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
result = (
service.spaces()
.messages()
.create(
parent=NAME,
body={
'text': 'Hello, world!',
'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
},
)
.execute()
)
print(result)
请替换以下内容:
EMAIL
:您通过全网域授权模拟的用户帐号的电子邮件地址。SPACE_NAME
:在导入模式下创建的空间的名称。
回应
您的 Chat 应用可以使用 Chat API 导入对消息的回应。如需了解导入模式聊天室中的资源方法和身份验证支持类型,请参阅向 Chat 应用授权。
附件
您的 Chat 应用可以使用 Chat API 上传附件。如需了解导入模式聊天室中的资源方法和身份验证支持类型,请参阅向 Chat 应用授权。但是,我们强烈建议您使用 Google Drive API 将附件作为 Google 云端硬盘文件上传,并将文件 URI 链接到导入模式聊天室中的相应消息,以从其他消息传递平台导入附件,以免达到 Google Chat 内部上传附件限制。
以往的会员身份
历史成员资格是为以下用户创建的成员资格:已从来源消息传递平台退出原始聊天室实体,但您希望在 Chat 中保留其数据。如需了解如何在聊天室不再处于导入模式后添加新成员,请参阅创建成员资格资源。
在许多情况下,当这些历史成员受 Google 中的数据保留政策约束时,您希望先保留聊天室中的历史成员创建的数据(例如消息和回应),然后再将其导入 Chat。当聊天室处于导入模式时,您可以对 Membership
资源使用 create
方法,将这些历史成员导入到聊天室。为了保留历史成员资格的离开时间,您必须设置成员资格的 deleteTime
。保留时间必须准确无误,因为它会影响为这些成员资格保留哪些数据。此外,此 deleteTime
必须晚于聊天室创建时间戳,而不得是未来的时间戳。
除了 deleteTime
之外,您还可以设置 createTime
以保留历史成员资格的原始加入时间。与 deleteTime
不同,createTime
是可选的。如果未设置,则系统会自动计算 createTime
,方法是从 deleteTime
中减去 1 微秒。如果设置,createTime
必须在 deleteTime
之前,且不得早于空间创建时间。这些 createTime
信息不会用于确定数据保留,也不会在 Google 管理控制台和 Google 保险柜等管理工具中显示。
虽然用户可以通过多种方式加入和退出来源消息传递平台中的聊天室(通过邀请、自行加入、由其他用户添加),但在 Chat 中,这些操作都通过历史成员资格 createTime
和 deleteTime
字段来表示,这些操作都是添加或移除的。
以下示例展示了如何在导入模式空间中创建历史成员资格:
Python
"""Create a historical membership in import mode space."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
service.spaces()
.members()
.create(
parent=NAME,
body={
'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
'member': {'name': USER, 'type': 'HUMAN'},
},
)
.execute()
)
print(result)
请替换以下内容:
EMAIL
:您通过全网域授权模拟的用户帐号的电子邮件地址。SPACE_NAME
:在导入模式下创建的空间的名称。USER_ID
:用户的唯一 ID。
验证导入的资源
您的 Chat 应用可以对 Message
资源调用 list
方法 ,从而回读并验证导入模式聊天室的内容。您可以从任何返回消息的 emojiReactionSummaries
和 attachment
字段中读取 Reaction
和 Attachment
资源。聊天应用只能通过模拟代表用户调用此方法。如需了解详情,请参阅向 Chat 扩展应用授权。
您的 Chat 应用还可以通过对 Message
资源调用 get
方法,读取单条消息进行验证。聊天应用只能通过使用自己的授权来调用此方法来读取自己的消息。如需了解详情,请参阅向 Chat 扩展应用授权。
聊天应用还可以通过对 Membership
资源调用 list
方法列出历史成员资格。聊天室退出导入模式后,list
方法将不再公开历史成员资格。聊天应用只能通过模拟代表用户调用此方法。如需了解详情,请参阅向 Chat 扩展应用授权。
您可以通过对 Space
资源调用 get
方法来读取导入模式空间的属性。Chat 应用只能使用自己的授权调用此方法。如需了解详情,请参阅向 Chat 扩展应用授权。
协调导入的资源与源数据之间的差异
如果由于导入过程中原始实体发生变化,任何导入的资源不再与源消息传递平台中的原始实体匹配,Chat 应用可以调用 Chat API 来修改导入的聊天资源。例如,如果在 Chat 中创建消息后,用户又在来源消息传递平台中修改了该消息,则 Chat 应用可以更新导入的消息,使其反映原始消息的当前内容。
信息
如需更新导入模式空间中消息的受支持字段,请对 Message
资源调用 update
方法。聊天应用调用此方法时所使用的授权与初始消息创建期间所使用的授权相同。如果您在初始消息创建期间使用了用户模拟,则必须使用同一模拟用户来更新相应消息。
如需在导入模式聊天室中删除消息,请对 Message
资源调用 delete
方法。导入模式聊天室中的消息不需要由原始消息创建者删除,可以通过模拟网域中的任何用户来删除。聊天应用只能通过自己的权限删除自己的消息。如需了解详情,请参阅向 Chat 扩展应用授权。
回应
如需在导入模式聊天室中删除对邮件的回应,请对 reactions
资源使用 delete
方法。如需了解导入模式聊天室中的资源方法和身份验证支持类型,请参阅向 Chat 应用授权。
附件
如需在导入模式聊天室中更新邮件的附件,请对 media
资源使用 upload
方法。如需了解导入模式聊天室中的资源方法和身份验证支持类型,请参阅向 Chat 应用授权。
以往的会员身份
如需删除导入模式聊天室中的历史成员资格,请对 Membership
资源使用 delete
方法。聊天室退出导入模式后,您将无法再通过 delete
方法删除历史成员资格。
您无法更新导入模式聊天室中的历史成员资格。如果要更正导入错误的历史成员资格,您需要先将其删除,然后在聊天室仍处于导入模式时重新创建该成员资格。
聊天室
如需更新导入模式空间中支持的字段,请对 spaces
资源使用 patch
方法。
如需删除导入模式空间,请对 spaces
资源使用 delete
方法。
如需了解导入模式聊天室中的资源方法和身份验证支持类型,请参阅向 Chat 应用授权。
完成导入模式
在调用 completeImport
方法之前,您应确保已完成验证和资源差异协调。退出导入模式空间是一个不可逆转的过程,并且会将导入模式空间转换为常规空间。Chat 中没有用于将这些聊天室归因于数据导入的指示符。
为了完成导入模式并允许用户访问聊天室,Chat 应用可以对 Space
资源调用 completeImport
方法。聊天应用只能通过模拟代表用户调用此方法。如需了解详情,请参阅向 Chat 扩展应用授权。此方法完成后,模拟用户会作为聊天室管理员添加到聊天室。首次调用 create.space
方法后,必须在 30 天内调用此方法。如果您在 30 天期限过后尝试调用此方法,调用将导致失败,因为导入模式空间将被删除,Chat 应用无法再访问该空间。
completeImport
方法中模拟的用户无需是聊天室创建者。
以下示例展示了如何完成导入模式:
Python
"""Complete import."""
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()
print(result)
请替换以下内容:
EMAIL
:您通过全网域授权模拟的用户帐号的电子邮件地址。SPACE_NAME
:在导入模式下创建的空间的名称。
在导入模式后授予对聊天室的访问权限
为了向 Chat 用户授予对最近导入的聊天室的访问权限,Chat 应用可以在初次调用 create.space()
方法后的 30 天内继续使用 chat.import
范围和用户模拟,以执行以下操作:
- 向聊天室添加成员:对
Membership
资源调用create()
方法。我们建议 Chat 应用在聊天室导入完成后立即创建Membership
资源,以便 Chat 应用可以继续使用chat.import
范围,并确保所有导入的成员都有权访问该聊天室。 - 设置目标对象群组:对
Space
资源调用update()
方法。如需了解如何创建和添加目标对象群组,请参阅将 Google Chat 聊天室设置为可供 Google Workspace 组织中的特定用户检测到。
如需将这些方法与 chat.import
范围搭配使用,被模拟的用户必须是聊天室管理员。