Der ausgehende Webhook fungiert als Bot und sucht mithilfe von @Erwähnung nach Nachrichten in Kanälen. Er sendet Benachrichtigungen an einen externen Webdienst und antwortet mit umfangreichen Nachrichten, die Karten und Bilder enthalten. Es hilft, den Erstellungsprozess von Bots über die Microsoft Bot Framework zu überspringen.
Wichtige Features von ausgehenden Webhooks
Die folgende Tabelle enthält die Features und die Beschreibung ausgehender Webhooks:
Features
Beschreibung
Konfigurationsbereich
Webhooks werden auf Teamebene definiert. Der obligatorische Setupprozess für jeden fügt einen ausgehenden Webhook hinzu.
Reaktives Messaging
Benutzer müssen @Erwähnung verwenden, damit der Webhook Nachrichten empfangen kann. Die Benutzer können einen ausgehenden Webhook nur in öffentlichen Kanälen und nicht innerhalb des persönlichen oder privaten Bereichs senden.
Standard-HTTP-Nachrichtenaustausch
Antworten werden in derselben Kette wie die ursprüngliche Anforderungsnachricht angezeigt und können beliebige Bot Framework-Nachrichteninhalte enthalten. Beispielsweise Rich-Text, Bilder, Karten und Emojis. Ausgehende Webhooks können zwar Karten, jedoch keine Kartenaktionen (mit Ausnahme von openURL) verwenden.
Unterstützung der Teams-API-Methode
Ausgehende Webhooks senden einen HTTP POST an einen Webdienst und erhalten eine Antwort. Sie können nicht auf andere APIs zugreifen, um z. B. die Liste oder die Liste der Kanäle in einem Team abzurufen.
Erstellen ausgehender Webhooks
Erstellen Sie ausgehende Webhooks, und fügen Sie Benutzerdefinierte Bots zu Teams hinzu. Folgen Sie diesen Schritten, um einen ausgehenden Webhook zu erstellen:
Wählen Sie im linken Bereich Teams aus.
Wählen Sie auf der Seite Teams das erforderliche Team aus, um einen ausgehenden Webhook zu erstellen, und wählen Sie ••• aus.
Wählen Sie im Dropdownmenü Team verwalten aus.
Wählen Sie auf der Kanalseite Apps aus.
Wählen Sie unter App hochladen die Option Ausgehenden Webhook erstellen aus.
Geben Sie auf der Seite Ausgehenden Webhook erstellen die folgenden Details ein:
Name: Der Webhooktitel und die Registerkarte @Erwähnung.
Rückruf-URL: Der HTTPS-Endpunkt, der JSON-Nutzlasten akzeptiert und POST-Anforderungen von Teams empfängt.
Beschreibung: Eine ausführliche Zeichenfolge, die im Profil Karte und der Dashboard auf Teamebene angezeigt wird.
Profilbild: Ein App-Symbol für Ihren Webhook, das optional ist.
Wählen Sie Erstellen aus. Der ausgehende Webhook wird dem Kanal des Teams hinzugefügt.
Ein Dialogfeld hashbasierter Nachrichtenauthentifizierungscode (HMAC) wird angezeigt. Es handelt sich um ein Sicherheitstoken, das zum Authentifizieren von Aufrufen zwischen Teams und dem angegebenen externen Dienst verwendet wird. Das HMAC-Sicherheitstoken läuft nicht ab und ist für jede Konfiguration eindeutig.
Hinweis
Der ausgehende Webhook steht den Benutzern des Teams nur zur Verfügung, wenn die URL gültig ist und die Server- und Clientauthentifizierungstoken gleich sind. Beispielsweise ein HMAC-Handshake.
Das folgende Szenario enthält die Details zum Hinzufügen eines ausgehenden Webhooks:
Szenario: Pushen von Änderungsstatusbenachrichtigungen auf einem Teams-Kanaldatenbankserver an Ihre App.
Beispiel: Sie verfügen über eine benutzerdefinierte App, die für Ihre Organisation (LOB-App) erstellt wurde, die alle CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren und Löschen) nachverfolgt. Diese Vorgänge werden von Teams-Kanal-HR-Benutzern in einem Microsoft 365-Mandanten an die Mitarbeiterdatensätze vorgenommen.
erstellen Sie eine URL auf dem Server Ihrer App, um eine POST-Anforderung mit einer JSON-Nutzlast zu akzeptieren und zu verarbeiten
Ihr Dienst empfängt Nachrichten in einem standardmäßigen Azure Bot Service-Messagingschema. Der Bot Framework-Connector ist ein RESTful-Dienst, der es ermöglicht, den Austausch von Nachrichten im JSON-Format über HTTPS-Protokolle zu verarbeiten, wie in der Azure Bot Service-API dokumentiert. Alternativ können Sie dem Microsoft Bot Framework SDK folgen, um Nachrichten zu verarbeiten und zu analysieren. Weitere Informationen finden Sie unter Übersicht über Azure Bot Service.
Ausgehende Webhooks sind auf die team-Ebene beschränkt und für alle Teammitglieder sichtbar. Benutzer müssen @Erwähnung den Namen des ausgehenden Webhooks, um ihn im Kanal aufzurufen.
Erstellen einer Methode zum Überprüfen des HMAC-Tokens für ausgehenden Webhook
Beispiel für eingehende Nachricht und ID: "contoso" von SigningKeyDictionary von {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.
Verwenden Sie den Wert "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" in der Autorisierung des Anforderungsheaders.
Um sicherzustellen, dass Ihr Dienst nur Anrufe von tatsächlichen Teams-Clients empfängt, stellt Teams einen HMAC-Code im HTTP-hmac-Autorisierungsheader bereit. Schließen Sie den Code immer in Ihr Authentifizierungsprotokoll ein.
Ihr Code muss die in der Anforderung enthaltene HMAC-Signatur immer wie folgt überprüfen:
Generieren Sie das HMAC-Token aus dem Anforderungstext der Nachricht. Es gibt Standardbibliotheken, um dies auf den meisten Plattformen zu tun, z. B . Crypto für Node.js und Teams-Webhookbeispiel für C#. Microsoft Teams verwendet SHA256 HMAC-Standardkryptografie. Sie müssen den Text in ein Bytearray in UTF8 konvertieren.
Berechnen Sie den Hash aus dem Bytearray des Sicherheitstokens, das von Teams bereitgestellt wird, wenn Sie den ausgehenden Webhook im Teams-Client registriert haben. Weitere Informationen finden Sie unter Erstellen eines ausgehenden Webhooks.
Konvertieren Sie den Hash mithilfe der UTF-8-Codierung in eine Zeichenfolge.
Vergleichen Sie den Zeichenfolgenwert des generierten Hashs mit dem in der HTTP-Anforderung angegebenen Wert.
public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
//...
string providedHmacValue = authenticationHeaderValue.Parameter;
string calculatedHmacValue = null;
try
{
byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
byte[] keyBytes = Convert.FromBase64String(signingKey);
using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
{
byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
calculatedHmacValue = Convert.ToBase64String(hashBytes);
}
if (string.Equals(providedHmacValue, calculatedHmacValue))
{
return new AuthResponse(true, null);
}
else
{
string errorMessage = string.Format(
"AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
calculatedHmacValue,
providedHmacValue);
return new AuthResponse(false, errorMessage);
}
}
catch (Exception ex)
{
Trace.TraceError("Exception occcured while verifying HMAC on the incoming request. Exception: {0}", ex);
return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
}
}
Erstellen einer Methode zum Senden einer Erfolgs- oder Fehlerantwort
Antworten von ausgehenden Webhooks werden in derselben Antwortkette wie die ursprüngliche Nachricht angezeigt. Wenn der Benutzer eine Abfrage durchführt, gibt Teams eine synchrone HTTP-Anforderung an Ihren Dienst aus, und Ihr Code erhält fünf Sekunden Zeit, um auf die Nachricht zu antworten, bevor die Verbindung abläuft und beendet wird.
Beispielantwort
{
"type": "message",
"text": "This is a reply!"
}
Verwenden von adaptiven Karten mit ausgehenden Webhooks
Sie können mit einem ausgehendem Webhook adaptive Karten, Herokarten und SMS als Anlage senden.
Karten unterstützen die Formatierung. Weitere Informationen finden Sie unter Formatieren von Karten mit Markdown.
Adaptive Karte in ausgehenden Webhooks unterstützt nur openURL Karte Aktionen.
Die folgenden Codes sind Beispiele für eine adaptive Kartenantwort:
// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
{
content = await reader.ReadToEndAsync();
}
var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
Body = new List<AdaptiveElement>()
{
new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
}
};
var attachment = new Attachment()
{
ContentType = AdaptiveCard.ContentType,
Content = Card
};
var sampleResponseActivity = new Activity
{
Attachments = new [] { attachment }
};
return sampleResponseActivity;
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
Feedback zu Platform Docs
Platform Docs ist ein Open Source-Projekt. Wählen Sie einen Link aus, um Feedback zu geben:
Demonstrieren Sie Fertigkeiten zum Planen, Bereitstellen, Konfigurieren und Verwalten von Microsoft Teams, um sich auf effiziente und effektive Zusammenarbeit und Kommunikation in einer Microsoft 365-Umgebung zu konzentrieren.