Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Dialogfelder (in TeamsJS v1.x als Aufgabenmodule bezeichnet) von Microsoft Teams-Bots mithilfe TaskFetchAction von Schaltflächen auf adaptiven Karten aufrufen. Dialoge bieten eine fokussierte Interaktion, indem sie ein Popup-Fenster für den Benutzer öffnen, was sie ideal für komplexe Formulare oder mehrstufige Workflows macht.
Es gibt zwei Möglichkeiten zum Aufrufen von Dialogfeldern:
- Eine neue Aufrufnachricht
task/fetch: Verwenden derAction.ExecuteKartenaktion für adaptive Karten mittask/fetchwird entweder ein HTML- oder ein adaptiver kartenbasierter Dialog dynamisch von Ihrem Bot abgerufen. - Deep-Link-URLs: Wenn Sie die Deep-Link-Syntax für Dialoge verwenden, können Sie die
Action.OpenUrlKartenaktion für adaptive Karten verwenden. Bei Deep-Link-URLs ist bereits bekannt, dass die Dialog-URL oder der Text der adaptiven Karte einen Serverroundtrip relativ zutask/fetchvermeidet.
Wichtig
fallbackUrl Jeder url muss das HTTPS-Verschlüsselungsprotokoll implementieren.
Hinweis
Im Teams-Client v1 wurden Dialoge als Aufgabenmodule bezeichnet. Sie können gelegentlich synonym verwendet werden.
Erstellen eines Dialogfeld-Startprogramms
Um einen Dialog von einem Bot aufzurufen, senden Sie eine adaptive Karte mit TaskFetchAction Schaltflächen. Jede Schaltfläche enthält Daten, die Ihr Bot verwendet, um zu bestimmen, welcher Dialoginhalt zurückgegeben werden soll.
Warnung
Die Clouddienste von Microsoft, einschließlich Webversionen von Teams, Outlook und Microsoft 365-Domänen, werden auf die *.cloud.microsoft Domäne migriert. Führen Sie die folgenden Schritte so bald wie möglich aus, um sicherzustellen, dass Ihre App weiterhin auf unterstützten Microsoft 365-Webclienthosts gerendert wird:
Aktualisieren Sie die TeamsJS-Bibliothek auf Version 2.19.0 oder höher. Sie müssen anrufen
microsoftTeams.app.initialize(), um zu vermeiden, dass in der neuen Domäne eine Warnung angezeigt wird. Weitere Informationen zur neuesten Version von TeamsJS finden Sie unter Microsoft Teams JavaScript-Clientbibliothek.Wenn Sie CSP-Header ( Content Security Policy ) für Ihre App definiert haben, aktualisieren Sie die Frame-Ancestors-Direktive , um die
*.cloud.microsoftDomäne einzuschließen. Um die Abwärtskompatibilität während der Migration sicherzustellen, behalten Sie die vorhandenenframe-ancestorsWerte in Ihren CSP-Headern bei. Durch diesen Ansatz wird sichergestellt, dass Ihre App sowohl in vorhandenen als auch in zukünftigen Microsoft 365-Hostanwendungen weiterhin funktioniert, und die Notwendigkeit nachfolgender Änderungen wird minimiert.
Aktualisieren Sie die folgende Domäne in der frame-ancestors Direktive der CSP-Header Ihrer App:
https://*.cloud.microsoft
Die folgenden Schritte enthalten Anweisungen zum Aufrufen eines Dialogfelds (in TeamsJS v1.x als Aufgabenmodul bezeichnet) mit task/fetch:
Dieses Bild zeigt eine adaptive Karte mit einer Aktion "Kaufen
Action.ExecuteKarte". Der Wert dertypeEigenschaft isttask/fetch, und der Rest desdataObjekts kann von Ihrer Wahl sein.Der Bot empfängt eine
card.actionAktivität. Im Teams SDK handhaben Sie dies mithilfe des HandlersOnAdaptiveCardAction. Weitere Informationen finden Sie unter Ausführen von Aktionen.Der Bot erstellt ein
ActionResponseObjekt und gibt es zurück. Weitere Informationen zum Schema für Antworten finden Sie in der Diskussion zu Aufgabe/Senden. Der folgende Code enthält ein Beispiel für den Antworttext, der ein TaskInfo-Objekt enthält, das in ein Wrapperobjekt eingebettet ist:{ "task": { "type": "continue", "value": { "title": "Task module title", "height": 500, "width": "medium", "url": "https://contoso.com/msteams/taskmodules/newcustomer", "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer" } } }Das
task/fetchEreignis und seine Antwort für Bots ähneln dermicrosoftTeams.tasks.startTask()Funktion in der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS).Microsoft Teams zeigt das Dialogfeld an.
Der nächste Abschnitt enthält Details zum Übermitteln der Ergebnisse eines Dialogfelds.
Übermitteln des Ergebnisses eines Dialogfelds
Wenn der Benutzer mit dem Dialogfeld fertig ist, wird das Ergebnis an Ihre App zurückgesendet. Wie die Übermittlung funktioniert, hängt vom Inhaltstyp des Dialogs ab:
-
Adaptive Karte (TaskInfo.Karte): Wenn der Benutzer eine
Action.SubmitSchaltfläche auswählt, sendet Teams ein Dialogübermittlungsereignis an Ihre App. Ihr Handler zum Senden des Dialogs empfängt die Formulardaten von der Karte. Verwenden Sie in C# das[TaskSubmit]Attribut. Verwenden Sieapp.on('dialog.submit', ...)in TypeScript . Verwenden Sie@app.on_dialog_submitin Python . -
Webseite (TaskInfo.url): Die Webseitenaufrufe
microsoftTeams.tasks.submitTask(formData)aus der TeamsJS-Clientbibliothek, die dasselbe Dialogübermittlungsereignis in Ihrer App auslöst.
Behandeln von Dialogfeldübermittlungsereignissen
Wenn der Benutzer ein Dialogfeld übermittelt, erhält der Bot eine task/submit Aufrufnachricht. Sie haben mehrere Optionen beim Antworten:
| Antworttyp | Szenario |
|---|---|
| Keine Antwort | Die einfachste Antwort ist überhaupt keine Antwort. Ihr Bot muss nicht antworten, wenn der Benutzer mit dem Dialogfeld fertig ist. |
MessageTask |
Teams zeigt eine Meldung in einem Popupmeldungsfeld im Dialogfeld an. |
ContinueTask |
Ermöglicht es Ihnen, Sequenzen adaptiver Karten in einem Assistenten oder in mehreren Schritten miteinander zu verketten. |
Die folgenden Registerkarten zeigen, wie Dialogübermittlungsereignisse in .NET, TypeScript und Python behandelt werden:
using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.TaskModules;
teams.OnTaskSubmit(async (context, cancellationToken) =>
{
var data = context.Activity.Value?.Data as JsonElement?;
if (data == null)
{
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("No data found in the activity value")
.Build();
}
var submissionType = data.Value.TryGetProperty("submissiondialogtype", out var submissionTypeObj) && submissionTypeObj.ValueKind == JsonValueKind.String
? submissionTypeObj.ToString()
: null;
string? GetFormValue(string key)
{
if (data.Value.TryGetProperty(key, out var val))
{
if (val is JsonElement element)
return element.GetString();
return val.ToString();
}
return null;
}
switch (submissionType)
{
case "simple_form":
var name = GetFormValue("name") ?? "Unknown";
await context.SendAsync($"Hi {name}, thanks for submitting the form!", cancellationToken);
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Form was submitted")
.Build();
default:
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Unknown submission type")
.Build();
}
});
Mehrstufige Dialogverkettung
Sie können Adaptive Karten zu einem mehrstufigen Assistenten verketten, indem Sie eine ContinueTask Antwort vom Sendehandler zurückgeben. Jeder Schritt gibt eine neue Karte zurück, und der letzte Schritt gibt eine MessageTask zurück, um das Dialogfeld zu schließen.
using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Apps.TaskModules;
using Microsoft.Teams.Cards;
// Add these cases to your OnTaskSubmit method
case "webpage_dialog_step_1":
var nameStep1 = GetFormValue("name") ?? "Unknown";
var nextStepCardJson = $$"""
{
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "Email",
"size": "Large",
"weight": "Bolder"
},
{
"type": "Input.Text",
"id": "email",
"label": "Email",
"placeholder": "Enter your email",
"isRequired": true
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Submit",
"data": {"submissiondialogtype": "webpage_dialog_step_2", "name": "{{nameStep1}}"}
}
]
}
""";
var nextStepCard = JsonSerializer.Deserialize<AdaptiveCard>(nextStepCardJson)
?? throw new InvalidOperationException("Failed to deserialize next step card");
TeamsAttachment nextStepAttachment = TeamsAttachment.CreateBuilder()
.WithAdaptiveCard(JsonSerializer.SerializeToElement(nextStepCard))
.Build();
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Continue)
.WithTitle($"Thanks {nameStep1} - Get Email")
.WithCard(nextStepAttachment)
.Build();
case "webpage_dialog_step_2":
var nameStep2 = GetFormValue("name") ?? "Unknown";
var emailStep2 = GetFormValue("email") ?? "No email";
await context.SendAsync($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}", cancellationToken);
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Multi-step form completed successfully")
.Build();
Bot Framework-Kartenaktionen im Vergleich zu Aktionsaktionen für adaptive Karten.Übermitteln von Aktionen
Das Schema für Bot Framework Karte-Aktionen unterscheidet sich von adaptiven Action.Submit Kartenaktionen, und auch die Art und Weise, Dialoge aufzurufen, unterscheidet sich. Das data Objekt in Action.Submit enthält ein msteams Objekt, damit es andere Eigenschaften auf der Karte nicht beeinträchtigt. Die folgende Tabelle zeigt ein Beispiel für jede Kartenaktion:
| Bot Framework-Kartenaktion | Aktion für adaptive Karten.Submit |
|---|---|
{ |
{ |
Codebeispiel
| Beispielname | Beschreibung | .NET | Node.js | Manifest | Python |
|---|---|---|---|---|---|
| Dialogbeispiel-bots-V4 | Diese Beispiel-App zeigt, wie Dialogfelder (in TeamsJS v1.x als Aufgabenmodule bezeichnet) mit Bot Framework v4 verwendet werden. | View | View | – | Anzeigen |