Partager via

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

  • Article

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 :

Ajouter une extension de message à l’application Teams

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 du Kit de ressources Microsoft Teams
  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 du Kit de ressources Microsoft Teams

Pour créer une application d’extension de message avec teams Toolkit, consultez Créer une application d’extension de message avec teams 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
|--teamsapp.local.yml
|--teamsapp.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-->
|--teamsapp.local.yml
|--teamsapp.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 teamsapp.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 teamsapp.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.

Étape suivante

Guides pratiques pour l’ajout de fonctionnalités

Voir aussi

Mettre en place des pipelines CI/CD