Ajouter une fonctionnalité de bot à l’application Teams

Article
12/17/2024

Un bot, également appelé chatbot ou bot conversationnel, est une application qui répond à des commandes simples dans un paramètre de conversation, fournissant des réponses pertinentes. Les bots sont couramment utilisés pour diverses tâches, telles que la notification des défaillances de build, la fourniture de mises à jour météorologiques, les horaires de bus ou les informations de voyage. Les interactions de bot peuvent aller de simples échanges de questions-réponses à des conversations complexes. En tant qu’application cloud, un bot peut offrir un accès sécurisé et précieux aux services cloud et aux ressources d’entreprise. Pour plus d’informations, consultez Générer des bots pour Microsoft Teams.

Configuration requise

Pour configurer le bot en tant que fonctionnalité supplémentaire, vérifiez que les conditions préalables suivantes sont remplies :

Application Teams et son fichier de manifeste d’application (précédemment appelé manifeste d’application Teams)
Compte Microsoft 365 pour tester l’application
Compte Microsoft Azure

Ajouter un bot à une application d’onglet
Ajouter un bot à l’application d’extension de message

Les étapes suivantes vous aident à ajouter un bot à une application d’onglet :

Créer une application bot à l’aide du Kit de ressources Microsoft Teams
Configurer la fonctionnalité de bot dans le manifeste de l’application
Ajouter du code de bot à votre projet
Configurer l’environnement de débogage local
Provisionner l’application sur Azure

Créer une application bot à l’aide du Kit de ressources Microsoft Teams

Pour créer une application bot à l’aide de Teams Toolkit, consultez Créer une application bot avec teams Toolkit.

Configurer la fonctionnalité de bot dans le manifeste de l’application

Vous pouvez configurer la fonctionnalité de bot dans le appPackage/manifest.json fichier . Pour plus d’informations, consultez Schéma de manifeste d’application.

L’extrait de code suivant est un exemple :

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

Ajouter du code de bot à votre projet

Créez un bot/ dossier dans votre projet et copiez le code source de l’application bot dans le dossier de Visual Studio Code. La structure de dossiers de votre projet se présente comme suit :

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

Réorganisez la structure des dossiers comme suit :

Conseil

Utilisez la commande npm init -y pour créer un fichier racine 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

Ajoutez le code suivant à votre racine 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"
    },

Remarque

Dans un projet JavaScript, vous pouvez exécuter le projet sans build dossier. Vous devez supprimer le build:bot script et mettre à jour le build script vers npm run build:tab.

Configurer l’environnement de débogage local

Mettez à jour .vscode/tasks.json comme suit :

Ajoutez trois nouvelles tâches : Start local tunnel, Start botet Start frontend.
Mettez à jour le Start application tableau de la dependsOn tâche pour inclure Start bot et Start frontend.
Configurez l’option cwd pour Start bot et Start frontend. Cette action est nécessaire, car vous avez précédemment déplacé le code de l’onglet et du bot dans leurs dossiers respectifs lors de la réorganisation de la structure des dossiers.
Ajouter Start local tunnel au tableau de la Start Teams App LocallydependsOn tâche.

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

Sous le teamsapp.local.yml fichier :

Sous provision, ajoutez les botAadApp/create actions et botFramework/create .
Sous deploy, mettez à jour le code de l’action 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}}

Pour plus d’informations, consultez Exemple d’application.

Sous Exécuter et déboguer, sélectionnez Déboguer (Edge) ou Déboguer (Chrome).
Sélectionnez la touche F5 pour déboguer et afficher un aperçu local de votre application Teams.

Provisionner l’application sur Azure

Copiez le botRegistration/ dossier du bot vers infra/.

Ajoutez le code suivant au azure.bicep fichier :

 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

Pour vous assurer que les paramètres nécessaires sont correctement définis, mettez à jour le azure.parameters.json fichier avec le code suivant :

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

Sous le teamsapp.yml fichier :

Sous provision, ajoutez l’action botAadApp/create . Pour plus d’informations, consultez Exemple d’application.
Sous la deploy section , ajoutez le code suivant :

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

Accédez à Afficher>la palette de commandes... ou sélectionnez Ctrl+Maj+P.
Entrez Teams: Provision pour appliquer le bicep à Azure.
Entrez Teams: Deploy pour déployer le code de votre application d’onglet sur Azure.
Sous Exécuter et déboguer, sélectionnez Lancer à distance (Edge) ou Lancer à distance (Chrome).
Sélectionnez la touche F5 pour déboguer et afficher un aperçu de votre application Teams.

Vous pouvez facilement ajouter la fonctionnalité de bot à une application d’extension de message, car les extensions de message sont basées sur Bot Framework.

Les étapes suivantes vous aident à ajouter la fonctionnalité de bot à une application d’extension de message :

Créer une application bot à l’aide du kit de ressources Teams
Mettre à jour le fichier manifeste
Ajouter du code de bot au projet

Créer une application bot à l’aide du kit de ressources Teams

Pour créer une application bot avec Teams Toolkit, consultez Créer une application de bot Teams.

Mettre à jour le fichier manifeste

Vous pouvez configurer la fonctionnalité de bot dans le appPackage/manifest.json fichier . Pour plus d’informations, consultez Schéma de manifeste d’application.

L’extrait de code suivant est un exemple :

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

Ajouter du code de bot au projet

Votre application d’extension de message contient une classe qui étend TeamsActivityHandler. Copiez le code de votre bot configuré à partir de l’application bot dans cette classe dans Visual Studio Code. Le code suivant est un exemple d’extension de message qui contient des fonctions d’une application bot créée dans 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
     */
   }

Accédez à Afficher>la palette de commandes... ou sélectionnez Ctrl+Maj+P.
Entrez Teams: Provision pour appliquer le bicep à Azure.
Entrez Teams: Deploy pour déployer le code de votre application d’onglet sur Azure.
Sous Exécuter et déboguer, sélectionnez Lancer à distance (Edge) ou Lancer à distance (Chrome).
Sélectionnez la touche F5 pour déboguer et afficher un aperçu de votre application Teams.

Étape suivante

Guides pratiques pour l’ajout de fonctionnalités

Voir aussi

Mettre en place des pipelines CI/CD

Partager via