向 Teams 应用添加机器人功能

项目
12/17/2024

机器人（也称为聊天机器人或聊天机器人）是一种在聊天设置中响应简单命令并提供相关响应的应用。机器人通常用于各种任务，例如通知生成失败、提供天气更新、公交时间表或旅行信息。机器人交互的范围从简单的问答交换到复杂的对话。作为云应用程序，机器人可以提供对云服务和公司资源的安全和有价值的访问。有关详细信息，请参阅为 Microsoft Teams 生成机器人。

先决条件

若要将机器人配置为附加功能，请确保满足以下先决条件：

Teams 应用及其应用清单 (以前称为 Teams 应用清单) 文件
Microsoft 365 帐户来测试应用
Microsoft Azure 帐户

将机器人添加到选项卡应用
将机器人添加到消息扩展应用

以下步骤可帮助你将机器人添加到选项卡应用：

使用 Microsoft Teams 工具包创建机器人应用
在应用清单中配置机器人功能
将机器人代码添加到项目
设置本地调试环境
将应用预配到 Azure

使用 Microsoft Teams 工具包创建机器人应用

若要使用 Teams 工具包创建机器人应用，请参阅使用 Teams 工具包创建机器人应用。

在应用清单中配置机器人功能

可以在文件中配置机器人功能 appPackage/manifest.json 。有关详细信息，请参阅应用清单架构。

以下代码片段是一个示例：

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

将机器人代码添加到项目

在项目中创建一个bot/文件夹，并将机器人应用的源代码复制到 Visual Studio Code 中的文件夹中。项目的文件夹结构如下所示：

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

按如下所示重新组织文件夹结构：

提示

使用命令 npm init -y 创建根 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

将以下代码添加到根 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"
    },

注意

在 JavaScript 项目中，可以在没有文件夹的情况下 build 运行项目。必须删除脚本并将 build:bot 脚本更新 build 为 npm run build:tab。

设置本地调试环境

更新 .vscode/tasks.json 如下：

添加三个新任务： Start local tunnel、 Start bot和 Start frontend。
更新 Start application 任务的 dependsOn 数组以包括 Start bot 和 Start frontend。
cwd配置 Start bot 和 Start frontend的选项。需要此操作，因为之前已在重新组织文件夹结构时将选项卡和机器人的代码移到其各自的文件夹中。
将添加到Start local tunnelStart Teams App Locally任务的 dependsOn 数组。

    "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 文件下：

在下 provision，添加 botAadApp/create 和 botFramework/create 操作。
在下 deploy，更新操作的代码 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}}

有关详细信息，请参阅示例应用。

在 “运行和调试”下，选择“ 调试 (Edge) ”或“调试 (Chrome) ”。
选择 F5 键在本地调试和预览 Teams 应用。

将应用预配到 Azure

将 botRegistration/ 文件夹从机器人复制到 infra/。

将以下代码添加到 azure.bicep 文件：

 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

若要确保正确设置必要的参数，请使用 azure.parameters.json 以下代码更新文件：

 {
 "$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 文件下：

在下 provision添加 botAadApp/create 操作。有关详细信息，请参阅示例应用。
在 deploy 部分下，添加以下代码：

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

转到 “查看>命令面板...” 或选择 Ctrl+Shift+P。
输入 Teams: Provision 以将 bicep 应用到 Azure。
输入 Teams: Deploy 以将选项卡应用代码部署到 Azure。
在 “运行和调试”下，选择“ 启动远程 (Edge) ”或 “启动远程 (Chrome) ”。
选择 F5 键以调试和预览 Teams 应用。

可以将机器人功能轻松添加到消息扩展应用，因为消息扩展是在 Bot Framework 上构建的。

以下步骤可帮助你将机器人功能添加到消息扩展应用：

使用 Teams 工具包创建机器人应用
更新清单文件
将机器人代码添加到项目

使用 Teams 工具包创建机器人应用

若要使用 Teams 工具包创建机器人应用，请参阅创建新的 Teams 机器人应用。

更新清单文件

可以在文件中配置机器人功能 appPackage/manifest.json 。有关详细信息，请参阅应用清单架构。

以下代码片段是一个示例：

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

将机器人代码添加到项目

消息扩展应用包含扩展的 TeamsActivityHandler类。在 Visual Studio Code 中将配置的机器人代码从机器人应用复制到此类中。以下代码是消息扩展的示例，其中包含在 Teams 工具包中创建的机器人应用中的函数：

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

转到 “查看>命令面板...” 或选择 Ctrl+Shift+P。
输入 Teams: Provision 以将 bicep 应用到 Azure。
输入 Teams: Deploy 以将选项卡应用代码部署到 Azure。
在 “运行和调试”下，选择“ 启动远程 (Edge) ”或 “启动远程 (Chrome) ”。
选择 F5 键以调试和预览 Teams 应用。

后续步骤

添加功能的操作指南

另请参阅

设置 CI/CD 管道

通过

向 Teams 应用添加机器人功能

先决条件

使用 Microsoft Teams 工具包创建机器人应用

在应用清单中配置机器人功能

将机器人代码添加到项目

设置本地调试环境

将应用预配到 Azure

使用 Teams 工具包创建机器人应用

更新清单文件

将机器人代码添加到项目

后续步骤

另请参阅

其他资源