Teilen über


Interaktiver Benachrichtigungsbot in Teams

Mit dem Microsoft Teams-Toolkit können Sie Anwendungen erstellen, die Ereignisse erfassen und als interaktive Benachrichtigungen an einen persönlichen Chat, einen Gruppenchat oder einen Kanal in Microsoft Teams senden. Sie können Benachrichtigungen als Nur-Text oder adaptive Karten senden. Die Vorlage für den Benachrichtigungsbot erstellt eine App, die eine Nachricht an Teams mit adaptiven Karten sendet, die von der HTTP-Post-Anforderung ausgelöst werden.

Die App-Vorlage wird mit dem TeamsFx SDK erstellt, das einen einfachen Satz von Funktionen über Microsoft Bot Framework bereitstellt, um Ihre Anforderungen zu implementieren. Beispielsweise erstellt ein Reisebüro eine App in Teams für seine Benutzer, um sie mit der Wettervorhersage auf dem neuesten Stand zu halten. Im folgenden Flussdiagramm benachrichtigt eine Teams-App die Benutzer mit einer adaptiven Karte über die Wettervorhersage:

Beispiel für Benachrichtigungsszenario für wettervorhersage

Sie können eine Botbenachrichtigung in den folgenden Szenarien senden:

  • Sie möchten alle Personen in einem Kanal oder Chat über den gleichen oder verwandten Inhalt benachrichtigen.

  • Hochgradig anpassbare Benutzeroberfläche in einer Karte

  • Schnelle Reaktion, Medieninhalte oder Aktionsschaltflächen erforderlich.

  • Senden geplanter Benachrichtigungen

  • Aktivieren sie doppelte Badges für Aktivität und Chat, Kanal oder App

  • Fügen Sie eine Vorlage im Quellcode hinzu.

  • Manuelles Verarbeiten der Lokalisierung.

Vorteile

  • Ermöglicht Benachrichtigungen für einen persönlichen Gruppenchat und in einem Kanal mithilfe von APIs aus dem TeamsFx SDK.

  • Verbessert die Benutzererfahrung, indem Benachrichtigungen mit einer adaptiven Karte angepasst werden.

  • Stellt mehrere Mechanismen zum Auslösen von Benachrichtigungen bereit, z. B. HTTP und Planen von Timertriggern mit Azure Functions.

  • Eine Benachrichtigungskarte lässt sich problemlos in einen Bot integrieren und bietet eine konsistente Benutzererfahrung innerhalb der Bot-App.

Hinweis

Die Botanwendung muss mit dem entsprechenden Bereich installiert werden, bevor eine Benachrichtigung gesendet wird.

Zurück zum Anfang

Benachrichtigung basierend auf Ereignissen

Bot Framework SDK bietet die Funktionalität für proaktive Nachrichten in Teams. Das TeamsFx SDK bietet die Funktionalität zum Verwalten der Konversationsverweise des Bots, wenn ein Botereignis ausgelöst wird. Das TeamsFx SDK erkennt die folgenden Botereignisse:

Document.SelectionChanged -Ereignis Verhalten
Wenn Sie einen Bot zum ersten Mal für eine Person, Gruppe oder ein Team installieren. Fügen Sie dem Speicher den Verweis auf die Zielkonversation hinzu.
Wenn der Bot von einer Person, Gruppe oder einem Team deinstalliert wird. Entfernen Sie den Zielkonversationsverweis aus dem Speicher.
Wenn das vom Bot installierte Team gelöscht wird. Entfernen Sie den Zielkonversationsverweis aus dem Speicher.
Wenn das vom Bot installierte Team wiederhergestellt wird. Fügen Sie dem Speicher den Verweis auf die Zielkonversation hinzu.
Wenn der Bot Nachrichten sendet. Wenn der Verweis auf die Zielkonversation nicht vorhanden ist, fügen Sie ihn dem Speicher hinzu.

Beispiel für ein neues Benachrichtigungsereignis

Wenn Sie Benachrichtigungen senden, erstellt das TeamsFx SDK eine neue Unterhaltung aus dem ausgewählten Konversationsverweis und sendet dann eine Nachricht. Für die erweiterte Verwendung können Sie direkt auf die Konversationsreferenz zugreifen, um Ihre eigene Botlogik auszuführen:

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // call Bot Framework's adapter.continueConversationAsync()
    await target.adapter.continueConversationAsync(
        target.botAppId,
        target.conversationReference,
        async (context) => {
            // your own bot logic
            await context...
        }
    );
}

Zurück zum Anfang

Installation des Benachrichtigungsbots

Je nach dem erforderlichen Bereich muss ein Benachrichtigungsbot in einem Team, einem Gruppenchat oder als persönliche App installiert werden. Sie müssen das Installationsziel auswählen, bevor Sie den Bot zu Ihrer App hinzufügen.

Hinzufügen des Installationsbereichs

Weitere Installationsoptionen finden Sie unter Konfigurieren von Standardinstallationsoptionen. Informationen zum Deinstallieren finden Sie unter Entfernen einer App aus Teams.

Zurück zum Anfang

Anpassen von Benachrichtigungen

Sie können die folgenden Anpassungen vornehmen, um die Benachrichtigungsvorlage an Ihre geschäftlichen Anforderungen zu erweitern:

Anpassen des Triggerpunkts aus der Ereignisquelle

Sie können die folgenden Trigger anpassen:

  • Restify basierende Benachrichtigung:

    • Wenn eine HTTP-Anforderung an den src/index.js Einstiegspunkt gesendet wird, sendet die Standardimplementierung eine adaptive Karte an Teams. Sie können dieses Ereignis anpassen, indem Sie ändern src/index.js. Eine typische Implementierung kann eine API aufrufen, um Ereignisse, Daten oder beides abzurufen, die eine adaptive Karte nach Bedarf senden können. Sie können folgendes ausführen, um weitere Trigger hinzuzufügen:

      • Erstellen Sie ein neues Routing: server.post("/api/new-trigger", ...).
      • Fügen Sie Timertrigger aus häufig verwendeten npm-Paketen wie Cron, node-schedule oder aus anderen Paketen hinzu.

      Hinweis

      Standardmäßig erstellt das Teams-Toolkit ein Gerüst für einen einzelnen restify Einstiegspunkt in src/index.js.

  • Azure Functions-basierte Benachrichtigung:

    • Wenn Sie trigger auswählen timer , sendet der standardmäßig implementierte Azure Function-Timertrigger src/timerTrigger.ts alle 30 Sekunden eine adaptive Karte. Sie können die Datei *Trigger/function.json bearbeiten, um die schedule Eigenschaft anzupassen. Weitere Informationen finden Sie in der Dokumentation zu Azure-Funktionen.

      Beispiel für eine durch timer ausgelöste Benachrichtigung

    • Wenn Sie den Trigger auswählen http , löst die HTTP-Anforderung die Benachrichtigung aus, und die Standardimplementierung sendet eine adaptive Karte an Teams. Sie können dieses Ereignis ändern, indem Sie anpassen src/*Trigger.ts. Diese Implementierung kann eine API aufrufen, um Ereignisse, Daten oder beides abzurufen, die eine adaptive Karte nach Bedarf senden können.

      Beispiel für durch HTTP ausgelöste Benachrichtigungen

  • Azure-Funktionstrigger:

    • Event Hub Trigger, um Benachrichtigungen zu senden, wenn ein Ereignis an Azure Event Hub gepusht wird.

    • Cosmos DB trigger, um Benachrichtigungen zu senden, wenn ein Cosmos-Dokument erstellt oder aktualisiert wird.

Weitere Informationen zu Supporttriggern finden Sie unter Azure Functions-Supporttrigger.

Anpassen des Benachrichtigungsinhalts

Die Datei src/adaptiveCards/notification-default.json definiert die adaptive Standardkarte. Sie können den Designer für adaptive Karten verwenden, um die Benutzeroberfläche für adaptive Karten visuell zu entwerfen. Definiert src/cardModels.ts eine Datenstruktur, die zum Laden von Daten für die adaptive Karte verwendet wird. Die Bindung zwischen dem Kartenmodell und der adaptiven Karte erfolgt durch einen übereinstimmenden Namen, z CardData.title . B. zuordnungen zu ${title} in der adaptiven Karte. Sie können Eigenschaften und deren Bindungen hinzufügen, bearbeiten oder entfernen, um die adaptive Karte nach Bedarf anzupassen.

Sie können bei Bedarf auch neue Karten hinzufügen. Weitere Informationen zum Erstellen verschiedener Typen von adaptiven Karten mit einer Liste oder einem Dynamischen Inhaltsverzeichnis mit ColumnSet und FactSetfinden Sie unter Beispiel für Benachrichtigungen für adaptive Karten.

Anpassen, wo Benachrichtigungen gesendet werden

Sie können das Senden der Benachrichtigung an die folgenden Ziele anpassen:

  • Benachrichtigungen an einen persönlichen Chat:

    // list all installation targets
    for (const target of await notificationApp.notification.installations()) {
        // "Person" means this bot is installed as Personal app
        if (target.type === "Person") {
            // Directly notify the individual person
            await target.sendAdaptiveCard(...);
        }
    }
    

  • Benachrichtigungen an einen Gruppenchat:

    // list all installation targets
    for (const target of await notificationApp.notification.installations()) {
        // "Group" means this bot is installed to a Group Chat
        if (target.type === "Group") {
            // Directly notify the Group Chat
            await target.sendAdaptiveCard(...);
    
                // List all members in the Group Chat then notify each member
                const members = await target.members();
                for (const member of members) {
                    await member.sendAdaptiveCard(...);
                }
            }
    
    }
    

  • Benachrichtigungen an einen Kanal:

    // list all installation targets
    for (const target of await notificationApp.notification.installations()) {
        // "Channel" means this bot is installed to a Team (default to notify General channel)
        if (target.type === "Channel") {
            // Directly notify the Team (to the default General channel)
            await target.sendAdaptiveCard(...);
    
            // List all members in the Team then notify each member
            const members = await target.members();
            for (const member of members) {
                await member.sendAdaptiveCard(...);
            }
    
            // List all channels in the Team then notify each channel
            const channels = await target.channels();
            for (const channel of channels) {
                await channel.sendAdaptiveCard(...);
            }
        }
    }
    

  • Benachrichtigungen an einen bestimmten Kanal:

    // find the first channel when the predicate is true.
    const channel = await notificationApp.notification.findChannel(c => Promise.resolve(c.info.name === "MyChannelName"));
    
    // send adaptive card to the specific channel.
    await channel?.sendAdaptiveCard(...);
    

    Hinweis

    Um eine nicht definierte Ausgabe zu verhindern, stellen Sie sicher, dass Sie die Bot-App im Kanal Allgemein eines Teams installieren.

  • Benachrichtigungen an eine bestimmte Person:

    // find the first person when the predicate is true.
    const member = await notificationApp.notification.findMember(m => Promise.resolve(m.account.name === "Bob"));
    
    // send adaptive card to the specific person. 
    await member?.sendAdaptiveCard(...);
    

    Hinweis

    Um eine nicht definierte Ausgabe und eine fehlende Benachrichtigung zu verhindern, müssen Sie die bestimmte Person in den Benachrichtigungsinstallationsbereich einschließen.

Zurück zum Anfang

Anpassen der Initialisierung

Sie müssen erstellen ConversationBot , um eine Benachrichtigung zu senden.

Hinweis

Der Code wird im Projekt generiert.

/** Javascript/Typescript: src/internal/initialize.*s **/
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
    },
});

Zurück zum Anfang

Anpassen des Adapters

Sie können anpassen, indem Sie einen eigenen Adapter erstellen oder den Adapter nach der Initialisierung anpassen. Es folgt das Codebeispiel zum Erstellen Ihres Adapters:

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const notificationApp = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
notificationApp.adapter.onTurnError = ...

Zurück zum Anfang

Hinzufügen von Speicherplatz

Speicher kann verwendet werden, um Benachrichtigungsverbindungen zu implementieren. Sie können Ihren eigenen Speicher mithilfe des folgenden Codebeispiels hinzufügen:

// implement your own storage
class MyStorage implements NotificationTargetStorage {...}
const myStorage = new MyStorage(...);

// initialize ConversationBot with notification enabled and customized storage
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
        storage: myStorage,
    },
});

Wenn kein Speicher bereitgestellt wird, können Sie einen standardmäßigen lokalen Dateispeicher verwenden, in dem Benachrichtigungsverbindungen gespeichert werden:

  • .notification.localstore.json , wenn lokal ausgeführt wird.
  • ${process.env.TEMP}/.notification.localstore.json, wenn process.env.RUNNING_ON_AZURE auf 1 festgelegt ist.

Wenn Sie den standardmäßigen lokalen Dateispeicher verwenden, bereinigen Die Azure-Web-App und Azure Functions die lokale Datei während eines Neustarts oder einer erneuten Bereitstellung. Sie können den Bot auch aus Teams deinstallieren und dann installieren, um dem Speicher erneut Verbindungen hinzuzufügen.

Unterscheidet NotificationTargetStorage sich vom benutzerdefinierten Speicher des Bot Framework SDK. Der Benachrichtigungsspeicher erfordert writeread, , deleteund list Funktionen, aber der Speicher des Bot Framework SDK verfügt über read, writeund delete Funktionen und verfügt nicht über die list Funktionalität.

Weitere Informationen zu Azure Blob Storage finden Sie im Notification Storage-Implementierungsbeispiel.

Hinweis

  • Es wird empfohlen, ihren eigenen freigegebenen Speicher für die Produktionsumgebung zu verwenden.
  • Wenn Sie ihren eigenen Bot Framework SDK-Speicher implementieren, z. B. , botbuilder-azure-blobs.BlobsStoragemüssen Sie einen anderen Speicher für Benachrichtigungen implementieren. Sie können dieselbe Blob-Verbindungszeichenfolge für verschiedene Container freigeben.

Zurück zum Anfang

Hinzufügen der Authentifizierung für die Benachrichtigungs-API

Wenn Sie HTTP-Trigger auswählen, ist die Authentifizierung oder Autorisierung für die Gerüstbenachrichtigungs-API nicht aktiviert. Stellen Sie sicher, dass Sie die Authentifizierung oder Autorisierung für die API hinzufügen, bevor Sie sie für die Produktion verwenden. Sie können eine der folgenden Aktionen ausführen:

Es kann weitere Authentifizierungs- oder Autorisierungslösungen für eine API geben, die Sie nach Bedarf auswählen können.

Zurück zum Anfang

Herstellen einer Verbindung mit vorhandenen APIs

Wenn Sie nicht über das erforderliche SDK verfügen und externe APIs in Ihrem Code aufrufen möchten, können Sie den Befehl Teams: Herstellen einer Verbindung mit einer API in microsoft Visual Studio Code Teams Toolkit-Erweiterung oder den Befehl teamsfx add api-connection in teamsFx CLI zum Bootstrap von Code zum Aufrufen von Ziel-APIs verwenden. Weitere Informationen finden Sie unter Integrieren vorhandener Drittanbieter-APIs.

Teams-Botanwendung oder eingehender Teams-Webhook

TeamsFx unterstützt zwei Möglichkeiten, Um Benachrichtigungen von Ihrem System an Teams zu senden:

  • Erstellen Sie eine Teams-Bot-App.
  • Erstellen Sie eingehenden Teams-Webhook.

In der folgenden Tabelle sehen Sie den Vergleich der beiden verschiedenen Möglichkeiten:

  Teams-Bot-App Eingehender Teams-Webhook
Nachricht einzelne Person ✔️
Nachrichtengruppenchat ✔️
Öffentlicher Nachrichtenkanal ✔️ ✔️
Privater Nachrichtenkanal ✔️
Senden einer Kartennachricht ✔️ ✔️
Begrüßungsnachricht senden ✔️
Abrufen des Teams-Kontexts ✔️
Installationsschritte in Teams erforderlich ✔️
Azure-Ressource anfordern Azure Bot Service

Eingehende Webhookbenachrichtigung

Eingehende Webhooks helfen beim Veröffentlichen von Nachrichten aus Apps in Teams. Wenn eingehende Webhooks für ein Team in einem beliebigen Kanal aktiviert sind, wird der HTTPS-Endpunkt verfügbar gemacht, der ordnungsgemäß formatierten JSON-Code akzeptiert und die Nachrichten in diesen Kanal einfügt. Sie können z. B. einen eingehenden Webhook in Ihrem DevOps-Kanal erstellen, Ihren Build konfigurieren und gleichzeitig Dienste bereitstellen und überwachen, um Warnungen zu senden. TeamsFx bietet Ihnen ein Beispiel für eingehende Webhook-Benachrichtigungen , mit dem Sie folgende Aktionen ausführen können:

Zurück zum Anfang

Benachrichtigungen über Aktivitätsfeeds senden

Wenn Sie Aktivitätsfeedbenachrichtigungen für Ihre App senden möchten, können Sie die Benachrichtigungs-APIs für Aktivitätsfeeds in Microsoft Graph verwenden. Weitere Informationen finden Sie unter Senden von Aktivitätsfeedbenachrichtigungen an Benutzer in Microsoft Teams.

Häufig gestellte Fragen


Warum sind die Benachrichtigungsinstallationen leer, obwohl die Bot-App in Teams installiert ist?

Teams sendet ein Ereignis nur bei der ersten Installation. Wenn die Bot-App bereits installiert ist, bevor Ihr Benachrichtigungsbotdienst gestartet wird, hat das Installationsereignis den Botdienst nicht erreicht oder wird ausgelassen.

Sie können dieses Problem auf folgende Weise beheben:

  • Senden Sie eine Nachricht an Ihren persönlichen Bot, oder erwähnen Sie Ihren Bot im Gruppenchat oder Kanal, wodurch Sie den Botdienst wieder mit korrekten Installationsinformationen erreichen können.
  • Deinstallieren Sie die Bot-App aus Teams, und führen Sie dann eine erneute Fehlerbehebung durch oder starten Sie sie neu. Sie können das Installationsereignis erneut an bot Service senden.

Benachrichtigungszielverbindungen werden im Persistenzspeicher gespeichert. Wenn Sie den lokalen Standarddateispeicher verwenden, werden alle Installationen unter .notification.localstore.jsongespeichert.

Hinweis

Weitere Informationen zum Hinzufügen ihres eigenen Speichers finden Sie unter Hinzufügen von Speicher.


Warum tritt beim Senden einer Benachrichtigung der Fehler "Ungültige Anforderung" oder "Ungültiges Argument" auf?

Wenn die Benachrichtigungsinstallation nicht mit der Bot-ID oder dem Kennwort übereinstimmt, erhalten Sie den Fehler Konversations-ID konnte nicht entschlüsselt werden . Eine mögliche Ursache für diesen Fehler ist, dass die Bot-ID oder das Kennwort aufgrund der Bereinigung des lokalen Zustands oder der erneuten Bereitstellung geändert wird.

Sie können dieses Problem beheben, indem Sie den Benachrichtigungsspeicher bereinigen. Benachrichtigen Sie nach der Bereinigung in Teams, ihren Bot neu zu installieren, und stellen Sie sicher, dass die neue Installation auf dem neuesten Stand ist. Jede gespeicherte Benachrichtigungsinstallation ist an einen Bot gebunden. Wenn Sie Ihren Benachrichtigungsspeicher überprüfen können, sollte das Botfeld mit dem von Ihnen ausgeführten Bot übereinstimmen, z. B. der Bot-ID mit derselben GUID.

Hinweis

Bei lokalem Speicher ist .notification.localstore.jsonder Standardspeicherort .


Warum geht das Benachrichtigungsziel nach dem Neustart oder erneuten Bereitstellen der Bot-App verloren?

Benachrichtigungszielverbindungen werden im Persistenzspeicher gespeichert. Wenn Sie den standardmäßigen lokalen Dateispeicher verwenden, bereinigen Die Azure-Web-App und Azure Functions die lokale Datei während eines Neustarts oder einer erneuten Bereitstellung. Sie können den Bot auch aus Teams deinstallieren und dann installieren, um dem Speicher erneut Verbindungen hinzuzufügen. Es wird empfohlen, ihren eigenen freigegebenen Speicher für die Produktionsumgebung zu verwenden.


Warum wird ein nicht definierter Fehler zurückgegeben, wenn die API "findChannel"() verwendet wird?

Es kann ein nicht definierter Fehler auftreten, wenn die Bot-App in anderen Kanälen anstelle des Kanals General installiert wird. Um diesen Fehler zu beheben, können Sie die Bot-App aus Teams deinstallieren und neu debuggen und neu starten. Stellen Sie nach dem erneuten Debuggen und Neustart sicher, dass die Bot-App im General Kanal installiert ist.


Kann ich alle Ziele kennen, auf denen mein Bot im Benachrichtigungsprojekt installiert ist?

Es gibt Microsoft Graph-APIs zum Auflisten von Apps, die in einem Team, einer Gruppe oder einem Chat installiert sind. Falls erforderlich, durchlaufen Sie Ihr Team, Ihre Gruppe oder chatten Sie in einer installierten App, um sie als Ziel zu verwenden. Im Benachrichtigungsprojekt wird Persistenzspeicher verwendet, um Installationsziele zu speichern. Weitere Informationen finden Sie unter Benachrichtigung basierend auf Ereignissen.


Wie passen Sie die Azurite-Überwachungsports an?

Wenn Azurite aufgrund des verwendeten Ports beendet wird, können Sie einen anderen Lauschport angeben und die Verbindungszeichenfolge von AzureWebJobsStorage in local.settings.jsonaktualisieren.


Wie kann ich meinen Benachrichtigungsbot erweitern, um Befehle und Antworten zu unterstützen?
  1. Wechseln Sie zu , bot\src\internal\initialize.ts(js) und aktualisieren Sie Ihre conversationBot Initialisierung, um das Benachrichtigungsfeature zu aktivieren:

    Initialisierung des Konversationsbots, um das Benachrichtigungsfeature zu aktivieren.

  2. Um Ihrem Bot einen Befehl hinzuzufügen, befolgen Sie die Anweisungen unter Befehlsbot in Teams.


Wie kann ich meinen Benachrichtigungsbot erweitern, indem ich Workflow-Bot-Aktionen für adaptive Karten hinzufübe?

Der Aktionshandler für adaptive Karten ermöglicht es der App, auf Aktionen für adaptive Karten zu reagieren, die von Endbenutzern ausgelöst werden, um einen sequenziellen Workflow abzuschließen. Eine adaptive Karte stellt eine oder mehrere Schaltflächen auf der Karte bereit, um benutzereingaben zu fragen, z. B. das Aufrufen einiger APIs. Die adaptive Karte sendet dann eine weitere adaptive Karte in der Unterhaltung, um auf die Kartenaktion zu reagieren.

Weitere Informationen zum Hinzufügen adaptiver Kartenaktionen zum Befehlsbot finden Sie unter Workflowbot in Teams.


Zurück zum Anfang

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung zum Erstellen eines Teams-Benachrichtigungsbots .

Siehe auch