Partilhar via

Bot de fluxo de trabalho no Teams

  • Artigo

Um bot de fluxo de trabalho permite que os utilizadores interajam com um Cartão Ajustável. O processador de ações cartão ajustável permite que o cartão ajustável converse na aplicação Teams. Pode criar um bot de fluxo de trabalho em vários cenários para os seus utilizadores melhorarem a experiência do utilizador, como a gestão de incidentes, pedidos de suporte, fluxo de trabalho de aprovação e cartões de gestão de projetos. Pode criar e atribuir um item de trabalho com o bot de fluxo de trabalho e sincronizar o conteúdo com o Azure DevOps ou o sistema Jira.

Um bot de fluxo de trabalho pode ser instalado numa equipa, chat de grupo ou como aplicação pessoal, dependendo de diferentes âmbitos. A lógica de comando predefinida devolve um Cartão Ajustável. Pode personalizar esta lógica com o seu requisito empresarial. Para a personalização, tem de chamar as APIs existentes.

Vantagens:

  • Automatiza processos empresariais e fluxos de trabalho repetitivos sem sair do contexto das conversações.

  • Suporta utilizadores com fluxo de trabalho sequencial através de vários cartões progressivamente, sem enviar cartões adicionais.

  • Fornece vistas específicas do utilizador atualizadas.

  • Simplifica o modelo de programação com o SDK do TeamsFx.

    Observação

    Pode selecionar a capacidade que pretende instalar ao adicionar a aplicação. Para obter mais informações, veja Configurar opções de instalação predefinidas.

Pode criar um bot de fluxo de trabalho para responder ao Cartão Ajustável acionado pelos utilizadores. O processador de ações cartão ajustável com tecnologia teamsFx SDK pode executar a ação Action.Execute universal cartão ajustável acionada pelos utilizadores. Em resposta a esta respetiva ação de cartão na conversação, o processador de ações Cartão Ajustável envia outro Cartão Ajustável.

Captura de ecrã a mostrar o resultado final de um bot de fluxo de trabalho no Teams.

Processador de ações de cartão

Para simplificar a criação de um bot de fluxo de trabalho, o SDK do TeamsFx fornece um processador de ações cartão ajustável TeamsFxAdaptiveCardActionHandler. Pode concentrar-se apenas no desenvolvimento do bot de fluxo de trabalho para responder à ação de cartão sem aprender o Bot Framework.

O diagrama seguinte ilustra como responder a uma ação cartão ajustável com o SDK teamsFx:

Diagrama a mostrar o processador de ações do cartão de bot de fluxo de trabalho.

  1. Cartão de ação: o cartão onde define a ação que os utilizadores podem invocar, por exemplo o DoStuff.
  2. Processador de ações de cartão: acionado quando os utilizadores invocam a ação de cartão correspondente, triggerVerb é igual à propriedade na ação verb Cartão Ajustável. Pode enviar um cartão de resposta para responder à ação.
  3. Cartão de resposta: o cartão que responde à ação quando o utilizador o invoca a partir do cartão de ação.

Para processar ações de cartões com o SDK do TeamsFx, cada processador de ações de cartão tem de implementar a TeamsFxAdaptiveCardActionHandler interface:


TeamsFxAdaptiveCardActionHandler 
{
    /**
     * The verb defined in adaptive card action that can trigger this handler.
     */
    triggerVerb: string;

    /**
     * Specify the behavior for how the card response will be sent in Teams conversation.
     * The default value is `AdaptiveCardResponse.ReplaceForInteractor`, which means the card
     * response will replace the current one only for the interactor.
     */
    adaptiveCardResponse?: AdaptiveCardResponse;
    
    /**
     * The handler function that will be invoked when the action is fired.
     * @param context The turn context.
     * @param actionData The contextual data that associated with the action.
     */
    handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse>;
}

Personalizar inicialização

Pode inicializar o bot de fluxo de trabalho com o seu próprio adaptador ou personalizar após a inicialização. A inicialização predefinida está localizada em bot/src/internal/initialize.js(ts).

Pode atualizar a lógica de inicialização para:

  1. Defina options.adapter para utilizar o seu próprio BotFrameworkAdapter.
  2. Defina options.command.commands para incluir vários processadores de comandos.
  3. Defina options.cardAction.actions para incluir vários processadores de ações.
  4. Defina options.{feature}.enabled para ativar várias ConversationBot funcionalidades.

Para obter mais informações sobre a personalização da inicialização, veja Personalização de inicialização adicional

Adicionar ações de cartão

Para adicionar ações de cartão com JavaScript e TypeScript, siga estes passos:


1. Adicionar uma ação ao seu Cartão Ajustável

Pode adicionar uma nova ação (botão) a um Cartão Ajustável ao defini-la no ficheiro JSON, tal como adicionar uma nova DoSomething ação ao src/adaptiveCards/helloworldCommandResponse.json ficheiro.

O código seguinte é um exemplo do tipo Action.Executede ação :

{ 
  "type": "AdaptiveCard", 
  "body": [
    ...
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "DoSomething",
          "verb": "doSomething" 
        }
      ]
    },
    ...
  ]
}

Quando a ação é invocada no Teams, é necessária a propriedade verbo, para que o SDK de conversação do TeamsFx possa invocar o processador de ações correspondente.

Observação

Certifique-se de que fornece uma cadeia exclusiva global para a propriedade do verbo, quando estiver a utilizar uma cadeia geral que possa causar uma colisão com outro bot. Isto pode evitar comportamentos inesperados.


2. Responder com novo Cartão Ajustável

Pode devolver um novo Cartão Ajustável para cada ação invocada para apresentar a resposta ao utilizador final. Tem de criar um novo ficheiro, bot/src/adaptiveCards/doSomethingResponse.json como resposta para a ação doSomething com o seguinte conteúdo:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "A sample response to DoSomething."
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

Observação

Pode estruturar o seu esquema de cartão de acordo com as suas necessidades empresariais. Veja Estruturador de cartões ajustável.


3. Adicionar processador de ações

Pode processar uma nova ação invocada pelo Cartão Ajustável com a classe TeamsFxAdaptiveCardActionHandlerdo SDK teamsFx . Tem de personalizar a ação neste passo, como chamar uma API, processar dados ou qualquer outra ação de acordo com as suas necessidades empresariais.

Pode criar um novo ficheiro bot/src/cardActions/doSomethingActionHandler.js:

    const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
    const { AdaptiveCardResponse, InvokeResponseFactory } = require("@microsoft/teamsfx");
    const responseCard = require("../adaptiveCards/doSomethingResponse.json");

    class DoSomethingActionHandler { 
    triggerVerb = "doStuff";

        async handleActionInvoked(context, message) { 
            const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
            return InvokeResponseFactory.adaptiveCard(responseCardJson);
        }
    }

     module.exports = {

       DoSomethingActionHandler,
    }

Observação

  • triggerVerb é a propriedade verbo da sua ação.
  • actionData são os dados associados à ação, que podem incluir a entrada dinâmica do utilizador ou alguns dados contextuais fornecidos na propriedade de dados da sua ação.
  • Se for devolvido um Cartão Ajustável, o cartão existente é substituído por predefinição.

4. Registar o processador de ações

Tem de configurar cada nova ação de cartão no conversationBot que ativa o fluxo de conversação do modelo de bot de fluxo de trabalho. Pode navegar para o bot/src/internal/initialize.js(ts) ficheiro e atualizar a actions matriz da cardAction propriedade .

Os passos seguintes ajudam-no a registar o processador de ações:

  1. Pode abrir o ficheiro bot/src/internal/initialize.js(ts).

  2. Tem de atualizar conversationBot a inicialização para ativar cardAction a funcionalidade. Adicione o processador à actions matriz com o seguinte código:

          const conversationBot = new ConversationBot({ 
     ... 
     cardAction: { 
       enabled: true, 
       actions: [ 
         new DoStuffActionHandler(),
         new DoSomethingActionHandler() 
       ], 
     } 
   });

    Observação

    Para saber mais sobre como expandir o modelo de bot fluxo de trabalho, veja Responder a ações de cartões no Teams


Personalizar a resposta da ação

Pode utilizar a adaptiveCardResponse propriedade no processador para personalizar a forma como o bot envia o Cartão Ajustável aos utilizadores. Seguem-se as três opções a personalizar:

  • O cartão de resposta é substituído pelo cartão atual onde o botão é definido para o interator que aciona a ação. Os utilizadores na conversação ainda podem ver o cartão AdaptiveCardResponse.ReplaceForInteractor de ação original por predefinição.

    Captura de ecrã a mostrar como personalizar a forma como o bot envia um cartão adaptável.

  • O cartão de resposta é substituído pelo cartão de ação para todos os utilizadores na conversa e podem ver o cartão AdaptiveCardResponse.ReplaceForAllde resposta .

    Captura de ecrã a mostrar o cartão de ação substituído para todos os utilizadores na conversa com o botão de confirmação.

    Captura de ecrã a mostrar o cartão de ação substituído para todos os utilizadores no chat sem o botão de confirmação.

  • O cartão de resposta é enviado como uma mensagem separada na conversação que não pode substituir o cartão de ação. Todos os utilizadores no chat podem ver o cartão AdaptiveCardResponse.NewForAllde resposta .

    Captura de ecrã a mostrar o cartão de resposta enviado para todos como utilizadores na conversa como uma mensagem separada.

Responder com mensagem sms

Também pode responder com mensagens SMS em vez de utilizar o Cartão Adaptável para a resposta de ação do cartão, utilizando InvokeResponseFactory.textMessage:

async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
    return InvokeResponseFactory.textMessage("This is a sample card action response!");
}

Pode ver a seguinte mensagem de resposta no Teams:

Captura de ecrã a mostrar uma resposta de cartão de exemplo.

Responder com mensagens de erro

Quando quiser devolver uma mensagem de resposta de erro ao cliente, pode aplicar-se InvokeResponseFactory.errorResponse para criar a resposta de invocação. A imagem seguinte mostra a mensagem de erro no Cartão Ajustável:

Captura de ecrã a mostrar uma mensagem de resposta a erros.

Observação

Para obter mais informações sobre o formato de resposta de invocação, veja formato de resposta.

Personalizar conteúdo do Cartão Ajustável

Pode editar o ficheiro src/adaptiveCards/helloworldCommand.json para personalizar o Cartão Ajustável de acordo com a sua preferência. O ficheiro src/cardModels.ts define uma estrutura de dados utilizada para preencher dados para o Cartão Ajustável.

O enlace entre o modelo e o Cartão Ajustável é efetuado por nome correspondente, como, por exemplo, CardData.title mapeia para ${title} no Cartão Ajustável. Pode adicionar, editar ou remover propriedades e os respetivos enlaces para personalizar o Cartão Ajustável de acordo com as suas necessidades.

Também pode adicionar novos cartões, se necessário para a sua aplicação. Para criar diferentes tipos de Cartões Ajustáveis com uma lista ou um índice dinâmico com ColumnSet o e FactSet, consulte TeamsFx-Samples.

Atualizar automaticamente para a vista específica do utilizador

Quando os Cartões Ajustáveis são enviados num canal do Teams ou chat de grupo, todos os utilizadores podem ver o mesmo conteúdo do cartão. Com o novo modelo de atualização para a ação universal cartões ajustáveis, os utilizadores podem ter uma vista específica do utilizador. A atualização automática também facilita cenários como aprovações, controlos de criador de inquéritos, pedidos de suporte, gestão de incidentes e cartões de gestão de projetos. O diagrama seguinte ilustra como fornecer uma vista específica do utilizador com refresh o modelo:

Diagrama a mostrar um modelo de atualização automática específico do utilizador.

  1. Cartão base: o bot envia uma mensagem com a versão base do cartão. Este cartão base pode ser enviado como uma notificação de bot, resposta de comando ou qualquer outra resposta de ação de cartão. Todos os membros da conversação podem ver a mesma resposta. O cartão base é atualizado automaticamente para o utilizador definido userId na refresh propriedade do cartão base.

  2. Comportamento da atualização: depois de o utilizador ver a mensagem, o cliente do Teams aciona automaticamente uma atualização um minuto após a última resposta de atualização. O processador de vistas específico do utilizador é invocado para devolver uma vista Response Card de cartão para um utilizador UserAespecífico. Os outros utilizadores na conversação ainda podem ver o cartão base.

A imagem seguinte ilustra a forma como a vista específica do utilizador é apresentada no Teams:

Captura de ecrã a mostrar uma vista específica do utilizador no Teams.

Adicionar vista específica do utilizador

Os passos seguintes ajudam-no a adicionar uma vista específica do utilizador com o SDK do TeamsFx:


1. Ativar a atualização no Cartão Adaptável base

As vistas específicas do utilizador são atualizadas a partir de um cartão base, quando o cartão de resposta é atualizado a partir do cartão base, conforme ilustrado na vista específica do utilizador de atualização automática. Pode ativar a atualização automática no cartão base da seguinte forma:

  • A primeira opção permite a atualização da vista específica do utilizador com o SDK. O cartão base pode ser enviado como uma resposta de comando ou uma resposta de ação de cartão. Pode ativar a atualização da vista específica do utilizador num handleCommandReceived processador de comandos ou no handleActionInvoked processador de ações do cartão onde o cartão base é devolvido. Pode utilizar refresh(refreshVerb, userIds, data) o @microsoft/adaptivecards-tools método da biblioteca para injetar uma secção de atualização no cartão base. Para definir a secção de atualização, certifique-se de que fornece as seguintes propriedades:

    1. userIds: um conjunto de MRIs de utilizador para quem pode acionar a atualização automática. Para obter mais informações sobre como adicionar a lista na userIds secção de atualização do Cartão Ajustável, consulte Obter a lista ou perfil de utilizador.
    2. verb: uma cadeia para identificar a ação de atualização.
    3. data: dados opcionais a associar à ação de atualização.

    No exemplo seguinte, um cartão base devolve como resposta de comando que pode atualizar automaticamente para um utilizador específico, como o remetente do comando:

             import baseCard from "../adaptiveCards/baseCard.json";
         import { AdaptiveCards } from "@microsoft/adaptivecards-tools";

         export class MyCommandHandler1 implements TeamsFxBotCommandHandler {
         triggerPatterns: TriggerPatterns = "helloWorld";

         async handleCommandReceived(context: TurnContext, message: CommandMessage): 
         Promise<string | Partial<Activity> | void> {
         const refreshVerb = "userViewRefresh";        // verb to identify the refresh action
         const userIds = [ context.activity.from.id ]; // users who will be refreshed
         const data = { key: "value"};                 // optional data associated with the action

         const responseCard = AdaptiveCards
           .declare(baseCard)
           .refresh(refreshVerb, userIds, data)
           .render(cardData);

             return MessageFactory.attachment(CardFactory.adaptiveCard(responseCard));
         }
       }

  • A segunda opção permite que a vista específica do utilizador atualize o Seu Cartão Ajustável. Esta é uma ação de atualização de exemplo definida em baseCard.json:

    {
  "type": "AdaptiveCard",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Refresh",
      "verb": "userViewRefresh" ,
      "data": {
        "key": "value"
      }
    },
    "userIds": [
      "${userID}"
    ]
  },
  "body": [
    ...
  ],
  ...
}

    Tem de substituir ${userID} pela ressonância magnética do utilizador no código, ao compor o conteúdo do cartão.


2. Adicionar Cartão Ajustável específico do utilizador

Tem de estruturar o Cartão Ajustável específico do utilizador para atualizar um cartão de resposta específico, como responseCard.jsonuserA o mostrado no diagrama para comportamento de atualização. Para começar, pode criar um responseCard.json com o seguinte conteúdo e guardá-lo na bot/src/adaptiveCards pasta:

-
{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "This is a user-specific view"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

3. Adicionar processador de ações de cartão para atualizar vistas

Pode adicionar um processador que implementa TeamsFxAdaptiveCardActionHandler para processar a atividade de invocação de atualização que é acionada automaticamente no Teams:

import responseCard from "../adaptiveCards/responseCard.json";

export class Handler1 implements TeamsFxBotCardActionHandler {
    triggerVerb: string = "userViewRefresh";

    async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
      /**
       * If you have multiple userIds defined in your refresh action, for example: userIds: [ "<UserA>", "<userB>" ] ,
       * and you can return different card response for those users respectively with the following code sample.
        
        const currentUserId = context.activity.from.id;
        switch (currentUserId) {
          case "<userA's id>":
            const card1 = AdaptiveCards.declare(card1).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card1);
          case "<userB's id>":
            const card1 = AdaptiveCards.declare(card2).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card2);
        }
     */
      const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
      return InvokeResponseFactory.adaptiveCard(responseCardJson);
    } 
}

4. Registar o processador de ações

Pode registar o processador de ações de atualização no bot/src/internal/initialize.js(ts) com o seguinte código:

export const commandBot = new ConversationBot({
  ...
  cardAction: {
    enabled: true,
    actions: [
      new Handler1()
    ],
  }
})

Acesso Microsoft Graph

Se estiver a responder a um comando que precisa de aceder aos dados do Microsoft Graph de um utilizador do Teams já com sessão iniciada, pode fazê-lo através do início de sessão único (SSO) com o token de utilizador do Teams. Leia mais sobre como o Teams Toolkit pode ajudá-lo a adicionar o início de sessão único à aplicação Teams.

Ligar a APIs existentes

Muitas vezes, tem de se ligar às APIs existentes para obter dados para enviar para o Teams. O Teams Toolkit facilita a configuração e a gestão da autenticação das APIs existentes. Para obter mais informações, veja como integrar APIs de terceiros existentes.

Perguntas frequentes


Como expandir o bot de fluxo de trabalho com notificações?

As notificações adicionam a capacidade na sua aplicação de enviar Cartões Ajustáveis em resposta a eventos externos. Por exemplo, quando uma mensagem é publicada num Hub de Eventos, a sua aplicação pode responder com um Cartão Ajustável conforme necessário. Como expandir o bot de fluxo de trabalho com notificações, veja Personalizar notificações.


Como expandir o bot de fluxo de trabalho com comando e resposta?

O bot de fluxo de trabalho predefinido inclui comando e resposta. Para obter mais informações sobre como expandir o bot de fluxo de trabalho com comando e resposta, veja Adicionar comando e resposta.


Guias passo a passo

Siga o guia passo a passo para criar o bot de fluxo de trabalho do Teams.

Confira também