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.
Aufrufen von Dialogfeldern (in TeamsJS v1.x als Aufgabenmodule bezeichnet) von Microsoft Teams-Bots mithilfe von TaskFetchAction Schaltflächen auf adaptiven Karten. Dialoge bieten eine fokussierte Interaktion, indem sie ein Popupfenster für den Benutzer öffnen, sodass sie sich ideal für komplexe Formulare oder mehrstufige Workflows eignen.
Es gibt zwei Möglichkeiten zum Aufrufen von Dialogen:
- Eine neue Aufrufmeldung
task/fetch: Mithilfe derAction.ExecuteKarte Aktion für adaptive Karten mittask/fetchwird entweder ein HTML- oder adaptives Karten-basiertes Dialogfeld dynamisch aus Ihrem Bot abgerufen. - Deep Link-URLs: Mithilfe der Deep Link-Syntax für Dialogfelder können Sie die
Action.OpenUrlaktion Karte für adaptive Karten verwenden. Bei Deep Link-URLs ist die Dialog-URL oder der Text der adaptiven Karte bereits bekannt, um einen Server-Roundtrip relativ zu zutask/fetchvermeiden.
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 Dialogstartprogramms
Um ein Dialogfeld über einen 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 zur *.cloud.microsoft Domäne migriert. Führen Sie so schnell wie möglich die folgenden Schritte aus, um sicherzustellen, dass Ihre App weiterhin auf unterstützten Microsoft 365-Webclienthosts gerendert wird:
Aktualisieren Sie die TeamsJS-Bibliothek auf v.2.19.0 oder höher. Sie müssen aufrufen
microsoftTeams.app.initialize(), um eine Warnung in der neuen Domäne zu vermeiden. 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-Vorgängerdirektive , 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. Dieser Ansatz stellt sicher, dass Ihre App weiterhin sowohl für vorhandene als auch für zukünftige Microsoft 365-Hostanwendungen funktioniert, und minimiert den Bedarf an nachfolgenden Änderungen.
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 Dialogs (in TeamsJS v1.x als Aufgabenmodul bezeichnet) mit task/fetch:
Diese Abbildung 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 behandeln Sie dies mithilfe desOnAdaptiveCardActionHandlers. Weitere Informationen finden Sie unter Ausführen von Aktionen.Der Bot erstellt ein
ActionResponse-Objekt und gibt es zurück. Weitere Informationen zum Schema für Antworten finden Sie in der Diskussion zu Aufgabe/Übermittlung. 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 des Ergebnisses eines Dialogs.
Übermitteln des Ergebnisses eines Dialogfelds
Wenn der Benutzer das Dialogfeld beendet hat, wird das Ergebnis zurück an Ihre App übermittelt. Wie die Übermittlung funktioniert, hängt vom Inhaltstyp des Dialogfelds ab:
-
Adaptive Karte (TaskInfo.Karte): Wenn der Benutzer eine
Action.SubmitSchaltfläche auswählt, sendet Teams ein Dialogfeld zum Senden eines Ereignisses an Ihre App. Der Dialog-Übermittlungshandler empfängt die Formulardaten aus dem 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 Webseite ruft
microsoftTeams.tasks.submitTask(formData)aus der TeamsJS-Clientbibliothek auf, die dasselbe Dialog-Übermittlungsereignis in Ihrer App auslöst.
Behandeln von Ereignissen zum Übermitteln von Dialogen
Wenn der Benutzer ein Dialogfeld übermittelt, empfängt der Bot eine task/submit Aufrufnachricht. Sie haben mehrere Optionen, wenn Sie antworten:
| Antworttyp | Szenario |
|---|---|
| Keine Antwort | Die einfachste Antwort ist überhaupt keine Antwort. Ihr Bot muss nicht reagieren, wenn der Benutzer den Dialog beendet hat. |
MessageTask |
Teams zeigt eine Nachricht in einem Popup-Meldungsfeld 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 Ereignisse zum Übermitteln von Dialogen in .NET, TypeScript und Python behandelt werden:
using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Activities.Invokes;
using Microsoft.Teams.Apps.Annotations;
using Microsoft.Teams.Common.Logging;
[TaskSubmit]
public async Task<Microsoft.Teams.Api.TaskModules.Response> OnTaskSubmit([Context] Tasks.SubmitActivity activity, [Context] IContext.Client client, [Context] ILogger log)
{
var data = activity.Value?.Data as JsonElement?;
if (data == null)
{
log.Info("[TASK_SUBMIT] No data found in the activity value");
return new Microsoft.Teams.Api.TaskModules.Response(
new Microsoft.Teams.Api.TaskModules.MessageTask("No data found in the activity value"));
}
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 client.Send($"Hi {name}, thanks for submitting the form!");
return new Microsoft.Teams.Api.TaskModules.Response(
new Microsoft.Teams.Api.TaskModules.MessageTask("Form was submitted"));
default:
return new Microsoft.Teams.Api.TaskModules.Response(
new Microsoft.Teams.Api.TaskModules.MessageTask("Unknown submission type"));
}
}
Mehrstufige Dialogverkettung
Sie können adaptive Karten in einen mehrstufigen Assistenten verketten, indem Sie eine ContinueTask Antwort vom Übermittlungshandler zurückgeben. Jeder Schritt gibt eine neue Karte zurück, und der letzte Schritt gibt einen MessageTask zurück, um den Dialog zu schließen.
using System.Text.Json;
using Microsoft.Teams.Api;
using Microsoft.Teams.Api.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");
var nextStepTaskInfo = new TaskInfo
{
Title = $"Thanks {nameStep1} - Get Email",
Card = new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = nextStepCard
}
};
return new Response(new ContinueTask(nextStepTaskInfo));
case "webpage_dialog_step_2":
var nameStep2 = GetFormValue("name") ?? "Unknown";
var emailStep2 = GetFormValue("email") ?? "No email";
await client.Send($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}");
return new Response(new MessageTask("Multi-step form completed successfully"));
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 Aktionen für adaptive KartenAction.Submit, und die Art und Weise zum Aufrufen von Dialogen unterscheidet sich ebenfalls. Das data -Objekt in Action.Submit enthält ein msteams -Objekt, sodass es andere Eigenschaften im 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 |
|---|---|---|---|---|---|
| Dialogbeispielbots-V4 | In dieser Beispiel-App wird veranschaulicht, wie Dialoge (in TeamsJS v1.x als Aufgabenmodule bezeichnet) mit Bot Framework v4 verwendet werden. | View | View | – | Anzeigen |