Plattform-Nachrichten von Drittanbietern mithilfe von Microsoft Graph in Teams importieren

Mit Microsoft Graph können Sie den vorhandenen Nachrichtenverlauf und die Daten von Benutzern aus einem externen System zu Teams migrieren. Benutzer können ihre Kommunikation nahtlos fortsetzen und ohne Unterbrechung fortfahren, indem sie die Wiederherstellung einer Plattform-Messaginghierarchie von Drittanbietern in Teams ermöglichen.

Berechtigungen

Unterstützte Kanal- und Chattypen

Teams unterstützt die Migration externer Nachrichten zu den folgenden Kanal- und Chattypen:

• Neuer Team- und Standardkanal: Erstellen Sie ein neues Team und seine Standardkanäle im Migrationsmodus, um Inhalte zu importieren. Mit diesem Ansatz können Sie die genaue Struktur Ihres externen Systems in den neuen Kanal importieren. Informationen zum Aktivieren migrationMode für ein neues Standardteam und einen neuen Standardkanal finden Sie unter Erstellen eines Teams und eines Standardkanals im Migrationsmodus.

• Vorhandener Kanal oder Chat: Verwenden Sie alle Kanäle oder Chats, die bereits in Teams vorhanden sind, unabhängig davon, wann Sie ihn erstellt haben. Mit diesem Ansatz können Sie vorhandenen Kontext zu Kanälen hinzufügen, die bereits in Teams aktiv sind, und die Kontinuität für laufende Unterhaltungen erhalten. Informationen zum Aktivieren des Migrationsmodus in einem vorhandenen Kanal oder Chat finden Sie unter Vorhandene Kanalmigration.

migrationMode ist ein spezieller Zustand, der die Datenintegrität sicherstellt, indem die folgenden Vorgänge während der Datenmigration verhindert werden.

• Für neue Teams und Standardkanäle:
  • Es schränkt den Empfang neuer Nachrichten ein.
  • Es verhindert das Hinzufügen oder Entfernen von Elementen.
• Für alle unterstützten Kanäle und Chattypen:
  • Es ermöglicht das Importieren von Verlaufsmeldungen mit benutzerdefinierten Zeitstempeln.
  • Die ursprüngliche Konversationsstruktur und -hierarchie wird beibehalten.

Inhaltsbereich für den Import

Die folgende Tabelle enthält den Inhaltsbereich für vorhandene Kanäle und Chats.

Voraussetzungen

Analysieren und Vorbereiten von Nachrichtendaten

• Überprüfen Sie die Drittanbieterdaten, um zu entscheiden, was migriert werden soll.
• Extrahieren Sie die ausgewählten Daten aus dem Drittanbieter-Chatsystem.
• Ordnen Sie die Drittanbieter-Chatstruktur der Microsoft Teams-Struktur zu.
• Konvertieren Sie Importdaten in das format, das für die Migration erforderlich ist.

Richten Sie Ihren Microsoft 365-Mandanten ein.

• Stellen Sie sicher, dass ein Microsoft 365-Mandant für die Importdaten vorhanden ist. Weitere Informationen zum Einrichten eines Microsoft 365-Mandanten für Teams finden Sie unter Vorbereiten Ihres Microsoft 365-Mandanten.
• Stellen Sie sicher, dass sich die Teammitglieder in Microsoft Entra ID befinden. Weitere Informationen finden Sie unter Hinzufügen eines neuen Benutzers zu Microsoft Entra ID.

Importieren von verlaufsbezogenen Nachrichten in Teams

Sie können verlaufsbezogene Nachrichten nahtlos in vorhandene und neu erstellte Kanäle oder Chats importieren, indem Sie die folgenden Schritte ausführen:

1. Starten der Migration
2. Überprüfen der status für die Migration
3. Importieren von Nachrichten
4. Vollständiger Migrationsmodus
5. Überprüfen des Abschlusses des Migrationsmodus

Schritt 1: Starten der Migration

Um mit der Migration des Nachrichtenverlaufs eines Benutzers von einer Beliebigen Drittanbieterplattform zu Teams zu beginnen, können Sie entweder ein neues Team und einen Standardkanal erstellen oder einen vorhandenen Kanal oder Chat verwenden. Wählen Sie je nach Szenario eine der folgenden Optionen aus:

• Erstellen eines Teams und eines Standardkanals im Migrationsmodus
• Starten der Migration in vorhandenen Kanälen und Chats

Erstellen eines Teams und eines Standardkanals im Migrationsmodus

Erstellen Sie in diesem Szenario ein neues Team und einen Standardkanal in migrationMode , um mit dem Importieren vorhandener Nachrichten fortzufahren. migrationMode wird nur für Standardkanäle unterstützt.

Erstellen eines neuen Teams

• Erstellen Sie mithilfe der -Eigenschaft ein neues Team mit einem Back-in-Time-Zeitstempel createdDateTime .
• Platzieren Sie das neue Team inmigrationMode, indem Sie auf migrationfestlegenteamCreationMode.

Anforderung (Erstellen eines Teams im Migrationsmodus)

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

Antwort

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

Fehlermeldung

400 Bad Request

Sie können diese Fehlermeldung in den folgenden Szenarien erhalten:

• Wenn createdDateTime auf ein Datum in der Zukunft festgelegt ist.
• Wenn createdDateTime ordnungsgemäß angegeben wurde, aber das teamCreationMode-Instanzattribut fehlt oder auf einen ungültigen Wert festgelegt wurde.

Erstellen eines neuen Kanals

• Erstellen Sie mithilfe der createdDateTime -Eigenschaft der Kanalressource einen neuen Kanal mit einem Back-in-Time-Zeitstempel.
• Versetzen Sie den neuen Kanal in den Migrationsmodus, indem Sie auf migrationfestlegenchannelCreationMode.

Anforderung (Erstellen eines Kanals im Migrationsmodus)

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

Antwort

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
}

Fehlermeldung

400 Bad Request

Sie können diese Fehlermeldung in den folgenden Szenarien erhalten:

• Wenn createdDateTime auf ein Datum in der Zukunft festgelegt ist.
• Wenn createdDateTime ordnungsgemäß angegeben wurde, aber das channelCreationMode-Instanzattribut fehlt oder auf einen ungültigen Wert festgelegt wurde.

Nachdem Sie ein neues Team und einen neuen Standardkanal erstellt haben, schließen Sie die Migration mit den folgenden Schritten ab:

1. Überprüfen der status für die Migration
2. Importieren von Nachrichten
3. Vollständiger Migrationsmodus
4. Überprüfen des Abschlusses des Migrationsmodus

Starten der Migration in vorhandenen Kanälen und Chats

Verwenden Sie in vorhandenen Kanälen oder Chats die API, um den startMigrationKanalmigrationsmodus zu aktivieren , oder um den ChatmigrationsmodusstartMigration zu aktivieren, legt den Migrationsstatus auf fest InProgress und startet den Nachrichtenimportprozess. Weitere Informationen finden Sie unter:

• Vorhandene Kanalmigration
• Vorhandene Chatmigration

Vorhandene Kanalmigration

Verwenden Sie die API, um den startMigration Migrationsmodus für vorhandene Kanäle zu aktivieren.

Anforderung (vorhandener Kanal im Migrationsmodus)

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

Antwort

Wenn die Anforderung erfolgreich ist, gibt die Methode eine leere HTTP-Antwort zurück.

HTTP/1.1 204 No Content

Beispiel

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

Vorhandene Chatmigration

Verwenden Sie die API, um den startMigration Migrationsmodus für vorhandene Chats zu aktivieren.

Anforderung (vorhandener Chat im Migrationsmodus)

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

Antwort

Wenn die Anforderung erfolgreich ist, gibt die Methode eine leere HTTP-Antwort zurück.

HTTP/1.1 204 No Content

Beispiel

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

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

Beachten Sie die folgenden wichtigen Punkte:

• Definieren Sie einen Mindestzeitstempel für zu migrierende Nachrichten. Der bereitgestellte Zeitstempel muss älter als der aktuelle createdDateTimedes Kanals oder Chats sein. Dieser Zeitstempel ersetzt den vorhandenen createdDateTime des Kanals. Wenn Sie auf einen vergangenen Zeitstempel aktualisieren createdDateTime , können Sie ihn nicht erneut in einen zukünftigen Zeitstempel verschieben.
• Die creationDateTime -Eigenschaft ist in einem Anforderungstext optional. Wenn keine Angabe erfolgt, verwendet die startMigration API das aktuelle Datum und die aktuelle Uhrzeit als Minimalzeitstempel.
• Die startMigration API startet den Nachrichtenmigrationsprozess, indem der Migrationsmodus für einen angegebenen Kanal oder Chat auf InProgress festgelegt wird.

Schritt 2: Überprüfen der status für die Migration

Rufen Sie Get channel oder Get chat auf, um zu bestätigen, dass der migrationMode Zustand auf InProgressfestgelegt ist. Weitere Informationen finden Sie unter:

• Get channel
• Chat abrufen

Schritt 3: Importieren von Nachrichten

Jetzt können Sie Back-in-Time-Nachrichten importieren, indem Sie die createdDateTime Schlüssel und from in den Anforderungstext einfügen.

Anforderung (POST einer Nur-Text-Nachricht)

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

Antwort

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

Fehlermeldung

Sie erhalten die folgende Fehlermeldung, wenn Sie die createdDateTime Eigenschaft auf ein zukünftiges Datum und eine zukünftige Uhrzeit festlegen.

400 Bad Request

Anforderung (POST-Nachricht mit einem Inlinebild)

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

Antwort

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

Schritt 4: Beenden des Migrationsmodus

Verwenden Sie die completeMigration API, um den Migrationsprozess für neue und vorhandene Kanäle und Chats abzuschließen. Weitere Informationen finden Sie unter:

• Abschließen der Migration neuer Teams und Kanäle
• Abschließen der vorhandenen Kanal- oder Chatmigration

Abschließen der Migration neuer Teams und Kanäle

Verwenden Sie die API, um die completeMigrationMigration für das neue Team und den neuen Kanal abzuschließen . Diese Aktion öffnet die Team- und Kanalressourcen für die allgemeine Verwendung durch Teammitglieder. Die Aktion ist an die team-Instanz gebunden. Bevor Sie die Migration von Teamnachrichten abschließen, müssen Sie die Migration auf allen Kanälen abschließen.

Anforderung (Kanalmigrationsmodus beenden)

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

Antwort

HTTP/1.1 204 NoContent

Anforderung (Teammigrationsmodus beenden)

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

Antwort

HTTP/1.1 204 NoContent

Hinzufügen von Teammitgliedern

Nach Abschluss der Migration externer Nachrichten können Sie ein einzelnes Mitglied zu einem Team hinzufügen, indem Sie die Teams-Benutzeroberfläche verwenden. Sie können auch Microsoft Graph verwenden, um einzelne Mitglieder hinzuzufügen oder Mitglieder in einem Massenvorgang hinzuzufügen.

Anforderung (Mitglied hinzufügen)

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

Antwort

HTTP/1.1 204 No Content

Nachdem Sie die Migration eines neuen Teams und Kanals abgeschlossen haben, überprüfen Sie den Abschluss des Migrationsmodus.

Abschließen der vorhandenen Kanal- oder Chatmigration

Verwenden Sie für vorhandene Kanäle oder Chats, die sich bereits im Migrationsmodus befinden, die completeMigration API, um den Migrationsstatus als abgeschlossen zu kennzeichnen. Dadurch wird sichergestellt, dass der Kanal oder Chat dauerhaft verfügbar bleibt, anstatt nach der Migration gelöscht zu werden.

Anforderung (vorhandene Kanalmigration abschließen)

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

Antwort

HTTP/1.1 204 NoContent

Anforderung (vorhandene Chatmigration abschließen)

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

Antwort

HTTP/1.1 204 NoContent

Optional: Aktualisieren des Verlaufs von Gruppenchatmitglieden nach der Migration

Wenn Sie die Nachrichtenmigration in einem Gruppenchat abschließen, können Sie optional den Freigabeverlauf der Mitglieder mithilfe der visibleHistoryStartDateTime -Eigenschaft in Microsoft Graph aktualisieren. Diese Eigenschaft legt fest, zu wie früh ein Chatmitglied Nachrichten in einer Unterhaltung anzeigen kann. Wenn importierte Nachrichten älter als der Wert der Eigenschaft sind, werden sie nur angezeigt, wenn Sie die Eigenschaft aktualisieren.

So aktualisieren Sie die visibleHistoryStartDateTime Eigenschaft:

1. Entfernen Sie das Mitglied aus dem Chat.
2. Fügen Sie das Mitglied mit einer neuen visibleHistoryStartDateTime hinzu, die die importierten Nachrichten enthält.

Beispiel

Stellen Sie sich ein Szenario vor, in dem der ursprüngliche Chat um 22:00 Uhr erstellt wurde, um 1:00 Uhr aktualisiert wurde, Nachrichten um 9:00 Uhr importiert wurden und der Freigabeverlauf von Mitglied A um 10:00 Uhr beginnt. So stellen Sie sicher, dass Mitglied A die um 9 Uhr importierten Nachrichten sehen kann:

1. Entfernen Sie Mitglied A aus dem Chat.
2. Fügen Sie Mitglied A hinzu, wobei die visibleHistoryStartDateTime Eigenschaft vor 9:00 Uhr festgelegt ist.

Schritt 5: Überprüfen des Abschlusses des Migrationsmodus

Rufen Sie get channel (Kanal abrufen ) oder Get chat (Chat abrufen ) auf, um zu überprüfen, ob als migrationModeCompletedmarkiert ist.

Tipps und zusätzliche Informationen

• Nachdem Sie in einem vorhandenen Kanal oder Chat aufgerufen completeMigration haben, können Sie den Import von Nachrichten mithilfe der startMigration API fortsetzen.

• Sie können Teammitglieder nur zu den neuen Teams hinzufügen, nachdem die completeMigration Anforderung eine erfolgreiche Antwort zurückgegeben hat. Diese Regel gilt nur für das neu erstellte Team und den Standardkanal.

• Drosselung: Nachrichten werden mit fünf RPS pro Kanal importiert.

• Wenn Sie die Migrationsergebnisse korrigieren müssen, müssen Sie die Teams löschen, die Schritte zum Erstellen der Teams und des Kanals wiederholen und die Nachrichten erneut migrieren.

Codebeispiel

Siehe auch

• Integration von Microsoft Graph und Microsoft Teams
• Exportieren von Inhalten mit den Microsoft Teams Export-APIs
• Microsoft Teams-Diensteinschränkungen
• Lizenzierungs- und Zahlungsanforderungen für die Microsoft Teams-API