Usar módulos de tarefas dos bots

  • Artigo

Os módulos de tarefa podem ser invocados de bots do Microsoft Teams usando botões em Cartões Adaptáveis e cartões Bot Framework que são heróis, miniaturas e conector para Grupos do Microsoft 365. Os módulos de tarefa geralmente são uma melhor experiência do usuário do que várias etapas de conversa. Acompanhe o estado do bot e permita que o usuário interrompa ou cancele a sequência.

Há duas maneiras de invocar módulos de tarefa:

  • Uma nova mensagem task/fetchde invocação: usar a ação deinvoke cartão para cartões Bot Framework ou a ação deAction.Submit cartão para Cartões Adaptáveis, com task/fetch, módulo de tarefa uma URL ou um Cartão Adaptável, é buscada dinamicamente do bot.
  • URLs de link profundo: usando a sintaxe de link profundo para módulos de tarefa, você pode usar a ação deopenUrl cartão para cartões Bot Framework ou a ação deAction.OpenUrl cartão para Cartões Adaptáveis, respectivamente. Com URLs de link profundo, a URL do módulo de tarefa ou o corpo do Cartão Adaptável já é conhecido por evitar uma viagem de ida e volta do servidor em relação a task/fetch.

Importante

Cada url e fallbackUrl deve implementar o protocolo de criptografia HTTPS.

A próxima seção fornece detalhes sobre como invocar um módulo de tarefa usando task/fetch.

Invocar um módulo de tarefa usando task/fetch

Quando o objeto value da ação de cartão invoke ou Action.Submit é inicializado e quando um usuário seleciona o botão, uma invoke mensagem é enviada ao bot. Na resposta HTTP à invoke mensagem, há um objeto TaskInfo inserido em um objeto wrapper, que o Teams usa para exibir o módulo de tarefa.

tarefa/buscar solicitação ou resposta

As etapas a seguir fornecem o módulo de tarefa de invocação usando task/fetch:

  1. Esta imagem mostra um cartão herói do Bot Framework com umaaçãoComprarinvoke cartão. O valor da propriedade type é task/fetch e o restante do objeto value pode ser de sua escolha.

  2. O bot recebe a mensagem HTTP POST invoke.

  3. O bot cria um objeto de resposta e o retorna no corpo da resposta POST com um código de resposta HTTP 200. Para obter mais informações sobre o esquema de respostas, consulte a discussão sobre tarefa/envio. O código a seguir fornece um exemplo de corpo da resposta HTTP que contém um objeto TaskInfo inserido em um objeto wrapper:

    {
  "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"
    }
  }
}

    O task/fetch evento e sua resposta para bots são semelhantes à microsoftTeams.tasks.startTask() função na biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS).

  4. O Microsoft Teams exibe o módulo de tarefa.

A próxima seção fornece detalhes sobre como enviar o resultado de um módulo de tarefa.

Enviar o resultado de um módulo de tarefa

Quando o usuário é concluído com o módulo de tarefa, enviar o resultado de volta para o bot é semelhante à maneira como ele funciona com guias. Para obter mais informações, consulte exemplo de enviar o resultado de um módulo de tarefa. Há algumas diferenças da seguinte maneira:

  • HTML ou JavaScript: depois de TaskInfo.urlvalidar o que o usuário inseriu, você chamará a microsoftTeams.tasks.submitTask() função chamada posteriormente como submitTask() para fins de legibilidade. Você pode chamar submitTask() sem parâmetros se quiser que o Teams feche o módulo de tarefa, mas passe um objeto ou uma cadeia de caracteres para seu submitHandler. Passe-o como o primeiro parâmetro, result. O Teams invoca submitHandler, err é null, e result é o objeto ou cadeia de caracteres que você passou para submitTask(). Se você chamar submitTask() com um parâmetro result, você deve passar um appId ou uma matriz de cadeias de caracteres appId. Isso permite que o Teams valide que o aplicativo que envia o resultado é o mesmo, que invocou o módulo de tarefa. Seu bot recebe uma mensagem task/submit incluindo result. Para obter mais informações, consulte conteúdo de task/fetch e task/submit.
  • Cartão Adaptável que é TaskInfo.card: o corpo do Cartão Adaptável preenchido pelo usuário é enviado ao bot por meio de um task/submit quando o usuário seleciona qualquer botão Action.Submit.

A próxima seção fornece detalhes sobre como responder às task/submit mensagens.

Responde às task/submit mensagens

Quando o usuário termina com um módulo de tarefa invocado de um bot, o bot sempre recebe uma mensagem task/submit invoke. Você tem várias opções ao responder à mensagem task/submit da seguinte maneira:

Resposta do corpo HTTP Cenário
Nenhum ignora a task/submit mensagem A resposta mais simples não é nenhuma resposta. Seu bot não é necessário para responder quando o usuário terminar com o módulo de tarefa. 
{
  "tarefa": {
    "type": "message",
    "value": "Texto da mensagem"
  }
}
 O Teams exibe o valor de value em uma caixa de mensagem pop-up. 
{
  "tarefa": {
    "type": "continue",
    "value": <objeto TaskInfo>
  }
}
 Permite encadear sequências de Cartões Adaptáveis em uma experiência de assistente ou de várias etapas.

Observação

O encadeamento Cartões Adaptáveis em uma sequência é um cenário avançado. O aplicativo de exemplo Node.js dá suporte a ele. Para obter mais informações, consulte Módulo de tarefa Node.js do Microsoft Teams.

A próxima seção fornece detalhes sobre o conteúdo das mensagens task/fetch e task/submit.

Carga de task/fetch mensagens e task/submit

Esta seção define o esquema do que seu bot recebe quando recebe um objeto task/fetch ou task/submit Bot Framework Activity. A tabela a seguir fornece as propriedades de conteúdo das mensagens task/fetch e task/submit:

Propriedade Descrição
type É sempre invoke.
name É task/fetch ou task/submit.
value É a carga definida pelo desenvolvedor. A estrutura do objeto value é igual ao que é enviado do Teams. Nesse caso, no entanto, é diferente. Ele requer suporte para uma pesquisa dinâmica que é task/fetch de ambos os Bot Framework, que é value e as ações Action.Submit, que são data. Uma maneira de comunicar o Teams context ao bot é necessária além do que está incluído no value ou data.

Combine 'value' e 'data' em um objeto pai:

{
  "context": {
    "tema": "padrão" | "escuro" | "contraste",
  },
  "data": [campo de valor do cartão Bot Framework] | [campo de dados do Cartão Adaptável]
}

A próxima seção fornece um exemplo de recebimento e resposta a task/fetch e task/submit invocam mensagens no Node.js.

As seguintes guias fornecem task/fetch e task/submit invocam mensagens em Node.js e 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 ações do cartão vs. Ação do Cartão Adaptável.Enviar ações

O esquema para ações de cartão Bot Framework é diferente das ações Action.Submit e a maneira de invocar módulos de tarefa também é diferente. O data objeto no Action.Submit contém um msteams objeto para que ele não interfira em outras propriedades no cartão. A tabela a seguir mostra um exemplo de cada ação de cartão:

Bot Framework ação do cartão Ação De Cartão Adaptável.Enviar ação 
{
  "type": "invoke",
  "title": "Buy",
  "value": {
    "type": "task/fetch",
    <...>
  }
}
 
{
  "type": "Action.Submit",
  "id": "btnBuy",
  "title": "Buy",
  "data": {
    <...>,
    "msteams": {
      "type": "task/fetch"
    }
  }
}

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto
Bots de exemplo do módulo de tarefa -V4 Este exemplo mostra como criar módulos de tarefa usando a estrutura do bot v4 e a guia Teams. View View View

Guias passo a passo

Siga a guia passo a passo para criar e buscar o bot do módulo de tarefa no Teams.

Confira também