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

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

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

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

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

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

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

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

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

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

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

Режим импорта поддерживает только SpaceType SPACE . Он не поддерживает DIRECT_MESSAGE . Если вы являетесь участником программы Developer Preview , GROUP_CHAT также поддерживается. Дополнительную информацию см. в документации по SpaceType .

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

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

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

• Дата и время . Помните, режим импорта должен быть завершен в течение 30 дней. Если пространство по-прежнему находится в режиме импорта по истечении 30 дней с момента вызова метода spaces.create() , оно автоматически удаляется и становится недоступным и не подлежащим восстановлению.
  • Не используйте значение поля createTime для отслеживания истечения 30-дневного периода времени. Это не всегда то же самое, что при вызове метода 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 . Чтобы импортировать сообщение в пространство режима импорта, вызовите метод 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 может импортировать реакции на сообщения с помощью Chat API. Сведения о методах ресурсов и типах поддержки аутентификации в пространствах режима импорта см. в разделе Авторизация приложений чата .

Вложения

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

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

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

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

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

Хотя может быть несколько способов, с помощью которых пользователь может присоединиться и покинуть пространство на исходной платформе обмена сообщениями (через приглашения, присоединение самостоятельно, добавление другим пользователем), в Chat все эти действия представлены историческими полями 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. Это применимо только тогда, когда пространство находится в режиме импорта. Как только пространство завершит режим импорта , внешних пользователей можно будет пригласить присоединиться к импортированным пространствам (см. раздел «Доступ» ), а их учетные данные можно будет использовать для вызова Chat API.

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

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

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

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

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

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

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

Сообщения

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

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

Реакции

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

Вложения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда пространство успешно импортировано, CompleteImportSpace завершается со статусом OK .

Импорт не завершен до истечения 30-дневного периода.

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

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

Найдите недостающие места

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