Импортируйте данные в Google Chat

С помощью API Google Chat вы можете импортировать данные из других платформ обмена сообщениями в Google Chat. Вы можете импортировать существующие сообщения, вложения, реакции, данные о членстве и сущности чат-групп из других платформ обмена сообщениями в соответствующие ресурсы API чата . Вы можете импортировать эти данные, создав чат-группы в режиме импорта и импортировав в них данные. После успешного завершения процесса эти чат-группы становятся стандартными чат-группами.

Ниже описывается полный процесс импорта:

1. Планируйте свой импорт
2. Настройте авторизацию для приложения «Чат»
3. Создать пространство в режиме импорта
4. Импорт ресурсов
5. Проверить импортированные ресурсы
6. Устранение различий в импортируемых ресурсах с исходными данными
7. Полный режим импорта
8. Предоставить доступ к пространству после режима импорта
9. Поиск неисправностей

Предпосылки

Планируйте свой импорт

Планируйте объём импортируемых данных соответствующим образом, учитывайте, как ограничения и квоты на использование могут повлиять на процесс импорта, а также учитывайте типы чат-пространств, поддерживаемые при импорте в новое пространство. Если вы администратор, ознакомьтесь со статьёй «Импорт данных сообщений в Google Chat из другого сервиса» и внимательно следуйте инструкциям.

Просмотреть ограничения на использование API

Время, необходимое для импорта данных в Chat, может значительно варьироваться в зависимости от количества импортируемых ресурсов Chat. Проверьте ограничения использования вашего приложения Chat и объём данных, запланированных для импорта с исходной платформы обмена сообщениями, чтобы определить предполагаемые сроки.

При импорте сообщений в пространство мы рекомендуем распределить вызовы метода messages.create() по разным потокам сообщений.

Определите поддерживаемые пространства для импорта

Режим импорта поддерживает только SpaceType SPACE и GROUP_CHAT . DIRECT_MESSAGE не поддерживается. Подробнее см. в документации по SpaceType .

Создать пространство в режиме импорта

Чтобы создать пространство в режиме импорта, вызовите метод create для ресурса Space и установите importMode в true .

При создании пространства в режиме импорта обратите внимание на следующее.

• Дата и время . Помните, что режим импорта должен быть завершён в течение 90 дней. Если пространство всё ещё находится в режиме импорта по истечении 90 дней с момента вызова метода spaces.create() , оно автоматически удаляется и становится недоступным и не подлежит восстановлению.
  • Используйте значение поля importModeExpireTime для отслеживания истечения 90-дневного срока.
  • Не используйте значение поля createTime для отслеживания истечения 90-дневного срока. Это не всегда то же самое, что и при вызове метода spaces.create() . При использовании режима импорта поле createTime можно установить равным исторической временной метке создания пространства в источнике, чтобы сохранить исходное время создания.
• Имя ресурса пространства ( name ) — уникальный идентификатор, который используется для извлечения информации о конкретном пространстве и на который ссылаются на последующих этапах при импорте контента в пространство.

Чтобы сохранить время создания эквивалентной сущности пространства из исходной платформы обмена сообщениями, можно задать createTime пространства. Значение createTime должно находиться в диапазоне от 1 января 2000 года до текущего момента.

Чтобы создать внешнее пространство в режиме импорта, установите externalUserAllowed значение true . После успешного завершения импорта вы сможете добавлять внешних пользователей.

В следующем примере показано, как создать пространство в режиме импорта:

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);
}

"""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 , даже если предыдущие сообщения с этим временем удалены.

Сообщения, содержащие сторонние URL-адреса в пространствах режима импорта, не могут отображать предварительный просмотр ссылок в Google Chat.

При создании сообщений в режиме импорта пространства не уведомляют и не отправляют электронные письма каким-либо пользователям, включая сообщения, содержащие упоминания пользователей .

В следующем примере показано, как создать сообщение в пространстве режима импорта:

"""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 может импортировать реакции на сообщения с помощью API Chat. Сведения о методах ресурсов и типах поддержки аутентификации в пространствах режима импорта см. в разделе «Авторизация приложений Chat» .

Вложения

Ваше приложение Chat может загружать вложения с помощью API Chat. Сведения о методах поддержки ресурсов и типах аутентификации в областях режима импорта см. в разделе «Авторизация приложений Chat» . Однако мы настоятельно рекомендуем использовать API Google Drive для загрузки вложений в виде файлов Google Drive и связывать URI файлов с соответствующими сообщениями в областях режима импорта для импорта вложений из других платформ обмена сообщениями, чтобы избежать превышения внутреннего лимита Google Chat на загрузку вложений.

Историческое членство

Исторические членства — это членства, созданные для пользователей, которые уже покинули исходное пространство на исходной платформе обмена сообщениями, но вы хотите сохранить их данные в Chat . Сведения о добавлении новых участников после того, как пространство больше не находится в режиме импорта, см. в разделе Создание ресурса членства .

Во многих случаях, когда на эти исторические участники распространяется политика хранения данных в Google , вы хотите сохранить данные (например, сообщения и реакции), созданные историческими участниками в пространстве, перед их импортом в Chat. Пока пространство находится в режиме импорта, вы можете импортировать эти исторические участники в пространство, используя метод create ресурса Membership . Чтобы сохранить время выхода из исторического членства, необходимо задать время deleteTime для членства. Это время выхода должно быть точным, поскольку оно влияет на то, какие данные для этих участников сохранять. Более того, время deleteTime должно быть после временной метки создания пространства и не должно быть будущей временной меткой.

Помимо deleteTime , вы также можете задать createTime для сохранения исходного времени присоединения к истории членства. В отличие от deleteTime , createTime не является обязательным. Если не задано, createTime автоматически рассчитывается путем вычитания 1 микросекунды из deleteTime . Если задано, createTime должно предшествовать deleteTime и не превышать время создания пространства. Эта информация createTime не используется для определения срока хранения данных и не отображается в инструментах администратора, таких как консоль администратора Google и Google Vault.

Хотя на исходной платформе обмена сообщениями у пользователя может быть несколько способов присоединиться к пространству и покинуть его (через приглашения, присоединение самостоятельно, добавление другим пользователем), в чате все эти действия представлены историческими полями createTime и deleteTime членства как добавление или удаление.

В следующем примере показано, как создать историческое членство в пространстве режима импорта:

"""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 : уникальный идентификатор пользователя .

Импорт ресурсов во внешнее пространство

Вы можете создать внешнее пространство в режиме импорта, используя только учетные данные пользователей вашей организации Workspace. Это применимо только пока пространство находится в режиме импорта. После завершения режима импорта внешние пользователи могут быть приглашены в импортированные пространства (см. раздел «Доступ »), а их учетные данные могут быть использованы для вызова API чата.

Проверить импортированные ресурсы

Ваше приложение Chat может считывать и проверять содержимое пространства режима импорта, вызывая метод list ресурса Message . Вы можете считывать ресурсы Reaction и Attachment из полей emojiReactionSummaries и attachment любого возвращаемого сообщения. Приложения Chat могут вызывать этот метод только от имени пользователя посредством олицетворения. Подробнее см. в разделе Авторизация приложений Chat .

Ваше приложение Chat также может читать отдельные сообщения для проверки, вызывая метод get ресурса Message . Приложения Chat могут вызывать этот метод только для чтения собственных сообщений, используя собственные полномочия. Подробнее см. в разделе Авторизация приложений Chat .

Приложения чата также могут выводить список истории членства, вызывая метод list ресурса Membership . После выхода из режима импорта метод list больше не отображает историю членства. Приложения чата могут вызывать этот метод только от имени пользователя, используя олицетворение. Подробнее см. в разделе Авторизация приложений чата .

Вы можете прочитать свойства пространства в режиме импорта, вызвав метод get ресурса Space . В ответе также будет указан параметр importModeExpireTime , что позволит вам корректно отслеживать время, необходимое для завершения процесса импорта. Приложения чата могут вызывать этот метод только с использованием собственных полномочий. Подробнее см. в разделе Авторизация приложений чата .

Устранение различий в импортируемых ресурсах с исходными данными

Если какой-либо импортированный ресурс больше не соответствует исходной сущности из исходной платформы обмена сообщениями из-за изменений в исходной сущности во время импорта, приложения Chat могут обратиться к API Chat для изменения импортированного ресурса чата. Например, если пользователь редактирует сообщение в исходной платформе обмена сообщениями после того, как оно было создано в Chat, приложения Chat могут обновить импортированное сообщение, чтобы оно отражало текущее содержание исходного сообщения.

Сообщения

Чтобы обновить поддерживаемые поля сообщения в пространстве режима импорта, вызовите метод update ресурса Message . Приложения чата могут вызывать этот метод только с теми же полномочиями, которые были использованы при создании первоначального сообщения. Если при создании первоначального сообщения вы использовали олицетворение пользователя, для обновления этого сообщения необходимо использовать того же олицетворенного пользователя.

Чтобы удалить сообщение в пространстве режима импорта, вызовите метод delete ресурса Message . Сообщения в пространстве режима импорта не обязательно должны быть удалены исходным создателем сообщения, их можно удалить, выдав себя за любого пользователя в домене. Приложения чата могут удалять только собственные сообщения, используя собственные полномочия. Подробнее см. в разделе Авторизация приложений чата .

Реакции

Чтобы удалить реакцию на сообщение в пространстве в режиме импорта, используйте метод delete ресурса reactions . Сведения о методах ресурсов и типах поддержки аутентификации в пространствах в режиме импорта см. в разделе «Авторизация приложений чата» .

Вложения

Чтобы обновить вложения к сообщению в пространстве в режиме импорта, используйте метод upload media . Сведения о методах ресурсов и типах поддержки аутентификации в пространствах в режиме импорта см. в разделе «Авторизация приложений чата» .

Историческое членство

Чтобы удалить историю членства в пространстве в режиме импорта, используйте метод delete ресурса Membership . После выхода пространства из режима импорта метод delete больше не позволяет удалять историю членства.

В пространстве, находящемся в режиме импорта, невозможно обновить историю членства. Чтобы исправить некорректно импортированную историю членства, необходимо сначала удалить её, а затем создать заново, пока пространство находится в режиме импорта.

Пространства

Чтобы обновить поддерживаемые поля в пространстве режима импорта, используйте метод patch в ресурсе spaces .

Чтобы удалить пространство режима импорта, используйте метод delete ресурса spaces .

Информацию о методах ресурсов и типах поддержки аутентификации в пространствах режима импорта см. в разделе Авторизация приложений чата .

Полный режим импорта

Перед вызовом метода completeImport необходимо убедиться, что проверка и согласование различий ресурсов завершены. Выход из режима импорта пространства — необратимый процесс, преобразующий пространство в режиме импорта в обычное пространство. В Chat нет индикатора, который бы связывал эти пространства с импортом данных.

Запишите дату и время вызова completeImport , имя ресурса пользователя, выполнившего вызов, и полученный ответ. Это может быть полезно, если вы столкнетесь с какими-либо проблемами и захотите их изучить.

Чтобы завершить режим импорта и сделать пространство доступным для пользователей, приложение Chat может вызвать метод completeImport ресурса Space . Приложения Chat могут вызывать этот метод только от имени пользователя посредством олицетворения. Подробнее см. в разделе Авторизация приложений Chat . Олицетворяемый пользователь добавляется в пространство в качестве менеджера пространства после завершения этого метода. Этот метод необходимо вызвать в течение 90 дней с момента первоначального вызова метода create.space . Попытка вызвать этот метод по истечении 90 дней приведет к сбою, поскольку пространство в режиме импорта будет удалено и больше недоступно для приложения Chat.

Олицетворяемый пользователь в методе completeImport не обязательно должен быть создателем пространства.

Не вызывайте completeImport слишком близко к importModeExpireTime , так как мы не можем гарантировать, что запрос поступит до importModeExpireTime , и могут возникнуть конфликты с обработкой данных в системах, запущенных по истечении времени. Мы рекомендуем вызывать completeImport как минимум за 30 минут до importModeExpireTime .

В следующем примере показано, как завершить режим импорта:

"""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 и олицетворение пользователя в течение 90 дней с момента первоначального вызова метода create.space() для выполнения следующих действий:

• Добавление участников в пространство : вызовите метод create() ресурса Membership . Мы рекомендуем приложениям Chat создавать ресурсы Membership сразу после завершения импорта пространства, чтобы приложения Chat могли продолжать использовать область действия chat.import и обеспечить доступ к пространству всем импортированным участникам. Следует отдавать приоритет добавлению участников, на которых может распространяться политика удержания Vault , которая позволяет сохранять импортированные сообщения, даже если срок их хранения истек.
• Задайте целевую аудиторию : вызовите метод update() ресурса Space . Чтобы узнать, как создавать и добавлять целевые аудитории, см. статью «Как сделать пространство Google Chat видимым для определенных пользователей в организации Google Workspace» .

Чтобы использовать эти методы с областью действия chat.import , олицетворяемый пользователь должен быть менеджером пространства.

Для внешних пространств метод member create() также позволяет приглашать пользователей за пределами вашей организации Workspace. Убедитесь, что вы понимаете все известные ограничения для внешних пользователей.

Поиск неисправностей

Если у вас возникли проблемы при импорте чат-пространств, ознакомьтесь со следующими рекомендациями. Если вы столкнулись с ошибкой, запишите её (скопируйте и вставьте текст в документ или сохраните снимок экрана) для дальнейшего использования и устранения неполадок.

После успешного импорта пространства CompleteImportSpace завершается со статусом OK .

Не завершил импорт до истечения 90-дневного периода

Как ранее было описано в разделе Создание пространства в режиме импорта , если пространство все еще находится в режиме импорта по истечении 90 дней с момента вызова метода create, оно автоматически удаляется и становится недоступным и не подлежащим восстановлению.

К сожалению, удаленное пространство больше не доступно и не подлежит восстановлению, и процесс импорта необходимо начать заново.

Если пространство не импортировалось из-за того, что в нем слишком много данных для импорта в течение 90-дневного окна с текущими ограничениями использования , разделите пространство на два или более меньших пространства для архивации и снова запустите процесс импорта.

Найти недостающие пробелы

Если вы не можете найти новое пространство чата, просмотрите следующую таблицу с ответом, полученным от CompleteImportSpace , чтобы увидеть объяснение и способ решения этой проблемы.