Importar mensagens de plataforma de terceiros para o Teams usando o Microsoft Graph

Com o Microsoft Graph, pode migrar os dados e o histórico de mensagens existentes dos utilizadores de um sistema externo para o Teams. Os utilizadores podem continuar as comunicações de forma totalmente integrada e continuar sem interrupções ao permitir a recriação de uma hierarquia de mensagens de plataforma de terceiros no Teams.

Permissões

Canais e tipos de chat suportados

O Teams suporta a migração de mensagens externas para canais ou chats existentes. Utilize qualquer canal ou chat que já exista no Teams, independentemente de quando o criou. Esta abordagem permite-lhe adicionar contexto existente a canais que já estão ativos no Teams e mantém a continuidade das conversações em curso. Para ativar o modo de migração num canal ou chat existente, consulte Migração de canal existente.

migrationMode é um estado especial que garante a integridade dos dados ao impedir determinadas operações durante a migração de dados.

• Para todos os canais e tipos de chat suportados:
  • Permite importar mensagens históricas com carimbos de data/hora personalizados
  • Mantém a estrutura e hierarquia de conversação originais

Âmbito do conteúdo para importação

A tabela seguinte fornece o âmbito de conteúdo para canais e chats existentes.

Pré-requisitos

Analisar e preparar dados de mensagem

• Reveja os dados de terceiros para decidir o que migrar.
• Extraia os dados selecionados do sistema de chat de terceiros.
• Mapeie a estrutura de chat de terceiros para a estrutura do Teams.
• Converta os dados de importação no formato necessário para a migração.

Configure o locatário do Microsoft 365.

• Certifique-se de que existe um inquilino do Microsoft 365 para os dados de importação. Para obter mais informações sobre como configurar um inquilino do Microsoft 365 para o Teams, consulte Preparar o seu inquilino do Microsoft 365.
• Certifique-se de que os membros da equipa estão no Microsoft Entra ID. Para obter mais informações, veja Adicionar um novo utilizador ao Microsoft Entra ID.

Importar mensagens históricas para o Teams

Pode importar mensagens históricas de forma totalmente integrada para canais ou chats existentes ao efetuar os seguintes passos:

1. Iniciar migração
2. Verificar status de migração
3. Importar mensagens
4. Modo de migração completo
5. Verificar a conclusão do modo de migração

Passo 1: Iniciar a migração

Para começar a migrar o histórico de mensagens de um utilizador de qualquer plataforma de terceiros para o Teams, pode utilizar um canal ou chat existente.

Iniciar a migração em canais e chats existentes

Em canais ou chats existentes, utilize a API para ativar o startMigrationmodo de migração de canais ou para ativar o modostartMigration de migração de chat define o estado de migração como InProgress e inicia o processo de importação de mensagens. Para saber mais, confira:

• Migração de canal existente
• Migração de chat existente

Migração de canal existente

Para ativar o modo de migração em canais existentes, utilize a startMigration API.

Pedido (canal existente no modo de migração)

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

Resposta

Se o pedido for bem-sucedido, o método devolve uma resposta HTTP vazia.

HTTP/1.1 204 No Content

Exemplo

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

Migração de chat existente

Para ativar o modo de migração em chats existentes, utilize a startMigration API.

Pedido (chat existente no modo de migração)

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

Resposta

Se o pedido for bem-sucedido, o método devolve uma resposta HTTP vazia.

HTTP/1.1 204 No Content

Exemplo

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

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

Considere os seguintes pontos importantes:

• Defina um carimbo de data/hora mínimo para as mensagens migrarem. O carimbo de data/hora fornecido tem de ser mais antigo do que o canal ou o chat atual createdDateTime. Este carimbo de data/hora substitui o existente createdDateTime do canal. Se atualizar createdDateTime para um carimbo de data/hora anterior, não poderá movê-lo novamente para um carimbo de data/hora futuro.
• A creationDateTime propriedade é opcional num corpo do pedido. Se for omitida, a startMigration API utiliza a data e hora atuais como o carimbo de data/hora mínimo.
• A startMigration API inicia o processo de migração de mensagens ao definir o modo InProgress de migração para um canal ou chat especificado.

Passo 2: Verificar status de migração

Chame Get channel ou Get chat para confirmar que o migrationMode estado está definido como InProgress. Para saber mais, confira:

• Get channel
• Obter bate-papo

Também pode verificar se o chat ou canal de destino está no migrationMode estado no Teams através de uma faixa que indica que a Migração para esta conversação está em curso. As mensagens podem estar fora de ordem durante este período de tempo.
Esta faixa permanecerá visível na IU do Teams até que a migração seja concluída para o chat ou canal de destino.

Etapa 3: Importar mensagens

Agora, pode importar mensagens de back-in-time ao incluir as createdDateTime chaves e from no corpo do pedido.

Solicitação (mensagem POST que é somente texto)

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"
   }
}

Resposta

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":[
   ]
}

Mensagem de erro

Receberá a seguinte mensagem de erro se definir a createdDateTime propriedade para uma data e hora futuras.

400 Bad Request

Pedido (mensagem POST com uma imagem inline)

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"
        }
    ]
}

Resposta

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":[]
}

Etapa 4: concluir o modo de migração

Para canais ou chats existentes já no modo de migração, utilize a completeMigration API para marcar o estado de migração como concluído. Este processo garante que o canal ou o chat permanece permanentemente disponível em vez de ser removido após a migração.

Pedido (concluir migração de canal existente)

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

Resposta

HTTP/1.1 204 NoContent

Pedido (concluir migração de chat existente)

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

Resposta

HTTP/1.1 204 NoContent

Opcional: Atualizar o histórico de membros do chat do grupo após a migração

Quando concluir a migração de mensagens numa conversa de grupo, pode atualizar opcionalmente o histórico de partilhas dos membros com a visibleHistoryStartDateTime propriedade no Microsoft Graph. Esta propriedade define a hora mais antiga em que um membro do chat pode ver mensagens numa conversação. Se as mensagens importadas forem mais antigas do que o valor da propriedade, não serão apresentadas a menos que atualize a propriedade.

Para atualizar a visibleHistoryStartDateTime propriedade:

1. Remova o membro da conversa.
2. Adicione o membro novamente com uma nova visibleHistoryStartDateTime que inclua as mensagens importadas.

Exemplo

Considere um cenário em que o chat original foi criado às 22:00, atualizado às 13:00, as mensagens eram importadas às 9:00 e o histórico de partilhas do membro A começa às 10:00. Para garantir que o membro A consegue ver as mensagens importadas das 9:00:

1. Remova o membro A da conversa.
2. Adicione o membro A com a visibleHistoryStartDateTime propriedade definida antes das 9:00.

Passo 5: Verificar a conclusão do modo de migração

Chame Obter canal ou Obter chat para verificar se o migrationMode está marcado como Completed.

Dicas e informações adicionais

• Depois de chamar completeMigration num canal ou chat existente, pode continuar a importar mensagens com a startMigration API.

• Limitação: as mensagens são importadas em cinco RPS por canal.

• Se precisar de corrigir os resultados da migração, tem de eliminar o Teams, repetir os passos para criar o Teams e o canal e voltar a migrar as mensagens.

Exemplo de código

Confira também

• Integração do Microsoft Graph com o Teams
• Exportar conteúdo com a API do Microsoft Teams Export
• Limites do serviço do Microsoft Teams
• Requisitos de licenciamento e pagamento para a API do Microsoft Teams