Compartilhar via

Adicionar a capacidade de extensão de mensagens à aplicação Teams

  • Artigo

Uma extensão de mensagem permite que os utilizadores interajam com o seu serviço Web ao compor mensagens no Microsoft Teams. Os utilizadores podem invocar o seu serviço Web para ajudar na composição de mensagens a partir da caixa de composição de mensagens ou da barra de pesquisa.

As extensões de mensagens são criadas com base na arquitetura do Bot Framework no Teams. Para obter mais informações, veja Build message extensions (Criar extensões de mensagens).

Pré-requisitos

Para configurar a capacidade de extensão de mensagens na sua aplicação, certifique-se de que são cumpridos os seguintes pré-requisitos:

Adicionar extensão de mensagem à aplicação Teams

Para adicionar uma extensão de mensagem a uma aplicação de separador, siga estes passos:

  1. Criar aplicação de extensão de mensagens com o Microsoft Teams Toolkit
  2. Configurar a extensão de mensagem no manifesto da aplicação
  3. Adicionar código de extensão de mensagem ao projeto
  4. Configurar o ambiente de depuração local
  5. Aprovisionar a sua aplicação no Azure

Criar aplicação de extensão de mensagens com o Microsoft Teams Toolkit

Para criar uma aplicação de extensão de mensagem com o Teams Toolkit, consulte Criar uma aplicação de extensão de mensagem com o Teams Toolkit.

Configurar a extensão de mensagem no manifesto da aplicação

Pode configurar a capacidade de extensão de mensagem no appPackage/manifest.json ficheiro. Para obter mais informações, veja esquema de manifesto de aplicação.

O fragmento de código seguinte é um exemplo:

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

Adicionar código de extensão de mensagem ao projeto

  1. Crie uma bot/ pasta no seu projeto de separador no Visual Studio Code. Copie o código fonte da aplicação de extensão de mensagem para a pasta . A estrutura de pastas do projeto tem o seguinte aspeto:

    |--.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. Reorganize a estrutura de pastas da seguinte forma:

    Dica

    Utilize o comando npm init -y para criar um ficheiro de raiz 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. Adicione o seguinte código à raiz 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"
},

    Observação

    Num projeto JavaScript, pode executar o projeto sem uma build pasta. Tem de remover o build:bot script e atualizar o build script para npm run build:tab.

Configurar o ambiente de depuração local

  1. Atualize .vscode/tasks.json da seguinte forma:

    1. Adicione três novas tarefas: Start local tunnel, Start bote Start frontend.
    2. Atualize a Start application matriz da dependsOn tarefa para incluir Start bot e Start frontend.
    3. Configure a opção cwd para Start bot e Start frontend. Esta ação é necessária, uma vez que moveu anteriormente o código do separador e bot para as respetivas pastas enquanto reorganizava a estrutura de pastas.
    4. Adicione Start local tunnel à Start Teams App Locally matriz da dependsOn tarefa.
    "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. teamsapp.local.yml No ficheiro:

    1. Em provision, adicione as ações botAadApp/create e botFramework/create .
    2. Em deploy, atualize o código da ação 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}}

    Para obter mais informações, veja exemplo de aplicação.

  3. Em Executar e Depurar, selecione Depurar (Edge) ou Depurar (Chrome).

  4. Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams localmente.

Aprovisionar a sua aplicação no Azure

  1. Copie a botRegistration/ pasta e adicione em infra/.

  2. Adicione o seguinte código ao azure.bicep ficheiro:

    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 garantir que os parâmetros necessários estão definidos corretamente, atualize o azure.parameters.json ficheiro com o seguinte código:

    {
"$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. teamsapp.yml No ficheiro:

    1. Em provision, adicione a ação botAadApp/create . Para obter mais informações, veja exemplo de aplicação.
    2. deploy Na secção , adicione o seguinte código:
    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. Aceda a Ver>Paleta de Comandos... ou selecione Ctrl+Shift+P.

  6. Introduza Teams: Provision para aplicar o bicep ao Azure.

  7. Introduza Teams: Deploy para implementar o código da aplicação de separador no Azure.

  8. Em Executar e Depurar, selecione Iniciar Remoto (Edge) ou Iniciar Remoto (Chrome).

  9. Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams.

Próxima etapa

Manuais de instruções para adicionar capacidades

Confira também

Configurar pipelines de CI/CD