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

Статья
04/04/2023

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

Примечание.

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

Обзор импорта

На общем уровне процесс импорта состоит из следующих действий.

Создание команды с меткой времени в прошлом.
Создание канала с меткой времени в прошлом.
Импорт внешних сообщений с датой в прошлом.
Завершение процесса миграции команды и канала.
Добавление участников команды.

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

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

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

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

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

Шаг 1. Создание команды

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

Создайте команду с меткой времени в прошлом, используя свойство createdDateTime ресурса команды. Поместите новую команду в migration mode — специальное состояние, которое запрещает пользователям большинство действий в команде до завершения процесса миграции. Включите атрибут экземпляра teamCreationMode со значением migration в запрос POST, чтобы явно идентифицировать новую команду как созданную для миграции.

Примечание.

Поле createdDateTime будет заполнено только для экземпляров команды или канала, которые были перенесены.

Разрешение

ScopeName	DisplayName	Описание	Тип	Согласие администратора?	Охваченные объекты/API
`Teamwork.Migrate.All`	Управление миграцией в Microsoft Teams	Создание ресурсов для миграции в Teams и управление ими.	Только для приложений	Да	`POST /teams`

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

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 или ему присвоено недопустимое значение.

Шаг 2. Создание канала

Создание канала для импортированных сообщений аналогично сценарию создания команды:

Создайте канал с меткой времени в прошлом, используя свойство createdDateTime ресурса канала. Поместите новый канал в migration mode — специальное состояние, которое запрещает пользователям большинство действий чата в канале до завершения процесса миграции. Включите атрибут экземпляра channelCreationMode со значением migration в запрос POST, чтобы явно идентифицировать новую команду как созданную для миграции.

Разрешение

ScopeName	DisplayName	Описание	Тип	Согласие администратора?	Охваченные объекты/API
`Teamwork.Migrate.All`	Управление миграцией в Microsoft Teams	Создание ресурсов для миграции в Teams и управление ими.	Только для приложений	Да	`POST /teams`

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

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 или ему присвоено недопустимое значение.

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

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

Примечание.

Сообщения, импортированные с параметром createdDateTime, значение которого предшествует значению createdDateTime цепочки сообщений, не поддерживаются.
Параметр createdDateTime должен быть уникальным для сообщений в одной цепочке.
Параметр createdDateTime поддерживает метки времени с точностью в миллисекундах. Например, если входящее сообщение запроса содержит параметр createdDateTime со значением 2020-09-16T05:50:31.0025302Z, оно будет преобразовано в 2020-09-16T05:50:31.002Z при приеме сообщения.

Запрос (команда 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":"Joh 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":[
   ]
}

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

400 Bad Request

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

Примечание.

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

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": "Joh 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 метода . Этот шаг открывает ресурсы команды и канала для общего использования участниками команды. Действие привязано к экземпляру team. Прежде чем команда завершит работу, все каналы должны быть выведены из режима миграции.

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

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

Отклик

HTTP/1.1 204 NoContent

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

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

Отклик

HTTP/1.1 204 NoContent

Действие вызывается для team или channel, отсутствующих в migrationMode.

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

Вы можете добавить участника в команду с помощью пользовательского интерфейса Teams или API добавления участника 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 вы не сможете импортировать дальнейшие сообщения в команду.
Вы можете добавлять участников команды в новую команду только после того, как запрос completeMigration возвратит успешный отклик.
Регулирование: сообщения импортируются на уровне пяти RPS на канал.
Если необходимо внести исправление в результаты миграции, необходимо удалить команду, повторить шаги по созданию команды и каналу и повторно перенести сообщения.

Примечание.

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

Импорт области содержимого

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

В области	В настоящее время вне области
Сообщения команды и канала	Сообщения индивидуального и группового чата
Время создания исходного сообщения	Закрытые каналы
Встроенные изображения как часть сообщения	Упоминания
Ссылки на существующие файлы в SPO или OneDrive	Реакции
Сообщения с форматированным текстом	Видео
Цепочка ответов на сообщение	Объявления
Обработка с высокой пропускной способностью	Фрагменты кода
	Наклейки
	Эмодзи
	Цитаты
	Перекрестные публикации между каналами
	Общие каналы

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

Обзор импорта

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

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

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

Шаг 1. Создание команды

Разрешение

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

Отклик

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

Шаг 2. Создание канала

Разрешение

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

Отклик

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

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

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

Отклик

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

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

Отклик

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

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

Отклик

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

Отклик

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

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

Отклик

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

Импорт области содержимого

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы