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

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

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

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

Предварительные требования

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

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

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

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

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

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

Режим импорта поддерживает пространства с SpaceType SPACE и GROUP_CHAT , но не DIRECT_MESSAGE .

Чтобы импортировать переписку между двумя людьми или между человеком и приложением чата, импортируйте переписку в пространство для двух участников с SpaceType SPACE или GROUP_CHAT .

Создайте пробел в режиме импорта.

Чтобы создать пространство в режиме импорта, вызовите метод 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 (например, сообщения, реакции, вложения) в режиме импорта. При создании ресурса в этом режиме указываются данные из связанного ресурса с той платформы обмена сообщениями, с которой осуществляется миграция.

Сообщения

Ваши приложения для чата могут импортировать сообщения, используя собственные полномочия, или от имени пользователя путем имитации. Автором сообщения устанавливается учетная запись пользователя, от имени которого осуществляется имитация. Для получения дополнительной информации см. раздел «Авторизация приложений для чата» . Чтобы импортировать сообщение в пространстве режима импорта, вызовите метод create ресурса Message . Чтобы сохранить время создания исходного сообщения на исходной платформе обмена сообщениями, вы можете установить значение createTime для сообщения. Это значение createTime должно находиться в диапазоне между временем создания в пространстве, которое вы установили ранее, и текущим временем.

Сообщения в одном и том же пространстве не могут иметь одинаковое createTime , даже если предыдущие сообщения с этим временем были удалены.

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

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

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

"""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 : имя пространства, созданного в режиме импорта .

Реакции

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

Вложения

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

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

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

Во многих случаях, когда на этих участников из прошлого распространяется политика хранения данных Google , вам необходимо сохранить данные (например, сообщения и реакции), созданные участниками из прошлого, в пространстве перед импортом их в Чат. Пока пространство находится в режиме импорта, вы можете импортировать эти данные об участниках из прошлого, используя метод 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 чата.

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

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

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

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

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

Согласовать различия в импортированных ресурсах с исходными данными.

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

Сообщения

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

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

Реакции

Чтобы удалить реакцию для сообщения в пространстве режима импорта, используйте метод delete ресурса reactions . Информацию о методах ресурсов и типах поддерживаемой аутентификации в пространствах режима импорта см. в разделе Authorize Chat apps .

Вложения

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

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

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

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

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

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

Для удаления пространства в режиме импорта используйте метод delete ресурса spaces .

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

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

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

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

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

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

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

Для использования этих методов в рамках области chat.import , пользователь, от имени которого осуществляется операция, должен быть администратором пространства.

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

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

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

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

Импорт не был завершен до истечения 90-дневного срока.

Как уже описывалось ранее в разделе «Создание пространства в режиме импорта» , если пространство остается в режиме импорта по истечении 90 дней с момента вызова метода создания, оно автоматически удаляется и становится недоступным и невосстановимым.

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

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

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

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