Verwenden von Dialogfeldern mit Bots

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 Aufrufnachrichttask/fetch: Verwenden der Action.Execute Kartenaktion für adaptive Karten mit task/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.OpenUrl Kartenaktion 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 zu task/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:

  1. 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.

  2. Wenn Sie CSP-Header ( Content Security Policy ) für Ihre App definiert haben, aktualisieren Sie die Frame-Ancestors-Direktive , um die *.cloud.microsoft Domäne einzuschließen. Um die Abwärtskompatibilität während der Migration sicherzustellen, behalten Sie die vorhandenen frame-ancestors Werte 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

Aufgaben-/Abrufanforderung oder -Antwort

Die folgenden Schritte enthalten Anweisungen zum Aufrufen eines Dialogfelds (in TeamsJS v1.x als Aufgabenmodul bezeichnet) mit task/fetch:

  1. Dieses Bild zeigt eine adaptive Karte mit einer Aktion "KaufenAction.Execute Karte". Der Wert der type Eigenschaft ist task/fetch, und der Rest des data Objekts kann von Ihrer Wahl sein.

  2. Der Bot empfängt eine card.action Aktivität. Im Teams SDK handhaben Sie dies mithilfe des Handlers OnAdaptiveCardAction . Weitere Informationen finden Sie unter Ausführen von Aktionen.

  3. 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/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/fetch Ereignis und seine Antwort für Bots ähneln der microsoftTeams.tasks.startTask() Funktion in der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS).

  4. 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.Submit Schaltflä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 Sie app.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
{
"type": "invoke",
"title": "Buy",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Buy",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

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

Siehe auch