Verwenden von Dialogen mit Bots

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 Aufrufmeldungtask/fetch: Mithilfe der Action.Execute Karte Aktion für adaptive Karten mit task/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.OpenUrl aktion 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 zu task/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:

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

  2. Wenn Sie CSP-Header ( Content Security Policy ) für Ihre App definiert haben, aktualisieren Sie die Frame-Vorgängerdirektive , 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. 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

Aufgaben-/Abrufanforderung oder -Antwort

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

  1. Diese Abbildung 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 behandeln Sie dies mithilfe des OnAdaptiveCardAction Handlers. 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/Ü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/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 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.Submit Schaltflä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 Sie app.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
{
"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
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

Siehe auch