Импорт сообщений из сторонних платформ в Teams с помощью Microsoft Graph

С помощью Microsoft Graph можно перенести существующий журнал сообщений и данные пользователей из внешней системы в Teams. Пользователи могут легко продолжать общение и действовать без прерывания, включив воссоздание иерархии обмена сообщениями сторонних платформ в Teams.

Разрешения

Поддерживаемые типы каналов и чатов

Teams поддерживает перенос внешних сообщений в следующие каналы и типы чатов:

• Новая команда и стандартный канал. Создайте новую команду и ее стандартные каналы в режиме миграции для импорта содержимого. Такой подход позволяет импортировать точную структуру внешней системы в новый канал. Сведения о включении migrationMode новой стандартной команды и канала см. в статье Создание команды и стандартного канала в режиме миграции.

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

migrationMode — это специальное состояние, которое обеспечивает целостность данных, предотвращая следующие операции во время миграции данных.

• Для новых команд и стандартных каналов:
  • Он ограничивает получение новых сообщений
  • Это предотвращает добавление или удаление элементов
• Для всех поддерживаемых каналов и типов чатов:
  • Это позволяет импортировать исторические сообщения с пользовательскими метками времени.
  • Он поддерживает исходную структуру диалога и иерархию

Область содержимого для импорта

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

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

Анализ и подготовка данных сообщений

• Просмотрите сторонние данные, чтобы решить, что следует перенести.
• Извлеките выбранные данные из сторонней системы чата.
• Сопоставьте стороннюю структуру чата со структурой Teams.
• Преобразуйте данные импорта в формат, необходимый для миграции.

Настройка клиента Microsoft 365

• Убедитесь, что для импорта данных существует клиент Microsoft 365. Дополнительные сведения о настройке клиента Microsoft 365 для Teams см. в статье Подготовка клиента Microsoft 365.
• Убедитесь, что члены команды находятся в Microsoft Entra ID. Дополнительные сведения см. в статье Добавление нового пользователя в Microsoft Entra ID.

Импорт исторических сообщений в Teams

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

1. Запуск миграции
2. Проверка состояния миграции
3. Импорт сообщений
4. Режим полной миграции
5. Проверка завершения режима миграции

Шаг 1. Начало миграции

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

• Создание команды и стандартного канала в режиме миграции
• Запуск миграции по существующим каналам и чатам

Создание команды и стандартного канала в режиме миграции

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

Создать новую команду

• Создайте команду с меткой времени "назад во времени" с помощью createdDateTime свойства .
• Поместите новую команду в migrationMode , задав для параметра teamCreationMode значение migration.

Запрос (создание команды в режиме миграции)

POST https://graph.microsoft.com/v1.0/teams
Content-Type:application/json

{
  "@microsoft.graph.teamCreationMode":"migration",
  "template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName":"My Sample Team",
  "description":"My Sample Team’s Description",
  "createdDateTime":"2020-03-14T11:22:17.043Z"
}

Отклик

HTTP/1.1 202 Accepted
Location: /teams/{team-id}/operations/{operation-id}
Content-Location: /teams/{team-id}

Сообщение об ошибке

400 Bad Request

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

• Если для createdDateTime настроено значение в будущем.
• Если параметр createdDateTime указан правильно, но отсутствует атрибут экземпляра teamCreationMode или ему присвоено недопустимое значение.

Создание канала

• Создайте новый канал с меткой времени "назад в времени" с помощью createdDateTime свойства ресурса канала.
• Переведите новый канал в режим миграции, задав для параметра channelCreationMode значение migration.

Запрос (создание канала в режиме миграции)

POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels
Content-Type: application/json

{
  "@microsoft.graph.channelCreationMode":"migration",
  "displayName":"Architecture Discussion",
  "description":"This channel is where we debate all future architecture plans",
  "membershipType":"standard",
  "createdDateTime":"2020-03-14T11:22:17.047Z"
}

Отклик

HTTP/1.1 202 Accepted

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels/$entity",
   "id":"id-value",
   "createdDateTime":null,
   "displayName":"Architecture Discussion",
   "description":"This channel is where we debate all future architecture plans",
   "isFavoriteByDefault":null,
   "email":null,
   "webUrl":null,
   "membershipType":null,
   "moderationSettings":null
}

Сообщение об ошибке

400 Bad Request

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

• Если для createdDateTime настроено значение в будущем.
• Если параметр createdDateTime указан правильно, но отсутствует атрибут экземпляра channelCreationMode или ему присвоено недопустимое значение.

После создания команды и стандартного канала выполните миграцию, выполнив следующие действия:

1. Проверка состояния миграции
2. Импорт сообщений
3. Режим полной миграции
4. Проверка завершения режима миграции

Запуск миграции по существующим каналам и чатам

В существующих каналах или чатах используйте startMigration API, чтобы включить режим миграции каналов или включить режимstartMigration миграции чата, чтобы задать состояние InProgress миграции и начать процесс импорта сообщений. Дополнительные сведения см. в разделе:

• Миграция существующего канала
• Миграция существующего чата

Миграция существующего канала

Чтобы включить режим миграции в существующих каналах, используйте startMigration API.

Запрос (существующий канал в режиме миграции)

POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/startMigration
{
  "conversationCreationDateTime":"2024-01-01T00:00:00Z"
}

Отклик

Если запрос выполнен успешно, метод возвращает пустой HTTP-ответ.

HTTP/1.1 204 No Content

Пример

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration
{
  "conversationCreationDateTime":"2024-01-01T00:00:00Z"
}

Миграция существующего чата

Чтобы включить режим миграции в существующих чатах, используйте startMigration API.

Запрос (существующий чат в режиме миграции)

POST https://graph.microsoft.com/beta/chats/{chat-id}/startMigration
{
  "conversationCreationDateTime":"2024-01-01T00:00:00Z"
}

Отклик

Если запрос выполнен успешно, метод возвращает пустой HTTP-ответ.

HTTP/1.1 204 No Content

Пример

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration 

{ 
  "conversationCreationDateTime":"2024-01-01T00:00:00Z" 
} 

Учитывайте следующие важные моменты.

• Определите минимальную метку времени для переносимого сообщения. Указанная метка времени должна быть старше текущей createdDateTimeверсии канала или чата. Эта метка времени заменяет существующий createdDateTime канал. При обновлении createdDateTime до прошлой метки времени вы не сможете снова переместить ее в будущую метку времени.
• Свойство creationDateTime является необязательным в тексте запроса. Если этот параметр опущен, startMigration API использует текущую дату и время в качестве минимальной метки времени.
• startMigration API запускает процесс миграции сообщений, задавая режим миграции в значение InProgress для указанного канала или чата.

Шаг 2. Проверка состояния миграции

Вызовите Get channel или Get chat , чтобы убедиться, migrationMode что для состояния задано значение InProgress. Дополнительные сведения см. в разделе:

• Получение канала
• Получение чата

Шаг 3. Импорт сообщений

Теперь вы можете импортировать сообщения с обратным временем, включив ключи createdDateTime и from в текст запроса.

Запрос (команда POST для сообщения, содержащего только текст)

POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages

{
   "createdDateTime":"2019-02-04T19:58:15.511Z",
   "from":{
      "user":{
         "id":"id-value",
         "displayName":"John Doe",
         "userIdentityType":"aadUser"
      }
   },
   "body":{
      "contentType":"html",
      "content":"Hello World"
   }
}

Отклик

HTTP/1.1 200 OK

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity",
   "id":"id-value",
   "replyToId":null,
   "etag":"id-value",
   "messageType":"message",
   "createdDateTime":"2019-02-04T19:58:15.58Z",
   "lastModifiedDateTime":null,
   "deleted":false,
   "subject":null,
   "summary":null,
   "importance":"normal",
   "locale":"en-us",
   "policyViolation":null,
   "from":{
      "application":null,
      "device":null,
      "conversation":null,
      "user":{
         "id":"id-value",
         "displayName":"Joh Doe",
         "userIdentityType":"aadUser"
      }
   },
   "body":{
      "contentType":"html",
      "content":"Hello World"
   },
   "attachments":[
   ],
   "mentions":[
   ],
   "reactions":[
   ]
}

Сообщение об ошибке

Если для свойства заданы дата и время в будущем, появляется следующее createdDateTime сообщение об ошибке.

400 Bad Request

Запрос (сообщение POST со встроенным изображением)

POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages

{
  "body": {
        "contentType":"html",
        "content": "<div><div>\n<div><span><img height=\"250\" src=\"../hostedContents/1/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
    },
    "hostedContents":[
        {
            "@microsoft.graph.temporaryId":"1",
            "contentBytes": "iVBORw0KGgoAAAANSUhEUgAAANcAAAExCAYAAADvFzeeAAAXjklEQVR4Ae2d/XNU1RnH+9e0FFrA0RCIyaS8hRA0HV5KbS1gHRgVpjMClY4GHJ3yYm1HCmXaWttaaZUZtIIFKYi8lFAkvOQ9u5vN225IARVBbX9/Os9NbrLZbMjmhCfJPX5+2Lmb3T25y3O+n/M599x7w9f+++UXwoMakIF7n4GvUdR7X1RqSk01A8CFuZm5GGUAuIwKi72wF3ABF+YyygBwGRUWc2Eu4AIuzGWUAeAyKizmwlzABVyYyygDwGVUWMyFuYALuDCXUQaAy6iwmAtzARdwfWXMdeuzT+TGxz3Sfb1LunrapL07IW3pePDQ5/qavqef0c+OdYAELuAac4jGGkLL9rdvfyo9N9ODQAqBGmmrwGlb/R0u3xG4gMspOC5hG882CoRaaCSA8n1ff9doIQMu4PIOrus3u+8ZVNnw6e/Od5AALuDKOyz5hmqiPnfnzi1J9bSbgRWCpvvQfY307wQu4BoxJCOFaDK8rwsQmQsUIQhWW93XSIsewAVckYdLQ24F0Ui/926AARdwRRounZ6Np7GyYdN9DzdFBC7gijRc43GMlQ1U9s/6HXJNjYELuHI<<-----Removed----->>>>",
            "contentType": "image/png"
        }
    ]
}

Отклик

HTTP/1.1 200 OK

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity",
    "id":"id-value",
    "replyToId":null,
    "etag":"id-value",
    "messageType":"message",
    "createdDateTime": "2019-02-04T19:58:15.511Z",
    "lastModifiedDateTime":null,
    "deleted":false,
    "subject":null,
    "summary":null,
    "importance":"normal",
    "locale":"en-us",
    "policyViolation":null,
    "from": {
        "application":null,
        "device":null,
        "conversation":null,
        "user": {
            "id":"id-value",
            "displayName":"John Doe",
            "userIdentityType":"aadUser"
        }
    },
      "body": {
        "contentType":"html",
        "content":"<div><div>\n<div><span><img height=\"250\" src=\"https://graph.microsoft.com/teams/teamId/channels/channelId/messages/id-value/hostedContents/hostedContentId/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
    },
    "attachments":[],
    "mentions":[],
    "reactions":[]
}

Шаг 4. Завершение режима миграции

completeMigration Используйте API, чтобы завершить процесс миграции для новых и существующих каналов и чатов. Дополнительные сведения см. в разделе:

• Завершение миграции новой команды и канала
• Завершение миграции существующего канала или чата

Завершение миграции новой команды и канала

completeMigration Используйте API для завершения миграции новой команды и канала. Это действие открывает ресурсы команды и канала для общего использования участниками команды. Действие привязано к экземпляру team. Прежде чем завершить миграцию сообщений группы, необходимо выполнить миграцию на всех каналах.

Запрос (завершение режима миграции канала)

POST https://graph.microsoft.com/beta/teams/team-id/channels/channel-id/completeMigration

Отклик

HTTP/1.1 204 NoContent

Запрос (завершение режима миграции команды)

POST https://graph.microsoft.com/beta/teams/team-id/completeMigration

Отклик

HTTP/1.1 204 NoContent

Добавление участников команды

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

Вы также можете использовать Microsoft Graph для добавления одного элемента или массового добавления элементов.

Запрос (добавление участника)

POST https://graph.microsoft.com/beta/teams/{team-id}/members
Content-type:application/json
Content-length:30

{
   "@odata.type":"#microsoft.graph.aadUserConversationMember",
   "roles":[],
   "user@odata.bind":"https://graph.microsoft.com/beta/users/{user-id}"
}

Отклик

HTTP/1.1 204 No Content

После завершения новой команды и миграции канала проверьте завершение режима миграции.

Завершение миграции существующего канала или чата

Для существующих каналов или чатов, которые уже находятся в режиме миграции completeMigration , используйте API, чтобы пометить состояние миграции как завершенное. Этот процесс гарантирует, что канал или чат остаются постоянно доступными, а не удаляются после миграции.

Запрос (завершение миграции существующего канала)

POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/completeMigration
 

Отклик

HTTP/1.1 204 NoContent

Запрос (завершение миграции существующего чата)

POST https://graph.microsoft.com/beta/chats/{chat-id}/completeMigration 

Отклик

HTTP/1.1 204 NoContent

Необязательно. Обновление журнала участников группового чата после миграции

После завершения миграции сообщений в групповом чате можно при необходимости обновить журнал общих ресурсов участников с помощью visibleHistoryStartDateTime свойства в Microsoft Graph. Это свойство задает самое раннее время, когда участник чата сможет просматривать сообщения в беседе. Если импортированные сообщения старше значения свойства, они не отображаются, если вы не обновите свойство.

Чтобы обновить свойство, visibleHistoryStartDateTime выполните следующие действия:

1. Удалите участника из чата.
2. Добавьте участника обратно с новым visibleHistoryStartDateTime элементом, который включает импортированные сообщения.

Пример

Рассмотрим сценарий, в котором исходный чат был создан в 22:00, обновлен в 1:00, сообщения импортированы в 9:00, а история общих данных участника A начинается в 10:00. Чтобы убедиться, что член A может видеть импортированные сообщения в 9:00:

1. Удалите участника А из чата.
2. Добавьте элемент A со свойством, заданным visibleHistoryStartDateTime до 9:00.

Шаг 5. Проверка завершения режима миграции

Вызовите командлет Get channel или Get chat , чтобы убедиться, что migrationMode объект помечен как Completed.

Советы и дополнительные сведения

• После вызова completeMigration существующего канала или чата вы можете продолжить импорт сообщений с помощью startMigration API.

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

• Регулирование: сообщения импортируются на уровне пяти RPS на канал.

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

Пример кода

См. также

• Интеграция Microsoft Graph и Teams
• Экспорт контента с помощью API экспорта Microsoft Teams
• Ограничения службы Microsoft Teams
• Требования к лицензированию и оплате для Microsoft Teams API