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

  • Artikel

Mit Microsoft Graph können Sie den bestehenden Nachrichtenverlauf und die Daten von Benutzern aus einem externen System in einen Microsoft Teams-Kanal importieren. Durch die Möglichkeit, die Hierarchie von Nachrichten aus einer Drittanbieterplattform in Microsoft Teams zu übertragen, können Benutzer ihre Unterhaltungen nahtlos und ohne Unterbrechung fortsetzen.

Hinweis

Microsoft kann in Zukunft von Ihnen oder Ihren Kunden fordern, basierend auf der Menge der importierten Daten, zusätzliche Gebühren zu zahlen.

Übersicht über den Importprozess

Im Allgemeinen besteht der Importprozess aus den folgenden Schritten:

  1. Erstellen eines Teams mit einem Back-in-Time-Zeitstempel
  2. Erstellen eines Kanals mit einem Back-in-Time-Zeitstempel
  3. Importieren externer Nachrichten mit Back-in-Time-Datum
  4. Abschließen des Team- und Kanalmigrationsprozesses
  5. Hinzufügen von Teammitgliedern

Voraussetzungen

Analysieren und Vorbereiten von Nachrichtendaten

  • Überprüfen Sie die Drittanbieterdaten, um zu entscheiden, was übertragen werden soll.
  • Extrahieren Sie die ausgewählten Daten aus dem Drittanbieter-Chatsystem.
  • Ordnen Sie die Drittanbieter-Chatstruktur der Microsoft Teams-Struktur zu.
  • Konvertieren Sie die zu importierenden Daten in das für die Übertragung erforderliche Format.

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 teammitglieder sich in Microsoft Entra-ID befinden. Weitere Informationen finden Sie unter Hinzufügen eines neuen Benutzers zu Microsoft Entra ID.

Schritt 1: Erstellen eines Teams

Da Sie bestehende Daten migrieren, sind die Erhaltung der ursprünglichen Nachrichtenzeitstempel und das Verhindern von Nachrichtenaktivitäten während des Migrationsprozesses entscheidend, um den bestehenden Nachrichtenablauf des Benutzers in Microsoft Teams neu zu erstellen. Dies wird wie folgt erreicht:

Erstellen Sie ein neues Team mit einem Back-in-Time-Zeitstempel mithilfe der Teamressourceneigenschaft createdDateTime. Versetzen Sie das neue Team in den Modus migration mode, einem besonderen Zustand, der die meisten Benutzeraktivitäten innerhalb des Teams bis zum Abschluss des Migrationsprozesses einschränkt. Schließen Sie das teamCreationMode-Instanzattribut mit dem Wert migration in die POST-Anforderung ein, um das neue Team explizit als für die Migration erstellt zu identifizieren.

Hinweis

Das createdDateTime-Feld wird nur für Instanzen eines Teams oder Kanals befüllt, die migriert wurden.

Berechtigung

ScopeName DisplayName Beschreibung Typ Administratorzustimmung? Abgedeckte Entitäten/APIs
Teamwork.Migrate.All Migration zu Microsoft Teams verwalten Erstellen und Verwalten von Ressourcen für die Migration zu Teams. Nur Anwendung Ja POST /teams

Anforderung (Team im Migrationsstatus erstellen)

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.

Schritt 2: Erstellen eines Kanals

Das Erstellen eines Kanals für die zu importierenden Nachrichten ähnelt dem Vorgang zum Erstellen eines Teams:

Erstellen Sie einen neuen Kanal mit einem Back-in-Time-Zeitstempel mithilfe der Kanalressourceneigenschaft createdDateTime. Versetzen Sie den neuen Kanal in den Modus migration mode, einem besonderen Zustand, der die meisten Chataktivitäten innerhalb des Kanals bis zum Abschluss des Migrationsprozesses einschränkt. Schließen Sie das channelCreationMode-Instanzattribut mit dem Wert migration in die POST-Anforderung ein, um den neuen Kanal explizit als für die Migration erstellt zu identifizieren.

Berechtigung

ScopeName DisplayName Beschreibung Typ Administratorzustimmung? Abgedeckte Entitäten/APIs
Teamwork.Migrate.All Migration zu Microsoft Teams verwalten Erstellen und Verwalten von Ressourcen für die Migration zu Teams. Nur Anwendung Ja POST /teams

Anforderung (Kanal im Migrationsstatus erstellen)

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.

Schritt 3: Importieren von Nachrichten

Nachdem das Team und der Kanal erstellt wurden, können Sie mit dem Senden von Back-in-Time-Nachrichten beginnen, indem Sie die createdDateTime Schlüssel und from im Anforderungstext verwenden.

Hinweis

  • Nachrichten mit einem createdDateTime-Datum, das vor dem createdDateTime-Datum des Nachrichtenthreads liegt, werden nicht unterstützt.
  • createdDateTime muss für alle Nachrichten im selben Thread eindeutig sein.
  • createdDateTime unterstützt Zeitstempel mit einer Präzision im Millisekundenbereich. Wenn die eingehende Anforderungsnachricht beispielsweise für als Wert von createdDateTime2020-09-16T05:50:31.0025302Z aufweist, wird dies in 2020-09-16T05:50:31.002Z konvertiert, wenn die Nachricht erfasst wird.

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":"Joh 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

400 Bad Request

Anforderung (POST einer Nachricht mit Inlinebild)

Hinweis

  • In diesem Szenario gibt es keine speziellen Berechtigungsbereiche, da die Anforderung Teil von chatMessage ist.
  • Die Bereiche für chatMessage gelten hier.
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": "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": []
}

Schritt 4: Beenden des Migrationsmodus

Nach Abschluss des Nachrichtenmigrationsprozesses werden sowohl das Team als auch der Kanal mithilfe der -Methode aus dem completeMigration Migrationsmodus genommen. In diesem Schritt werden die Team- und Kanalressourcen für die allgemeine Verwendung durch Teammitglieder freigegeben. Die Aktion ist an die team-Instanz gebunden. Bevor das Team abgeschlossen wird, müssen alle Kanäle außerhalb des Migrationsmodus abgeschlossen sein.

Anforderung (Kanalmigrationsmodus beenden)

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

Antwort

HTTP/1.1 204 NoContent

Anforderung (Teammigrationsmodus beenden)

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

Antwort

HTTP/1.1 204 NoContent

Aktion, die für ein team oder einen channel aufgerufen wird, die nicht im migrationMode sind.

Schritt 5: Hinzufügen von Teammitgliedern

Sie können einem Team ein Mitglied über die Microsoft Teams-Benutzeroberfläche oder mithilfe der Microsoft Graph-API zum Hinzufügen von Mitgliedern hinzufü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

Tipps und zusätzliche Informationen

  • Nachdem die completeMigration-Anforderung gestellt wurde, können Sie keine weiteren Nachrichten in das Team importieren.

  • Sie können dem neuen Team erst Teammitglieder hinzufügen, nachdem die completeMigration-Anforderung eine positive Antwort zurückgegeben hat.

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

  • Wenn Sie eine Korrektur an den Migrationsergebnissen vornehmen müssen, müssen Sie das Team löschen, die Schritte zum Erstellen des Teams und kanals wiederholen und die Nachrichten erneut migrieren.

Hinweis

Derzeit sind Inlinebilder der einzige Medientyp, der vom API-Schema für das Importieren von Nachrichten unterstützt wird.

Importierbare Inhalte

Die nachstehende Tabelle enthält die importierbaren Inhalte:

Importierbar Derzeit nicht importierbar
Team- und Kanalnachrichten 1:1- und Gruppenchatnachrichten
Erstellungszeit der ursprünglichen Nachricht Private Kanäle
Inlinebilder als Teil der Nachricht @-Erwähnungen
Links zu vorhandenen Dateien in SPO oder OneDrive Reaktionen
Nachrichten mit Rich-Text Videos
Nachrichtenantwortkette Ankündigungen
Verarbeitung mit hohem Durchsatz Codeausschnitte
Sticker
Emojis
Zitate
Crossposts zwischen Kanälen
Freigegebene Kanäle

Siehe auch