Proaktives Installieren Ihres Bots für Benutzer mit Microsoft Graph

Wenn Sie Nachrichten an Benutzer senden müssen, die Ihre App noch nicht installiert haben oder zuvor mit ihrer App interagiert haben, z. B. um wichtige Informationen an alle Benutzer in Ihrem organization zu übertragen, können Sie den Microsoft-Graph-API verwenden, um Ihren Bot für diese Benutzer proaktiv zu installieren. 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.

In diesem Artikel wird beschrieben, wie Sie Microsoft Graph verwenden, um die Installation status zu überprüfen und Ihren Bot programmgesteuert zu installieren. Informationen zum Abrufen der Konversations-ID und zum Senden einer 1:1-Nachricht an den Benutzer finden Sie nach der Installation unter Senden einer persönlichen Begrüßungsnachricht .

Berechtigungen

Microsoft Graph-Berechtigungen für den teamsAppInstallation-Ressourcentyp helfen Ihnen, den Installationslebenszyklus Ihrer App für alle Benutzerbereiche (persönlich) oder Teambereiche (Kanal) innerhalb der Microsoft Teams-Plattform zu verwalten:

Um diese Berechtigungen verwenden zu können, müssen Sie Ihrem App-Manifest (zuvor Teams-App-Manifest genannt) einen webApplicationInfo-Schlüssel mit den folgenden Werten hinzufügen:

• id: Ihre Microsoft Entra App-ID.
• resource: Die Ressourcen-URL für die App

Aktivieren der proaktiven Bot-Installation und des proaktiven Bot-Messagings

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

Um zu beginnen, benötigen Sie einen Bot für Teams mit proaktiven Messagingfunktionen, der sich im App Store Ihres organization oder im Teams Store befindet.

Abrufen der teamsAppId für Ihre App

Sie können die teamsAppId wie folgt 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 teamsApp-Objekt id zurückgeben, bei dem es sich um die vom App-Katalog generierte App-ID handelt. Dies unterscheidet sich von der ID, die Sie in Ihrem 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"
      }
    ]
  }
  

  Hinweis

  Wenn sich die App im Teams Store befindet, ist identisch teamsAppId mit IdFromManifest und externalId darf in diesem Fall nicht verwendet werden.

• Wenn Ihre App bereits für einen Benutzer im persönlichen Bereich hochgeladen wurde:

  Microsoft Graph-Seitenreferenz:Auflisten von Apps, die für 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 wurde:

  Microsoft Graph-Seitenreferenz: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 Ergebnisliste einzugrenzen, können Sie jedes der Felder des teamsApp-Objekts filtern.

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

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

Microsoft Graph-Seitenreferenz:Auflisten von Apps, die für 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-Seitenreferenz:App für Benutzer installieren

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 Microsoft Teams bei dem Benutzer gerade aktiv ist, erfolgt die App-Installation sofort. Möglicherweise ist ein Neustart erforderlich, damit die installierte App angezeigt wird.

Die nächsten Schritte finden Sie unter Senden einer persönlichen Begrüßungsnachricht , um zu erfahren, wie Sie die Konversations-ID abrufen und eine 1:1-Nachricht an den Benutzer senden.

Codebeispiel

Zusätzliche Codebeispiele

Siehe auch

• Verwalten von Richtlinien für App-Setup in Teams
• Proaktives Messaging mit teams SDK
• Senden von Aktivitätsfeedbenachrichtigungen an Benutzer in Microsoft Teams
• Hinzufügen einer App zum Team – Microsoft Graph v1.0
• Microsoft Teams-Diensteinschränkungen