Verwenden von Aufgabenmodulen aus Bots

Aufgabenmodule können von Microsoft Teams Bots mithilfe von Schaltflächen auf adaptiven Karten und Bot Framework-Karten aufgerufen werden, die Hero, Miniaturansicht und Office 365 Connector sind. Aufgabenmodule sind häufig eine bessere Benutzererfahrung als mehrere Unterhaltungsschritte. Verfolgen Sie den Botstatus, und erlauben Sie dem Benutzer, die Sequenz zu unterbrechen oder abzubrechen.

Es gibt zwei Möglichkeiten zum Aufrufen von Aufgabenmodulen:

  • Eine neue Art von task/fetch Aufrufnachricht: Die Verwendung der invoke Kartenaktion für Bot Framework-Karten oder der Action.Submit Kartenaktion für adaptive Karten mit dem task/fetch Aufgabenmodul einer URL oder einer adaptiven Karte wird dynamisch von Ihrem Bot abgerufen.
  • Deep-Link-URLs: Mithilfe der Deep Link-Syntax für Aufgabenmodulekönnen Sie die openUrl Kartenaktion für Bot Framework-Karten bzw. die Action.OpenUrl Kartenaktion für adaptive Karten verwenden. Bei Deep-Link-URLs ist die URL des Aufgabenmoduls oder der Textkörper für adaptive Karten bereits bekannt, um einen Server-Roundtrip relativ zu zu task/fetch vermeiden.

Wichtig

Jedes url muss fallbackUrl das HTTPS-Verschlüsselungsprotokoll implementieren.

Der nächste Abschnitt enthält Details zum Aufrufen eines Aufgabenmoduls mit task/fetch .

Aufrufen eines Aufgabenmoduls mithilfe von "task/fetch"

Wenn das value Objekt der invoke Kartenaktion Action.Submit initialisiert oder initialisiert wird und ein Benutzer die Schaltfläche auswählt, wird eine invoke Nachricht an den Bot gesendet. In der HTTP-Antwort auf die invoke Nachricht ist ein TaskInfo-Objekt in ein Wrapperobjekt eingebettet, das Teams zum Anzeigen des Aufgabenmoduls verwendet.

Task-/Fetch-Anforderung oder -Antwort

Die folgenden Schritte stellen das Aufgabenmodul "Aufrufen" mithilfe von "task/fetch" bereit:

  1. Diese Abbildung zeigt eine Bot Framework-Hero-Karte mit einer Aktion invoke "Karte kaufen". Der Wert der type Eigenschaft task/fetch ist, und der Rest des value Objekts kann Von Ihrer Wahl sein.

  2. Der Bot empfängt die invoke HTTP POST-Nachricht.

  3. Der Bot erstellt ein Antwortobjekt und gibt es im Textkörper der POST-Antwort mit einem HTTP 200-Antwortcode zurück. Weitere Informationen zum Schema für Antworten finden Sie in der Erläuterung zum Thema "Aufgabe/Absenden". Der folgende Code enthält ein Beispiel für den Textkörper der HTTP-Antwort, die ein in ein Wrapperobjekt eingebettetes TaskInfo-Objekt enthält:

    {
      "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 Funktion im microsoftTeams.tasks.startTask() Client-SDK.

  4. Microsoft Teams zeigt das Aufgabenmodul an.

Der nächste Abschnitt enthält Details zum Übermitteln des Ergebnisses eines Aufgabenmoduls.

Übermitteln des Ergebnisses eines Aufgabenmoduls

Wenn der Benutzer mit dem Aufgabenmodul fertig ist, ähnelt das Senden des Ergebnisses an den Bot der Funktionsweise mit Registerkarten. Weitere Informationen finden Sie im Beispiel zum Übermitteln des Ergebnisses eines Aufgabenmoduls. Es gibt einige Unterschiede:

  • HTML oder JavaScript, d. TaskInfo.url h.: Nachdem Sie überprüft haben, was der Benutzer eingegeben hat, rufen Sie die SDK-Funktion auf, microsoftTeams.tasks.submitTask() die nachfolgend als aus submitTask() Lesbarkeitsgründen bezeichnet wird. Sie können submitTask() ohne Parameter aufrufen, wenn Teams das Aufgabenmodul schließen möchten, Aber Sie müssen ein Objekt oder eine Zeichenfolge an Ihre submitHandler übergeben. Übergeben Sie ihn als ersten Parameter, result . Teams aufgerufen submitHandler err wird, ist null und ist das Objekt oder die result Zeichenfolge, das Bzw. die Sie übergeben submitTask() haben. Wenn Sie submitTask() mit einem Parameter result aufrufen, müssen Sie ein oder ein Array von appId appId Zeichenfolgen übergeben. Dadurch können Teams überprüfen, ob die App, die das Ergebnis sendet, dieselbe ist, die das Aufgabenmodul aufgerufen hat. Ihr Bot empfängt eine task/submit Nachricht einschließlich result . Weitere Informationen finden Sie unter Nutzlast task/fetch und task/submit Nachrichten.
  • Adaptive Karte, d. TaskInfo.card h.: Der vom Benutzer ausgefüllte Textkörper der adaptiven Karte wird über eine Nachricht an den Bot task/submit gesendet, wenn der Benutzer eine beliebige Schaltfläche auswählt. Action.Submit

Der nächste Abschnitt enthält Details zur Flexibilität von task/submit .

Die Flexibilität von Aufgabe/Übermittlung

Wenn der Benutzer mit einem Aufgabenmodul fertig ist, das von einem Bot aufgerufen wird, erhält der Bot immer eine task/submit invoke Nachricht. Sie haben mehrere Optionen, wenn Sie auf die task/submit Nachricht wie folgt reagieren:

HTTP-Textkörperantwort Szenario
Keine ignoriert die task/submit Nachricht Die einfachste Antwort ist gar keine Antwort. Ihr Bot muss nicht antworten, wenn der Benutzer mit dem Aufgabenmodul fertig ist.
{
"task": {
"type": "message",
"value": "Message text"
}
}
Teams zeigt den Wert value in einem Popup-Meldungsfeld an.
{
"task": {
"type": "continue",
"value": <TaskInfo object>
}
}
Ermöglicht ihnen das Verketten von Sequenzen adaptiver Karten in einem Assistenten oder einer mehrstufigen Oberfläche.

Hinweis

Das Verketten adaptiver Karten in einer Sequenz ist ein erweitertes Szenario. Die Node.js-Beispiel-App unterstützt sie. Weitere Informationen finden Sie unter Microsoft Teams Aufgabenmodul Node.js.

Der nächste Abschnitt enthält Details zur Nutzlast task/fetch und task/submit zu Nachrichten.

Nutzlast von Aufgaben-/Abruf- und Aufgaben-/Sendenachrichten

In diesem Abschnitt wird das Schema definiert, was Ihr Bot empfängt, wenn er ein task/fetch task/submit Bot Framework-Objekt Activity empfängt. Die folgende Tabelle enthält die Eigenschaften der Nutzlast und der task/fetch task/submit Nachrichten:

Eigenschaft Beschreibung
type Ist immer invoke .
name Ist entweder task/fetch oder task/submit .
value Ist die vom Entwickler definierte Nutzlast. Die Struktur des value Objekts entspricht dem, was von Teams gesendet wird. In diesem Fall ist dies jedoch anders. Es erfordert Unterstützung für das dynamische Abrufen, das task/fetch sowohl vom Bot-Framework stammt, als auch von value Action.Submit adaptiven Kartenaktionen, also data . Eine Möglichkeit, Teams context an den Bot zu kommunizieren, ist zusätzlich zu dem, was in oder enthalten ist, value data erforderlich.

Kombinieren Sie "Wert" und "Daten" in einem übergeordneten Objekt:

{
"context": {
"theme": "default" | "dark" | "contrast",
},
"data": [value field from Bot Framework card] | [data field from Adaptive Card]
}

Der nächste Abschnitt enthält ein Beispiel für das Empfangen und Reagieren auf und Aufrufen von task/fetch task/submit Nachrichten in Node.js.

Beispiel für Task-/Fetch- und Task/Submit-Aufrufnachrichten in Node.js und C

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

Bot Framework-Kartenaktionen im Vergleich zu Aktionen für adaptive Karten.Submit-Aktionen

Das Schema für Bot Framework-Kartenaktionen unterscheidet sich von Action.Submit adaptiven Kartenaktionen, und die Möglichkeit zum Aufrufen von Aufgabenmodulen unterscheidet sich ebenfalls. Das data Objekt enthält ein Action.Submit msteams Objekt, sodass 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-Aktion
{
"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
Aufgabenmodul-Beispielbots-V4 Beispiele zum Erstellen von Aufgabenmodulen. View Anzeigen

Siehe auch