Adicionar capacidade de bot à aplicação Teams

Artigo
12/17/2024

Um bot, também conhecido como chatbot ou bot de conversação, é uma aplicação que responde a comandos simples numa definição de chat, fornecendo respostas relevantes. Os bots são frequentemente utilizados para várias tarefas, tais como notificar sobre falhas de compilação, fornecer atualizações meteorológicas, horários de autocarros ou informações de viagem. As interações do bot podem ir desde trocas simples de perguntas e respostas a conversações complexas. Enquanto aplicação na cloud, um bot pode oferecer acesso seguro e valioso a serviços cloud e recursos empresariais. Para obter mais informações, veja Build bots for Microsoft Teams (Criar bots para o Microsoft Teams).

Pré-requisitos

Para configurar o bot como uma capacidade adicional, certifique-se de que são cumpridos os seguintes pré-requisitos:

Aplicação Teams e o respetivo ficheiro de manifesto de aplicação (anteriormente denominado manifesto de aplicação do Teams)
Conta do Microsoft 365 para testar a aplicação
Conta do Microsoft Azure

Adicionar bot à aplicação de separador
Adicionar bot à aplicação de extensão de mensagens

Os passos seguintes ajudam-no a adicionar um bot a uma aplicação de separador:

Criar uma aplicação de bot com o Microsoft Teams Toolkit
Configurar a capacidade do bot no manifesto da aplicação
Adicionar código de bot ao projeto
Configurar o ambiente de depuração local
Aprovisionar a aplicação no Azure

Criar uma aplicação de bot com o Microsoft Teams Toolkit

Para criar uma aplicação de bot com o Teams Toolkit, consulte Criar uma aplicação de bot com o Teams Toolkit.

Configurar a capacidade do bot no manifesto da aplicação

Pode configurar a capacidade do bot no appPackage/manifest.json ficheiro. Para obter mais informações, veja esquema de manifesto de aplicação.

O fragmento de código seguinte é um exemplo:

    "bots": [
        {
            "botId": "${{BOT_ID}}",
            "scopes": [
                "personal",
                "team",
                "groupchat"
            ],
            "supportsFiles": false,
            "isNotificationOnly": false,
            "commandLists": [
                {
                    "scopes": [
                        "personal",
                        "team",
                        "groupchat"
                    ],
                    "commands": [
                        {
                            "title": "welcome",
                            "description": "Resend welcome card of this Bot"
                        },
                        {
                            "title": "learn",
                            "description": "Learn about Adaptive Card and Bot Command"
                        }
                    ]
                }
            ]
        }
    ]

Adicionar código de bot ao projeto

Crie uma bot/ pasta no seu projeto e copie o código fonte da aplicação bot para a pasta no Visual Studio Code. A estrutura de pastas do projeto tem o seguinte aspeto:

    |-- .vscode/
    |-- appPackage/
    |-- env/
    |-- infra/
    |--public/
    |-- bot/           <!--bot source code-->
    |   |-- adaptiveCards/
    |   |-- index.ts
    |   |-- config.ts
    |   |-- teamsBot.ts
    |   |-- package.json
    |   |-- tsconfig.json
    |   |-- web.config
    |   |-- .webappignore
    |-- src/            <!--your current source code-->
    |   |-- app.ts
    |   |-- static/
    |   |-- views/
    |-- package.json
    |-- tsconfig.json
    |-- teamsapp.local.yml
    |-- teamsapp.yml

Reorganize a estrutura de pastas da seguinte forma:

Dica

Utilize o comando npm init -y para criar um ficheiro de raiz package.json .

    |-- .vscode/
    |-- appPackage/
    |-- env/
    |-- infra/
    |-- bot/            <!--bot source code-->
    |   |-- adaptiveCards/
    |   |-- index.ts
    |   |-- config.ts
    |   |-- teamsBot.ts
    |   |-- package.json
    |   |-- tsconfig.json
    |   |-- web.config
    |   |-- .webappignore
    |-- tab/           <!--move your current source code to a new sub folder-->
    |   |-- src/
    |   |   |-- app.ts
    |   |   |-- static/
    |   |   |-- views/
    |   |-- package.json
    |   |-- tsconfig.json
    |-- package.json <!--root package.json-->
    |-- teamsapp.local.yml
    |-- teamsapp.yml

Adicione o seguinte código à raiz package.json:

    "scripts": {
      "test": "echo \"Error: no test specified\" && exit 1",
      "install:bot": "cd bot && npm install",
      "install:tab": "cd tab && npm install",
      "install": "concurrently \"npm run install:bot\" \"npm run install:tab\"",
      "dev:bot": "cd bot && npm run dev",
      "start:tab": "cd tab && npm run start",
      "build:tab": "cd tab && npm run build",
      "build:bot": "cd bot && npm run build",
      "build": "concurrently \"npm run build:tab\" \"npm run build:bot\""
    },
    "dependencies": {
        "concurrently": "^7.6.0"
    },

Observação

Num projeto JavaScript, pode executar o projeto sem uma build pasta. Tem de remover o build:bot script e atualizar o build script para npm run build:tab.

Configurar o ambiente de depuração local

Atualize .vscode/tasks.json da seguinte forma:

Adicione três novas tarefas: Start local tunnel, Start bote Start frontend.
Atualize a Start application matriz da dependsOn tarefa para incluir Start bot e Start frontend.
Configure a opção cwd para Start bot e Start frontend. Esta ação é necessária, uma vez que moveu anteriormente o código do separador e bot para as respetivas pastas enquanto reorganizava a estrutura de pastas.
Adicione Start local tunnel à Start Teams App Locally matriz da dependsOn tarefa.

    "tasks":[
            {
                // Start the local tunnel service to forward public URL to local port and inspect traffic.
                // See https://aka.ms/teamsfx-tasks/local-tunnel for the detailed args definitions.
                "label": "Start local tunnel",
                "type": "teamsfx",
                "command": "debug-start-local-tunnel",
                "args": {
                    "type": "dev-tunnel",
                    "ports": [
                        {
                            "portNumber": 3978,
                            "protocol": "http",
                            "access": "public",
                            "writeToEnvironmentFile": {
                                "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
                                "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
                            }
                        }
                    ],
                    "env": "local"
                },
                "isBackground": true,
                "problemMatcher": "$teamsfx-local-tunnel-watch"
            },
            {
                "label": "Start bot",
                "type": "shell",
                "command": "npm run dev:teamsfx",
                "isBackground": true,
                "options": {
                    "cwd": "${workspaceFolder}/bot"
                },
                "problemMatcher": {
                    "pattern": [
                        {
                            "regexp": "^.*$",
                            "file": 0,
                            "location": 1,
                            "message": 2
                        }
                    ],
                    "background": {
                        "activeOnStart": true,
                        "beginsPattern": "[nodemon] starting",
                        "endsPattern": "restify listening to|Bot/ME service listening at|[nodemon] app crashed"
                    }
                }
            },
            {
               "label": "Start frontend",
               "type": "shell",
               "command": "npm run dev:teamsfx",
               "isBackground": true,
               "options": {
                    "cwd": "${workspaceFolder}/tab"
                },
                "problemMatcher": {
                    "pattern": {
                        "regexp": "^.*$",
                        "file": 0,
                        "location": 1,
                        "message": 2
                    },
                    "background": {
                        "activeOnStart": true,
                        "beginsPattern": ".*",
                        "endsPattern": "listening to|Compiled|Failed|compiled|failed"
                    }
                }
            },
             {
                 "label": "Start application",
                 "dependsOn": [
                     "Start bot",
                     "Start frontend"
                 ]
             },
             {
                 "label": "Start Teams App Locally",
                 "dependsOn": [
                     "Validate prerequisites",
                     "Start local tunnel",
                     "Provision",
                     "Deploy",
                     "Start application"
                 ],
                 "dependsOrder": "sequence"
             },
    ]

teamsapp.local.yml No ficheiro:

Em provision, adicione as ações botAadApp/create e botFramework/create .
Em deploy, atualize o código da ação file/createOrUpdateEnvironmentFile .

 provision:
   - uses: botAadApp/create
     with:
       # The Microsoft Entra application's display name
       name: bot-${{TEAMSFX_ENV}}
     writeToEnvironmentFile:
       # The Microsoft Entra application's client id created for bot.
       botId: BOT_ID
       # The Microsoft Entra application's client secret created for bot.
       botPassword: SECRET_BOT_PASSWORD 

   # Create or update the bot registration on dev.botframework.com
   - uses: botFramework/create
     with:
       botId: ${{BOT_ID}}
       name: bot
       messagingEndpoint: ${{BOT_ENDPOINT}}/api/messages
       description: ""
       channels:
         - name: msteams
 deploy:
   - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
     with:
       target: ./tab/.localConfigs
       envs:
         BROWSER: none
         HTTPS: true
         PORT: 53000
         SSL_CRT_FILE: ${{SSL_CRT_FILE}}
         SSL_KEY_FILE: ${{SSL_KEY_FILE}}

   - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
     with:
       target: ./bot/.localConfigs
       envs:
         BOT_ID: ${{BOT_ID}}
         BOT_PASSWORD: ${{SECRET_BOT_PASSWORD}}

Para obter mais informações, veja exemplo de aplicação.

Em Executar e Depurar, selecione Depurar (Edge) ou Depurar (Chrome).
Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams localmente.

Aprovisionar a aplicação no Azure

Copie a botRegistration/ pasta do bot para infra/.

Adicione o seguinte código ao azure.bicep ficheiro:

 param resourceBaseName2 string
 param webAppName2 string = resourceBaseName2
 @maxLength(42)
 param botDisplayName string
 @description('Required when create Azure Bot service')
 param botAadAppClientId string

 @secure()
 @description('Required by Bot Framework package in your bot project')
 param botAadAppClientSecret string
 resource webApp2 'Microsoft.Web/sites@2021-02-01' = {
   kind: 'app'
   location: location
   name: webAppName2
   properties: {
     serverFarmId: serverfarm.id
     httpsOnly: true
     siteConfig: {
       alwaysOn: true
       appSettings: [
         {
           name: 'WEBSITE_RUN_FROM_PACKAGE'
           value: '1' // Run Azure APP Service from a package file
         }
         {
           name: 'WEBSITE_NODE_DEFAULT_VERSION'
           value: '~18' // Set NodeJS version to 18.x for your site
         }
         {
           name: 'RUNNING_ON_AZURE'
           value: '1'
         }
         {
           name: 'BOT_ID'
           value: botAadAppClientId
         }
         {
           name: 'BOT_PASSWORD'
           value: botAadAppClientSecret
         }
       ]
       ftpsState: 'FtpsOnly'
     }
   }
 }

 // Register your web service as a bot with the Bot Framework
 module azureBotRegistration './botRegistration/azurebot.bicep' = {
   name: 'Azure-Bot-registration'
   params: {
     resourceBaseName: resourceBaseName
     botAadAppClientId: botAadAppClientId
     botAppDomain: webApp2.properties.defaultHostName
     botDisplayName: botDisplayName
   }
 }

 // The output will be persisted in .env.{envName}. Visit https://aka.ms/teamsfx-actions/arm-deploy for more details.
 output BOT_AZURE_APP_SERVICE_RESOURCE_ID string = webApp2.id
 output BOT_DOMAIN string = webApp2.properties.defaultHostName

Para garantir que os parâmetros necessários estão definidos corretamente, atualize o azure.parameters.json ficheiro com o seguinte código:

 {
 "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
 "contentVersion": "1.0.0.0",
 "parameters": {
   "resourceBaseName": {
     "value": "tab${{RESOURCE_SUFFIX}}"
   },
   "webAppSku": {
     "value": "B1"
   },
   "botAadAppClientId": {
     "value": "${{BOT_ID}}"
   },
   "botAadAppClientSecret": {
     "value": "${{SECRET_BOT_PASSWORD}}"
   },
   "botDisplayName": {
     "value": "bot"
   },
   "resourceBaseName2":{
     "value": "bot${{RESOURCE_SUFFIX}}"
   }
 }
 }

teamsapp.yml No ficheiro:

Em provision, adicione a ação botAadApp/create . Para obter mais informações, veja exemplo de aplicação.
deploy Na secção , adicione o seguinte código:

 deploy:
   - uses: cli/runNpmCommand # Run npm command
     with:
       args: install
   - uses: cli/runNpmCommand # Run npm command
     with:
       args: run build
   # Deploy bits to Azure Storage Static Website
   - uses: azureAppService/zipDeploy
     with:
       workingDirectory: ./tab
       # Deploy base folder
       artifactFolder: .
       # Ignore file location, leave blank will ignore nothing
       ignoreFile: .webappignore
       # The resource id of the cloud resource to be deployed to.
       # This key will be generated by arm/deploy action automatically.
       # You can replace it with your existing Azure Resource id
       # or add it to your environment variable file.
       resourceId: ${{TAB_AZURE_APP_SERVICE_RESOURCE_ID}}
   - uses: azureAppService/zipDeploy
     with:
       workingDirectory: ./bot
       # Deploy base folder
       artifactFolder: .
       # Ignore file location, leave blank will ignore nothing
       ignoreFile: .webappignore
       # The resource id of the cloud resource to be deployed to.
       # This key will be generated by arm/deploy action automatically.
       # You can replace it with your existing Azure Resource id
       # or add it to your environment variable file.
       resourceId: ${{BOT_AZURE_APP_SERVICE_RESOURCE_ID}}

Aceda a Ver>Paleta de Comandos... ou selecione Ctrl+Shift+P.
Introduza Teams: Provision para aplicar o bicep ao Azure.
Introduza Teams: Deploy para implementar o código da aplicação de separador no Azure.
Em Executar e Depurar, selecione Iniciar Remoto (Edge) ou Iniciar Remoto (Chrome).
Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams.

Pode adicionar a capacidade do bot a uma aplicação de extensão de mensagens facilmente, uma vez que as extensões de mensagens são criadas no Bot Framework.

Os passos seguintes ajudam-no a adicionar a capacidade de bot a uma aplicação de extensão de mensagem:

Criar uma aplicação de bot com o Teams Toolkit
Atualizar ficheiro de manifesto
Adicionar código de bot ao projeto

Criar uma aplicação de bot com o Teams Toolkit

Para criar uma aplicação de bot com o Teams Toolkit, consulte Criar uma nova aplicação de bot do Teams.

Atualizar ficheiro de manifesto

Pode configurar a capacidade do bot no appPackage/manifest.json ficheiro. Para obter mais informações, veja esquema de manifesto de aplicação.

O fragmento de código seguinte é um exemplo:

 "bots": [
     {
         "botId": "${{BOT_ID}}",
         "scopes": [
             "personal",
             "team",
             "groupchat"
         ],
         "supportsFiles": false,
         "isNotificationOnly": false,
         "commandLists": [
             {
                 "scopes": [
                     "personal",
                     "team",
                     "groupchat"
                 ],
                 "commands": [
                     {
                         "title": "welcome",
                         "description": "Resend welcome card of this Bot"
                     },
                     {
                         "title": "learn",
                         "description": "Learn about Adaptive Card and Bot Command"
                     }
                 ]
             }
         ]
     }
 ]

Adicionar código de bot ao projeto

A sua aplicação de extensão de mensagem contém uma classe que expande TeamsActivityHandler. Copie o código do bot configurado da aplicação de bot para esta classe no Visual Studio Code. O código seguinte é um exemplo de uma extensão de mensagem que contém funções de uma aplicação de bot criada no Teams Toolkit:

   public class YourHandler extends TeamsActivityHandler{

     // bot code
     constructor(){
       super();
       this.likeCountObj = { likeCount: 0 };
       this.onMessage(async (context, next) => {});
       this.onMembersAdded(async (context, next) => {});
     }
     async onAdaptiveCardInvoke(context: TurnContext,
 invokeValue: AdaptiveCardInvokeValue):  Promise<AdaptiveCardInvokeResponse> {};

     /**
      * your own message extension code
     */
   }

Aceda a Ver>Paleta de Comandos... ou selecione Ctrl+Shift+P.
Introduza Teams: Provision para aplicar o bicep ao Azure.
Introduza Teams: Deploy para implementar o código da aplicação de separador no Azure.
Em Executar e Depurar, selecione Iniciar Remoto (Edge) ou Iniciar Remoto (Chrome).
Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams.

Próxima etapa

Manuais de instruções para adicionar capacidades

Confira também

Configurar pipelines de CI/CD

Compartilhar via

Adicionar capacidade de bot à aplicação Teams

Pré-requisitos

Criar uma aplicação de bot com o Microsoft Teams Toolkit

Configurar a capacidade do bot no manifesto da aplicação

Adicionar código de bot ao projeto

Configurar o ambiente de depuração local

Aprovisionar a aplicação no Azure

Criar uma aplicação de bot com o Teams Toolkit

Atualizar ficheiro de manifesto

Adicionar código de bot ao projeto

Próxima etapa

Confira também

Recursos adicionais