Ajouter une fonctionnalité d’extension de message à l’application Teams

Une extension de message permet aux utilisateurs d’interagir avec votre service web lors de la composition de messages dans Microsoft Teams. Les utilisateurs peuvent appeler votre service web pour faciliter la composition des messages à partir de la zone de composition de message ou de la barre de recherche.

Les extensions de message reposent sur l’architecture Bot Framework dans Teams. Pour plus d’informations, consultez Extensions de message de génération.

Configuration requise

Pour configurer la fonctionnalité d’extension de message dans votre application, vérifiez que les conditions préalables suivantes sont remplies :

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

Ajouter une extension de message à l’application Teams

Ajouter une extension de message à l’application onglet

Pour ajouter une extension de message à une application d’onglet, procédez comme suit :

1. Créer une application d’extension de message à l’aide d’Agents Toolkit
2. Configurer l’extension de message dans le manifeste de l’application
3. Ajouter du code d’extension de message à votre projet
4. Configurer l’environnement de débogage local
5. Provisionner votre application sur Azure

Créer une application d’extension de message à l’aide d’Agents Toolkit

Pour créer une application d’extension de message avec Agents Toolkit (précédemment appelé Teams Toolkit), consultez Créer une application d’extension de message avec Agents Toolkit.

Configurer l’extension de message dans le manifeste de l’application

Vous pouvez configurer la fonctionnalité d’extension de message 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 :

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

Ajouter du code d’extension de message à votre projet

1. Créez un bot/ dossier dans votre projet d’onglet dans Visual Studio Code. Copiez le code source de l’application d’extension de message dans le dossier . La structure de dossiers de votre projet se présente comme suit :

   |--.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
   |--m365agents.local.yml
   |--m365agents.yml
   

2. 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/            <!--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-->
   |--m365agents.local.yml
   |--m365agents.yml
   

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

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

   1. Ajoutez trois nouvelles tâches : Start local tunnel, Start botet Start frontend.
   2. Mettez à jour le Start application tableau de la dependsOn tâche pour inclure Start bot et Start frontend.
   3. 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.
   4. 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"
            },
   ]
   

2. Sous le m365agents.local.yml fichier :

   1. Sous provision, ajoutez les botAadApp/create actions et botFramework/create .
   2. 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.

3. Sous Exécuter et déboguer, sélectionnez Déboguer (Edge) ou Déboguer (Chrome).

4. Sélectionnez la touche F5 pour déboguer et afficher un aperçu local de votre application Teams.

Provisionner votre application sur Azure

1. Copiez le botRegistration/ dossier et ajoutez sous infra/.

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

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

4. Sous le m365agents.yml fichier :

   1. Sous provision, ajoutez l’action botAadApp/create . Pour plus d’informations, consultez Exemple d’application.
   2. 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}}
   

5. Accédez à Afficher>la palette de commandes... ou sélectionnez Ctrl+Maj+P.

6. Entrez Teams: Provision pour appliquer le bicep à Azure.

7. Entrez Teams: Deploy pour déployer le code de votre application d’onglet sur Azure.

8. Sous Exécuter et déboguer, sélectionnez Lancer à distance (Edge) ou Lancer à distance (Chrome).

9. Sélectionnez la touche F5 pour déboguer et afficher un aperçu de votre application Teams.

Ajouter une extension de message à l’application bot

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

Pour ajouter une extension de message à une application de bot, procédez comme suit :

1. Créer une application d’extension de message à l’aide d’Agents Toolkit
2. Configurer l’extension de message dans le manifeste de l’application
3. Ajouter le code d’extension de message au projet

Créer une extension de message à l’aide d’Agents Toolkit

Pour créer une application d’extension de message, consultez Créer une application d’extension de message avec agents Toolkit.

Configurer l’extension de message dans le manifeste de l’application

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

L’extrait de code suivant est un exemple :

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

Ajouter le code d’extension de message au projet

1. Votre application de bot contient une classe qui étend TeamsActivityHandler. Copiez vos fonctions d’extension de message à partir de l’application d’extension de message dans cette classe dans Visual Studio Code. Le code suivant est un exemple de bot qui contient des fonctions d’une application d’extension de message créée dans Agents 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. Accédez à Afficher>la palette de commandes... ou sélectionnez Ctrl+Maj+P.

3. Entrez Teams: Provision pour appliquer le bicep à Azure.

4. Entrez Teams: Deploy pour déployer le code de votre application d’onglet sur Azure.

5. Sous Exécuter et déboguer, sélectionnez Lancer à distance (Edge) ou Lancer à distance (Chrome).

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