借助 Google Chat API,您可以导入其他即时通讯平台中的数据 Google Chat 中。您可以导入现有消息、附件、回应, 会员和聊天室实体 对应 Chat API 资源。 您可以通过在以下位置创建 Chat 聊天室来导入这些数据: 导入模式 以及将数据导入这些聊天室。此过程成功完成后 这些聊天室会变为标准 Chat 聊天室。
下面概述了完整的导入流程:
前提条件
Apps 脚本
- Business 或 Enterprise 有权访问以下内容的 Google Workspace 账号: Google Chat。
- 创建 Google Cloud 项目。
- 启用并配置 Google Chat API,指定一个名称, 图标和说明。
- 创建一个独立的 Apps 脚本项目, 然后启用高级聊天服务。
- Chat 应用必须在全网域授权 授权,请参阅 授权 Chat 应用。
Python
- Business 或 Enterprise 有权访问以下内容的 Google Workspace 账号: Google Chat。
- 创建 Google Cloud 项目。
- 启用并配置 Google Chat API,指定一个名称, 图标和说明。
- Python 3.6 或更高版本
- pip 软件包管理工具
- Chat 应用必须在全网域授权 授权,请参阅 授权 Chat 应用。
制定导入计划
根据要导入的数据量制定相应计划,了解 用量限额和配额可能会影响 导入流程,并了解 Chat 聊天室的类型 导入至新聊天室时受支持。
查看 API 用量限额
将数据导入 Chat 所需的时间可能相差很大 具体取决于要导入的 Chat 资源数量。 查看 Chat 应用的 用量限额和计划的数据量 从源消息传递平台导入,以确定预计时间表。
将消息导入到聊天室时,建议将通话分散
发送至 messages.create()
方法。
确定要导入的支持聊天室
导入模式仅支持 SPACE
的 SpaceType
。它不支持
第 SpaceType
个,共 GROUP_CHAT
个或DIRECT_MESSAGE
。请参阅
SpaceType
的文档
。
在导入模式下创建聊天室
要在导入模式下创建聊天室,请调用
create
方法
在
Space
项资源
并将 importMode
设置为 true
。
在导入模式下创建聊天室时,请注意以下事项。
- 日期和时间 - 请注意,必须在 30 分钟内完成导入模式
天。如果聊天室在 30 天后仍处于导入模式
自调用
spaces.create()
方法之日起算。 自动删除,变得无法访问且无法恢复。- 请勿将
createTime
字段以跟踪 30 天期限的到期时间。这不是 始终与调用spaces.create()
方法时相同。时间 使用导入模式时,可以将createTime
字段设置为历史记录 创建聊天室的时间戳,以便 保留原始创建时间。
- 请勿将
- 聊天室资源名称 (
name
) - 用于检索有关 特定空间,并在导入内容时在后续步骤中引用
为了保留来源中等效空间实体的创建时间
则可以设置聊天室的 createTime
。这个
createTime
的值必须介于 2000 年 1 月 1 日到当前时间之间。
如需在导入模式下创建外部聊天室,请将 externalUserAllowed
设为 true
。
导入成功完成后,您可以添加外部用户。
以下示例展示了如何在导入模式下创建聊天室:
Apps 脚本
function createSpaceInImportMode() {
const space = Chat.Spaces.create({
spaceType: 'SPACE',
displayName: 'DISPLAY_NAME',
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': 'DISPLAY_NAME',
'importMode': True,
'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
}
)
.execute()
)
print(result)
替换以下内容:
EMAIL
:执行恢复操作的用户账号的电子邮件地址 通过全网域授权进行模拟。DISPLAY_NAME
:在其中创建的聊天室的名称 导入模式。此名称必须是向以下用户显示的聊天室的唯一名称: 聊天用户。我们建议使用与 从中导入数据的空间。
导入资源
如要从其他即时通讯平台导入资源,请创建 Google Chat 资源(例如邮件、回应、附件)。 在聊天室中创建资源时,您可以指定来自相关资源 从消息平台中迁移资源
消息
您的 Chat 扩展应用可以使用自己的授权导入消息,或者
代表用户进行模拟。将消息作者设置为
被模拟的用户账号。如需了解详情,请参阅
授权 Chat 应用。
要导入
消息,调用
create
方法
在
Message
资源。
为了保留来源中的原始消息的创建时间
则可以设置消息的 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 导入聊天室中的过往成员资格。
聊天室处于导入模式时,您可以导入这些以往的成员
进入聊天室
create
方法
在
Membership
资源。
为了保留历史成员资格的离开时间,您必须设置
会员的 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
: user。
导入外部聊天室中的资源
您只能使用凭据创建采用导入模式的外部聊天室 组织内用户的数据。这仅适用于 。创建好之后, 完成导入模式后,外部用户可以 受邀加入导入的聊天室(请参阅访问权限部分) 其凭据可用于调用 Chat API。
验证导入的资源
您的 Chat 应用可以回读并验证内容
调用
list
方法 (对
Message
资源。
您可以从任何返回消息的Reaction
Attachment
emojiReactionSummaries
和 attachment
字段。聊天应用可以:
只能通过模拟来代表用户调用此方法。有关
请参阅
授权 Chat 应用。
您的 Chat 应用也可以阅读以下用户的单条消息:
调用
get
方法
针对 Message
资源。
聊天应用只能通过如下方式调用此方法来阅读自己的消息:
自己的权力。如需了解详情,请参阅
授权 Chat 应用。
聊天应用还可以通过调用
list
方法
在
Membership
资源。
聊天室退出导入模式后,list
方法不会显示历史数据
会员服务。聊天应用只能在
通过模拟来代表用户。如需了解详情,请参阅
授权 Chat 应用。
您可以通过调用
get
方法
在
Space
资源。
Chat 应用只能使用自己的授权调用此方法。
如需了解详情,请参阅
授权 Chat 应用。
协调导入的资源与源数据之间的差异
如果任何导入的资源不再与来源中的原始实体匹配 因为在导入过程中原始实体发生变化, Chat 应用可以调用 Chat API 来修改 聊天资源。例如,如果用户修改了源消息中的消息 创建该消息的平台后 Chat 扩展应用可以更新导入的消息,以反映 原始邮件的当前内容。
消息
更新
支持的字段
在导入模式聊天室中的邮件上,调用
update
方法
在
Message
资源。
聊天应用调用此方法时所使用的授权与
在初始消息创建期间使用的值。如果您使用了用户模拟功能
必须由同一模拟用户
更新这条消息。
要在“导入模式”聊天室中删除邮件,请调用
delete
方法
在
Message
资源。
导入模式聊天室中的消息无需由原始聊天室删除
消息创建者,而且可以通过模拟网域中的任何用户来删除。
Chat 扩展应用只能使用自己的应用来删除自己的消息
授权。如需了解详情,请参阅
授权 Chat 应用。
回应
如要在导入模式聊天室中删除邮件的回应,请使用
delete
方法
针对 reactions
资源。有关资源方法和
身份验证支持的类型,请参阅
授权 Chat 应用。
附件
要在导入模式聊天室中更新邮件附件,请使用
针对 media
的 upload
方法
资源。有关身份验证的资源方法和类型的信息
支持在导入模式聊天室中使用,请参阅
授权 Chat 应用。
以往的会员身份
如要在导入模式聊天室中删除历史成员资格,请使用
delete
方法
在
Membership
资源。在
退出导入模式,delete
方法不允许您删除历史记录
会员服务。
您无法更新导入模式聊天室中的历史成员资格。如果您想 更正导入错误的历史成员资格,您需要将其删除 先在聊天室处于“导入”模式时重新创建该任务。
Spaces
更新
支持的字段
进入导入模式聊天室,请使用
patch
方法
针对 spaces
资源。
如需删除“导入模式聊天室”,请使用
delete
方法
针对 spaces
资源。
有关身份验证支持的资源方法和类型的信息 进入“import 模式聊天室” 授权 Chat 应用。
完成导入模式
在调用 completeImport
之前,
方法,您应确保验证和
协调资源差异
已完成。退出聊天室退出导入模式是不可逆转的过程,
将导入模式空间转换为常规空间。以下范围内没有指示器:
将这些聊天室归因于数据导入的 Chat。
记下您调用 completeImport
(资源名称)的日期和时间
且系统返回了响应。这些信息可能会有帮助
必须进行相关调查
为了完成导入模式并让聊天室可供用户访问,
Chat 应用可以对completeImport
Space
资源。
聊天应用只能通过
。如需了解详情,请参阅
授权 Chat 应用。
系统将模拟的用户作为
聊天室管理员
在此方法完成后运行。此方法必须在启用增强型转化后的 30 天内调用
初始 create.space
方法调用。如果您尝试在
持续时间已过 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 扩展应用可以继续使用 chat.import
范围和用户
在初次调用 create.space()
方法后的 30 天内进行模拟
以下:
- 向聊天室添加成员:调用
create()
方法 针对Membership
资源。我们建议 在聊天室导入完成后立即创建Membership
项资源 以确保 Chat 扩展应用能继续使用chat.import
范围,并确保所有导入的成员都有权访问 空间。 - 设置目标受众群体:调用
update()
方法 针对Space
资源。要了解如何创建和添加目标对象群组,请参阅 将 Google Chat 聊天室设置为可供特定用户在 Google Workspace 组织。
如需将这些方法用于 chat.import
范围,被模拟的用户必须
成为聊天室管理员。
对于外部聊天室,
create()
方法
还可以邀请您的 Workspace 组织外部的用户。请确保
你了解了
已知限制
外部用户
问题排查
如果您在导入 Chat 聊天室时遇到问题,请查看 以获取帮助。如果遇到错误响应, 备注(将文本复制/粘贴到文档中或保存屏幕截图) 参考和问题排查
聊天室成功导入后,CompleteImportSpace
会以如下形式完成:
状态为 OK
。
未在 30 天的期限之前完成导入
如果如上文在导入模式下创建聊天室中所述, 在从 create 方法创建之日起 30 天后,该聊天室仍处于导入模式 被调用时,它会被自动删除,并且无法访问, 且不可恢复。
很抱歉,已删除的空间不再可用或恢复,并且 必须再次启动导入流程。
查找缺失的聊天室
如果您找不到新的 Chat 聊天室,请查看
下表中列出了 CompleteImportSpace
至
查看说明和解决方法。
已收到回答 | 调查步骤 | 说明 | 分辨率 |
---|---|---|---|
CompleteImportSpace 会抛出异常并调用
GetSpace 会返回 PERMISSION_DENIED 。 |
查看相关记录,了解聊天室的创建时间和创建时间是否早于 系统会自动将其删除。此外, 中导入空间的 聊天室管理工具 或审核日志。 | 导入流程开始后已超过 30 天 且聊天室未能成功退出迁移。 | 请创建一个新聊天室,然后重新运行导入过程。 |
CompleteImportSpace 返回 OK 并调用
GetSpace 会返回 PERMISSION_DENIED 。 |
在 聊天室管理工具 但该聊天室在 审核日志。 | 聊天室已成功导入,但随后被删除。 | 请创建一个新聊天室,然后重新运行导入过程。 |