Proaktive Installation von Apps über die Graph-API zum Senden von Nachrichten

Wichtig

Microsoft Graph und Microsoft Teams öffentliche Vorschauen stehen für frühzeitigen Zugriff und Feedback zur Verfügung. Obwohl diese Version umfangreichen Tests unterzogen wurde, ist sie nicht für die Verwendung in der Produktion vorgesehen.

Proaktives Messaging in Teams

Proaktive Nachrichten werden von Bots initiiert, um Unterhaltungen mit einem Benutzer zu starten. Sie dienen vielen Zwecken, darunter das Senden von Willkommensnachrichten, das Durchführen von Umfragen oder Umfragen und das Senden organisationsweiter Benachrichtigungen. Proaktive Nachrichten in Teams können als Ad-hoc- oder dialogbasierte Unterhaltungen übermittelt werden:

Nachrichtentyp Beschreibung
Proaktive Ad-hoc-Nachricht Der Bot übergibt eine Nachricht, ohne den Unterhaltungsfluss zu unterbrechen.
Dialogbasierte proaktive Nachricht Der Bot erstellt einen neuen Dialogthread, übernimmt die Kontrolle über eine Unterhaltung, übermittelt die proaktive Nachricht, schließt und gibt die Steuerung an das vorherige Dialogfeld zurück.

Proaktive App-Installation in Teams

Bevor Ihr Bot proaktiv eine Nachricht an einen Benutzer senden kann, muss er entweder als persönliche App oder in einem Team installiert werden, in dem der Benutzer Mitglied ist. Manchmal müssen Sie proaktive Nachrichten an Benutzer senden, die Ihre App nicht installiert oder zuvor mit Ihrer App interagiert haben. Beispielsweise müssen wichtige Informationen an alle Personen in Ihrer Organisation ausgegeben werden. Für solche Szenarien können Sie die Microsoft Graph-API verwenden, um Ihren Bot proaktiv für Ihre Benutzer zu installieren.

Berechtigungen

Microsoft Graph TeamsAppInstallation-Ressourcentypberechtigungen helfen Ihnen, den Installationslebenszyklus Ihrer App für alle Benutzer- (persönlichen) oder Teambereiche (Kanal) innerhalb der Microsoft Teams Plattform zu verwalten:

Anwendungsberechtigung Beschreibung
TeamsAppInstallation.ReadWriteSelfForUser.All Ermöglicht es einer Teams App, sich selbst ohne vorherige Anmeldung oder Verwendung für jeden Benutzer zu lesen, zu installieren, zu aktualisieren und zu deinstallieren.
TeamsAppInstallation.ReadWriteSelfForTeam.All Ermöglicht es einer Teams App, sich selbst in einem Beliebigen Team ohne vorherige Anmeldung oder Verwendung zu lesen, zu installieren, zu aktualisieren und zu deinstallieren.

Um diese Berechtigungen zu verwenden, müssen Sie Ihrem App-Manifest einen webApplicationInfo-Schlüssel mit den folgenden Werten hinzufügen:

  • id: Ihre Azure Active Directory -App-ID (AAD).
  • ressource: Die Ressourcen-URL für die App.

Hinweis

  • Ihr Bot erfordert Eine Anwendung und keine delegierten Benutzerberechtigungen, da die Installation für andere benutzerdelegiert ist.

  • Ein AAD Mandantenadministrator muss einer Anwendung explizit Berechtigungen erteilen. Nachdem der Anwendung Berechtigungen erteilt wurden, erhalten alle Mitglieder des AAD Mandanten die erteilten Berechtigungen.

Proaktive App-Installation und Messaging aktivieren

Wichtig

Microsoft Graph können nur Apps installieren, die im App Store Ihrer Organisation oder im Teams Store veröffentlicht wurden.

Erstellen und Veröffentlichen Ihres proaktiven Messaging-Bots für Teams

Um zu beginnen, benötigen Sie einen Bot für Teams mit proaktiven Messagingfunktionen, die sich im App Store Ihrer Organisation oder im Teams Store befinden.

Tipp

Die produktionsbereite Unternehmens-Communicator-App-Vorlage ermöglicht Broadcast-Messaging und ist ein guter Start für die Erstellung Ihrer proaktiven Bot-Anwendung.

Abrufen der teamsAppId Für Ihre App

Sie können die teamsAppId folgenden Methoden abrufen:

  • Aus dem App-Katalog Ihrer Organisation:

    Microsoft Graph-Seitenreferenz: teamsApp-Ressourcentyp

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
    

    Die Anforderung muss ein Objekt zurückgeben, bei dem es sich um teamsApp die vom id App-Katalog generierte App-ID handelt. Dies unterscheidet sich von der ID, die Sie in Ihrem Teams App-Manifest angegeben haben:

    {
      "value": [
        {
          "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
          "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
          "name": "Test App",
          "version": "1.0.1",
          "distributionMethod": "Organization"
        }
      ]
    }
    
  • Wenn Ihre App bereits für einen Benutzer im persönlichen Bereich hochgeladen oder quergeladen wurde:

    Microsoft Graph-Seitenverweis: Apps auflisten, die für den Benutzer installiert sind

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
    
  • Wenn Ihre App bereits für einen Kanal im Teambereich hochgeladen oder quergeladen wurde:

    Microsoft Graph-Seitenverweis: Apps im Team auflisten

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
    

    Tipp

    Um die Liste der Ergebnisse einzugrenzen, können Sie alle Felder des teamsApp-Objekts filtern.

Ermitteln, ob Ihr Bot derzeit für einen Nachrichtenempfänger installiert ist

Sie können wie folgt ermitteln, ob Ihr Bot derzeit für einen Nachrichtenempfänger installiert ist:

Microsoft Graph-Seitenverweis: Apps auflisten, die für den Benutzer installiert sind

HTTP GET-Anforderung:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

Die Anforderung gibt Folgendes zurück:

  • Ein leeres Array, wenn die App nicht installiert ist.
  • Ein Array mit einem einzelnen teamsAppInstallation-Objekt, wenn die App installiert ist.

Installieren Ihrer App

Sie können Ihre App wie folgt installieren:

Microsoft Graph-Seitenverweis: Installieren der App für den Benutzer

HTTP POST-Anforderung:

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

Wenn der Benutzer Microsoft Teams ausgeführt hat, erfolgt die App-Installation sofort. Möglicherweise ist ein Neustart erforderlich, um die installierte App anzuzeigen.

Abrufen der Unterhaltung chatId

Wenn Ihre App für den Benutzer installiert ist, erhält der Bot eine conversationUpdate Ereignisbenachrichtigung, die die erforderlichen Informationen zum Senden der proaktiven Nachricht enthält.

Microsoft Graph-Seitenverweis: Chat abrufen

  1. Sie müssen über die {teamsAppInstallationId} App verfügen. Wenn sie nicht vorhanden ist, verwenden Sie Folgendes:

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
    

    Die ID-Eigenschaft der Antwort ist die teamsAppInstallationId .

  2. Stellen Sie die folgende Anforderung, um die folgende Anforderung chatId abzurufen:

    HTTP GET-Anforderung (Berechtigung — TeamsAppInstallation.ReadWriteSelfForUser.All ):

    GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
    

    Die ID-Eigenschaft der Antwort ist die chatId .

    Sie können dies auch chatId mit der folgenden Anforderung abrufen, erfordert jedoch die umfassendere Chat.Read.All Berechtigung:

    HTTP GET-Anforderung (Berechtigung — Chat.Read.All ):

    GET https://graph.microsoft.com/beta/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
    

Senden proaktiver Nachrichten

Ihr Bot kann proaktive Nachrichten senden, nachdem der Bot für einen Benutzer oder ein Team hinzugefügt wurde und alle Benutzerinformationen erhalten hat.

Codebeispiel

Beispielname Beschreibung .NET Node.js
Proaktive Installation der App und Senden proaktiver Benachrichtigungen Dieses Beispiel zeigt, wie Sie die proaktive Installation von Apps für Benutzer verwenden und proaktive Benachrichtigungen senden können, indem Sie Microsoft Graph APIs aufrufen. View View

Zusätzliche Codebeispiele

Siehe auch