将数据导入 Google Chat

借助 Google Chat API，您可以将其他即时通讯平台中的数据导入到 Google Chat。您可以将其他即时通讯平台中的现有消息、附件、回应、成员资格和聊天室实体导入到相应的 Chat API 资源。您可以在导入模式下创建 Chat 聊天室，并将数据导入到这些聊天室中，从而导入这些数据。此过程成功完成后，这些聊天室将变为标准 Chat 聊天室。

以下概述了完整的导入流程：

  1. 规划导入
  2. 为 Chat 应用配置授权
  3. 在导入模式下创建聊天室
  4. 导入资源
  5. 验证导入的资源
  6. 协调源数据中导入的资源差异
  7. 完整导入模式
  8. 在导入模式后授予对聊天室的访问权限
  9. 问题排查

前提条件

Apps 脚本

Python

规划导入

相应地规划要导入的数据量，了解使用限制和配额如何影响导入过程，并了解将数据导入新聊天室时支持哪些类型的聊天室。如果您是管理员，请阅读将消息数据从其他服务导入到 Google Chat，并仔细按照其中的步骤操作。

查看 API 使用限制

将数据导入 Chat 所需的时间可能会因要导入的 Chat 资源数量而异。查看 Chat 应用的使用限制以及计划从源消息传递平台导入的数据量，以确定预计的时间表。

将消息导入聊天室时，建议您将对 messages.create() 方法的调用分散到不同的消息线程中。

确定要导入的受支持空间

导入模式仅支持 SPACE 和 GROUP_CHAT 的 SpaceType。不支持 DIRECT_MESSAGE。 如需了解详情，请参阅 SpaceType 的文档。

以导入模式创建聊天室

如需在导入模式下创建空间，请对 Space 资源调用 create 方法，并将 importMode 设置为 true。

以导入模式创建聊天室时，请注意以下事项。

  • 日期和时间 - 请注意，必须在 90 天内完成导入模式。如果聊天室在 spaces.create() 方法调用后 90 天仍处于导入模式，则会自动遭到删除，并且将无法访问和不可恢复。
    • 使用 importModeExpireTime 字段的值来跟踪 90 天期限的到期情况。
    • 请勿使用 createTime 字段的值来跟踪 90 天期限的到期情况。这并不总是与调用 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：在导入模式下创建的空间的名称。此名称必须是向 Chat 用户显示的会议室的唯一名称。建议使用与要从中导入数据的空间相同的显示名称。

导入资源

如需从其他即时通讯平台导入资源，您需要在导入模式聊天室中创建 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 是可选的。如果未设置，系统会自动通过从 deleteTime 中减去 1 微秒来计算 createTime。如果设置了 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。

在外部聊天室中导入资源

您只能使用属于 Workspace 组织内用户的凭据，以导入模式创建外部聊天室。此设置仅在聊天室处于导入模式时适用。聊天室完成导入模式后，可以邀请外部用户加入导入的聊天室（请参阅访问权限部分），并且可以使用其凭据调用 Chat API。

验证导入的资源

您的聊天应用可以通过对 Message 资源调用 list 方法 来回读并验证导入模式空间的内容。您可以从任何返回的消息的 emojiReactionSummaries 和 attachment 字段中读取 Reaction 和 Attachment 资源。聊天应用只能通过模拟来代表用户调用此方法。如需了解详情，请参阅授权 Chat 应用。

您的聊天应用还可以通过对 Message 资源调用 get 方法来读取单个消息以进行验证。聊天应用只能使用自己的权限调用此方法来读取自己的消息。如需了解详情，请参阅授权 Chat 应用。

聊天应用还可以通过对 Membership 资源调用 list 方法来列出历史成员资格。 聊天室退出导入模式后，list 方法不再公开历史成员资格。聊天应用只能通过模拟用户身份来代表用户调用此方法。如需了解详情，请参阅授权 Chat 应用。

您可以通过对 Space 资源调用 get 方法来读取导入模式空间的属性。响应中还会填充 importModeExpireTime，以便您正确跟踪完成导入过程的时间范围。 聊天应用只能使用自己的授权调用此方法。 如需了解详情，请参阅授权 Chat 应用。

根据源数据协调导入的资源差异

如果任何导入的资源因原始实体在导入期间发生更改而不再与源消息传递平台中的原始实体匹配，Chat 应用可以调用 Chat API 来修改导入的聊天资源。例如，如果用户在 Chat 中创建消息后，在源消息平台中修改了该消息，Chat 应用可以更新导入的消息，使其反映原始消息的当前内容。

消息

如需更新导入模式空间中消息的支持的字段，请对 Message 资源调用 update 方法。聊天应用只能使用初始消息创建期间使用的同一授权来调用此方法。如果您在首次创建消息时使用了用户模拟，则必须使用同一模拟用户来更新该消息。

如需删除导入模式空间中的消息，请对 Message 资源调用 delete 方法。在导入模式聊天室中，消息无需由原始消息创建者删除，而是可以通过模拟网域中的任何用户来删除。 聊天应用只能使用自己的权限删除自己的消息。如需了解详情，请参阅授权 Chat 应用。

回应

如需删除导入模式空间中消息的表情回应，请对 reactions 资源使用 delete 方法。如需了解导入模式聊天室中的资源方法和支持的身份验证类型，请参阅授权 Chat 应用。

附件

如需更新导入模式空间中消息的附件，请对 media 资源使用 upload 方法。如需了解导入模式聊天室中的资源方法和支持的身份验证类型，请参阅授权 Chat 应用。

历史会员资格

如需删除导入模式空间中的历史成员资格，请对 Membership 资源使用 delete 方法。空间退出导入模式后，delete 方法不再允许您删除历史成员资格。

您无法在导入模式聊天室中更新历史成员。如果您想更正错误导入的历史会员资格，需要先将其删除，然后在聊天室仍处于导入模式时重新创建。

Spaces

如需更新导入模式空间中的受支持的字段，请对 spaces 资源使用 patch 方法。

如需删除导入模式空间，请对 spaces 资源使用 delete 方法。

如需了解导入模式空间中的资源方法和支持的身份验证类型，请参阅授权 Chat 应用。

完整导入模式

在调用 completeImport 方法之前，您应确保已完成验证和资源差异协调。退出导入模式聊天室是不可逆转的过程，并且会将导入模式聊天室转换为常规聊天室。在 Chat 中，没有任何指标可将这些聊天室归因于数据导入。

记下您调用 completeImport 的日期和时间、拨打电话的用户的资源名称，以及返回的响应。如果您遇到任何问题并需要进行调查，这会很有帮助。

如需完成导入模式并让用户可以访问相应聊天室，Chat 应用可以对 Space 资源调用 completeImport 方法。聊天应用只能通过模拟用户身份来代表用户调用此方法。如需了解详情，请参阅授权 Chat 应用。 此方法完成后，模拟用户会作为聊天室管理员添加到聊天室。必须在首次调用 create.space 方法后的 90 天内调用此方法。如果您在 90 天期限过后尝试调用此方法，则调用会失败，因为导入模式的聊天室已被删除，Chat 应用无法再访问该聊天室。

completeImport 方法中的被模拟用户不必是聊天室创建者。

请勿在 importModeExpireTime 之前过早调用 completeImport，因为我们无法保证请求会在 importModeExpireTime 之前到达，并且可能会与在过期时间触发的系统中的数据处理发生冲突。我们建议您至少在 importModeExpireTime 前 30 分钟致电 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() 方法后的 90 天内继续使用 chat.import 范围和用户模拟功能来执行以下操作：

如需将这些方法与 chat.import 范围搭配使用，被模拟的用户必须是空间管理员。

对于外部聊天室，成员资格create()方法还允许邀请 Workspace 组织以外的用户。请务必了解外部用户的所有已知限制。

问题排查

如果您在导入 Chat 群组时遇到问题，请查看以下问题以寻求帮助。如果您遇到错误响应，请记下该响应（将文本复制/粘贴到文档中或保存屏幕截图），以供日后参考和排查问题。

成功导入空间后，CompleteImportSpace 会以 OK 状态完成。

未在 90 天期限到期前完成导入

如创建处于导入模式的聊天室中所述，如果聊天室在调用创建方法 90 天后仍处于导入模式，则会自动遭到删除，并且将无法访问和不可恢复。

很遗憾，已删除的聊天室无法再恢复，您必须重新启动导入流程。

如果因空间中的数据量过大而无法在 90 天内完成导入（受当前使用限制的约束），请将该空间拆分为两个或更多个较小的空间以进行归档，然后重新开始导入流程。

查找缺失的聊天室

如果您找不到新的 Chat 聊天室，请查看下表，了解您从 CompleteImportSpace 收到的回复，以及相应说明和问题解决方法。

已收到回答 调查步骤 说明 分辨率
CompleteImportSpace 抛出异常，调用 GetSpace 返回 PERMISSION_DENIED。 查看记录，了解聊天室的创建时间。如果聊天室的创建时间超过 90 天，则会被自动删除。此外，聊天室管理工具或审核日志中也没有导入聊天室的记录。 自导入流程开始以来已超过 90 天，但相应聊天室未能成功退出迁移。 创建新聊天室，然后再次运行导入流程。
CompleteImportSpace 返回 OK，调用 GetSpace 返回 PERMISSION_DENIED。 空间管理工具中没有导入空间的记录，但审核日志中显示该空间已被删除。 聊天室已成功导入，但随后被删除。 创建新聊天室，然后再次运行导入流程。