Adición de la funcionalidad de bot a la aplicación Teams

Artículo
12/17/2024

Un bot, también conocido como bot de chat o bot conversacional, es una aplicación que responde a comandos sencillos en una configuración de chat, lo que proporciona respuestas pertinentes. Los bots se usan normalmente para varias tareas, como notificar sobre errores de compilación, proporcionar actualizaciones meteorológicas, programaciones de autobús o información de viajes. Las interacciones de bots pueden ir desde intercambios simples de preguntas y respuestas hasta conversaciones complejas. Como aplicación en la nube, un bot puede ofrecer acceso seguro y valioso a los servicios en la nube y a los recursos corporativos. Para obtener más información, consulte Compilación de bots para Microsoft Teams.

Requisitos previos

Para configurar el bot como una funcionalidad adicional, asegúrese de que se cumplen los siguientes requisitos previos:

Archivo de aplicación de Teams y su manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams)
Cuenta de Microsoft 365 para probar la aplicación
Cuenta de Microsoft Azure

Agregar bot a la aplicación de pestaña
Adición de bot a la aplicación de extensión de mensajes

Los pasos siguientes le ayudan a agregar bot a una aplicación de pestaña:

Creación de una aplicación de bot con el kit de herramientas de Microsoft Teams
Configuración de la funcionalidad del bot en el manifiesto de aplicación
Adición de código de bot al proyecto
Configuración del entorno de depuración local
Aprovisionamiento de la aplicación en Azure

Creación de una aplicación de bot con el kit de herramientas de Microsoft Teams

Para crear una aplicación de bot con Teams Toolkit, consulte Creación de una aplicación de bot con Teams Toolkit.

Configuración de la funcionalidad del bot en el manifiesto de aplicación

Puede configurar la funcionalidad del bot en el appPackage/manifest.json archivo. Para obtener más información, consulte esquema de manifiesto de aplicación.

El siguiente fragmento de código es un ejemplo:

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

Adición de código de bot al proyecto

Cree una bot/ carpeta en el proyecto y copie el código fuente de la aplicación de bot en la carpeta de Visual Studio Code. La estructura de carpetas del proyecto tiene el siguiente aspecto:

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

Reorganizar la estructura de carpetas de la siguiente manera:

Sugerencia

Use el comando npm init -y para crear un archivo raíz 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

Agregue el código siguiente a la raíz 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"
    },

Nota:

En un proyecto de JavaScript, puede ejecutar el proyecto sin una build carpeta. Debe quitar el build:bot script y actualizarlo build a npm run build:tab.

Configuración del entorno de depuración local

Actualice .vscode/tasks.json de la siguiente manera:

Agregue tres nuevas tareas: Start local tunnel, Start boty Start frontend.
Actualice la matriz de la Start applicationdependsOn tarea para incluir Start bot y Start frontend.
Configure la cwd opción para Start bot y Start frontend. Esta acción es necesaria, ya que anteriormente ha movido el código de la pestaña y el bot a sus carpetas respectivas mientras reorganiza la estructura de carpetas.
Agregue Start local tunnel a la matriz de la dependsOnStart Teams App Locally tarea.

    "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"
             },
    ]

En el teamsapp.local.yml archivo:

En provision, agregue las botAadApp/create acciones y botFramework/create .
En deploy, actualice el código de la file/createOrUpdateEnvironmentFile acción.

 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 obtener más información, consulte aplicación de ejemplo.

En Ejecutar y depurar, seleccione Depurar (Edge) o Depurar (Chrome).
Seleccione la tecla F5 para depurar y obtener una vista previa de la aplicación de Teams localmente.

Aprovisionamiento de la aplicación en Azure

Copie la botRegistration/ carpeta del bot en infra/.

Agregue el código siguiente al azure.bicep archivo:

 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 asegurarse de que los parámetros necesarios se establecen correctamente, actualice el azure.parameters.json archivo con el código siguiente:

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

En el teamsapp.yml archivo:

En provision, agregue la botAadApp/create acción. Para obtener más información, consulte aplicación de ejemplo.
En la deploy sección , agregue el código siguiente:

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

Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.
Escriba Teams: Provision para aplicar el bicep a Azure.
Escriba Teams: Deploy para implementar el código de la aplicación de pestaña en Azure.
En Ejecutar y depurar, seleccione Iniciar remoto (Edge) o Iniciar remoto (Chrome).
Seleccione la tecla F5 para depurar y obtener una vista previa de la aplicación de Teams.

Puede agregar la funcionalidad del bot a una aplicación de extensión de mensajes fácilmente, ya que las extensiones de mensaje se basan en Bot Framework.

Los pasos siguientes le ayudan a agregar la funcionalidad del bot a una aplicación de extensión de mensaje:

Creación de una aplicación de bot mediante el kit de herramientas de Teams
Actualizar archivo de manifiesto
Adición de código de bot al proyecto

Creación de una aplicación de bot mediante el kit de herramientas de Teams

Para crear una aplicación de bot con Teams Toolkit, consulte Creación de una nueva aplicación de bot de Teams.

Actualizar archivo de manifiesto

Puede configurar la funcionalidad del bot en el appPackage/manifest.json archivo. Para obtener más información, consulte esquema de manifiesto de aplicación.

El siguiente fragmento de código es un ejemplo:

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

Adición de código de bot al proyecto

La aplicación de extensión de mensaje contiene una clase que extiende TeamsActivityHandler. Copie el código del bot configurado de la aplicación de bot en esta clase en Visual Studio Code. El código siguiente es un ejemplo de una extensión de mensaje que contiene funciones de una aplicación de bot creada en 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
     */
   }

Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.
Escriba Teams: Provision para aplicar el bicep a Azure.
Escriba Teams: Deploy para implementar el código de la aplicación de pestaña en Azure.
En Ejecutar y depurar, seleccione Iniciar remoto (Edge) o Iniciar remoto (Chrome).
Seleccione la tecla F5 para depurar y obtener una vista previa de la aplicación de Teams.

Paso siguiente

Guías paso a paso para agregar funcionalidades

Recursos adicionales

Configuración de canalizaciones CI/CD

Compartir a través de

Adición de la funcionalidad de bot a la aplicación Teams

Requisitos previos

Creación de una aplicación de bot con el kit de herramientas de Microsoft Teams

Configuración de la funcionalidad del bot en el manifiesto de aplicación

Adición de código de bot al proyecto

Configuración del entorno de depuración local

Aprovisionamiento de la aplicación en Azure

Paso siguiente

Recursos adicionales

Recursos adicionales