Adición de la funcionalidad de extensión de mensaje a la aplicación Teams

Una extensión de mensaje permite a los usuarios interactuar con el servicio web al redactar mensajes en Microsoft Teams. Los usuarios pueden invocar el servicio web para ayudar a la composición de mensajes desde el cuadro de redacción de mensajes o desde la barra de búsqueda.

Las extensiones de mensaje se basan en la arquitectura de Bot Framework en Teams. Para obtener más información, consulte Compilación de extensiones de mensajes.

Requisitos previos

Para configurar la funcionalidad de extensión de mensaje en la aplicación, asegúrese de que se cumplen los siguientes requisitos previos:

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

Agregar extensión de mensaje a la aplicación Teams

Agregar extensión de mensaje a la aplicación de pestaña

Para agregar una extensión de mensaje a una aplicación de pestaña, siga estos pasos:

1. Creación de una aplicación de extensión de mensaje mediante microsoft Teams Toolkit
2. Configuración de la extensión de mensaje en el manifiesto de la aplicación
3. Agregar código de extensión de mensaje al proyecto
4. Configuración del entorno de depuración local
5. Aprovisionamiento de la aplicación en Azure

Creación de una aplicación de extensión de mensaje mediante microsoft Teams Toolkit

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

Configuración de la extensión de mensaje en el manifiesto de la aplicación

Puede configurar la funcionalidad de extensión de mensaje 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:

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
               ],
               "description": "Test command to run query",
               "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
                }
            }
        ]
    }
]

Agregar código de extensión de mensaje al proyecto

1. Cree una bot/ carpeta en el proyecto de pestaña en Visual Studio Code. Copie el código fuente de la aplicación de extensión de mensaje en la carpeta . La estructura de carpetas del proyecto tiene el siguiente aspecto:

   |--.vscode/
   |--appPackage/
   |--env/
   |--infra/
   |--public/
   |--bot/           <!--message extension source code-->
   |   |--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
   

2. 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/            <!--message extension source code-->
      |--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
   

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

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

   1. Agregue tres nuevas tareas: Start local tunnel, Start boty Start frontend.
   2. Actualice la matriz de la Start applicationdependsOn tarea para incluir Start bot y Start frontend.
   3. 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.
   4. 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"
            },
   ]
   

2. En el teamsapp.local.yml archivo:

   1. En provision, agregue las botAadApp/create acciones y botFramework/create .
   2. 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.

3. En Ejecutar y depurar, seleccione Depurar (Edge) o Depurar (Chrome).

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

1. Copie la botRegistration/ carpeta y agregue en infra/.

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

3. 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}}"
     }
   }
   

4. En el teamsapp.yml archivo:

   1. En provision, agregue la botAadApp/create acción. Para obtener más información, consulte aplicación de ejemplo.
   2. 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}}
   

5. Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.

6. Escriba Teams: Provision para aplicar el bicep a Azure.

7. Escriba Teams: Deploy para implementar el código de la aplicación de pestaña en Azure.

8. En Ejecutar y depurar, seleccione Iniciar remoto (Edge) o Iniciar remoto (Chrome).

9. Seleccione la tecla F5 para depurar y obtener una vista previa de la aplicación de Teams.

Adición de la extensión de mensaje a la aplicación bot

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

Para agregar una extensión de mensaje a una aplicación de bot, siga estos pasos:

1. Creación de una aplicación de extensión de mensaje mediante el kit de herramientas de Teams
2. Configuración de la extensión de mensaje en el manifiesto de la aplicación
3. Agregar código de extensión de mensaje al proyecto

Creación de una extensión de mensaje mediante el kit de herramientas de Teams

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

Configuración de la extensión de mensaje en el manifiesto de la aplicación

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

El siguiente fragmento de código es un ejemplo:

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                   {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
                ],
                "description": "Test command to run query",
                "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
               }
            }
        ]
    }
]

Agregar código de extensión de mensaje al proyecto

1. La aplicación de bot contiene una clase que extiende TeamsActivityHandler. Copie las funciones de extensión de mensaje de la aplicación de extensión de mensaje en esta clase en Visual Studio Code. El código siguiente es un ejemplo de un bot que contiene funciones de una aplicación de extensión de mensaje creada en teams Toolkit:

     class YourHandler extends TeamsActivityHandler {
     /**
      * your own code
      */
     //message extension code
     // Action.
     public async handleTeamsMessagingExtensionSubmitAction(
       context: TurnContext,
       action: any
     ): Promise<any> {}
     // Search.
     public async handleTeamsMessagingExtensionQuery(
       context: TurnContext,
       query: any
     ): Promise<any> {}
     public async handleTeamsMessagingExtensionSelectItem(
       context: TurnContext,
       obj: any
     ): Promise<any> {}
     // Link Unfurling.
     public async handleTeamsAppBasedLinkQuery(
       context: TurnContext,
       query: any
     ): Promise<any> {}
   }
   async function createCardCommand(
     context: TurnContext,
     action: MessagingExtensionAction
   ): Promise<MessagingExtensionResponse> {}
   async function shareMessageCommand(
     context: TurnContext,
     action: MessagingExtensionAction
   ): Promise<MessagingExtensionResponse> {}
   

2. Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.

3. Escriba Teams: Provision para aplicar el bicep a Azure.

4. Escriba Teams: Deploy para implementar el código de la aplicación de pestaña en Azure.

5. En Ejecutar y depurar, seleccione Iniciar remoto (Edge) o Iniciar remoto (Chrome).

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