Adicionar capacidade de separador à aplicação Teams

Artigo
12/17/2024

Os separadores são páginas Web incorporadas no Microsoft Teams. Os separadores funcionam como etiquetas HTML iframe simples que apontam para domínios declarados no manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams). Pode adicionar um separador como capacidade a uma aplicação do Teams num canal dentro de uma equipa, chat de grupo ou aplicação pessoal para um utilizador individual. Você pode incluir guias personalizadas com seu aplicativo para inserir seu próprio conteúdo da Web no Teams ou adicionar funcionalidades específicas do Teams ao conteúdo da Web. Para obter mais informações, consulte Criar separadores para o Teams.

Antes de começar, recomendamos que crie e percorra uma aplicação de separador. Para obter mais informações, consulte Criar aplicação de separador com o Teams Toolkit.

Pré-requisitos

Certifique-se de que são cumpridos os seguintes pré-requisitos para configurar a capacidade de separador numa aplicação do Teams:

Aplicação Teams e o respetivo ficheiro de manifesto de aplicação
Conta do Microsoft 365 para testar a aplicação
Conta do Microsoft Azure

Separador Configurar na aplicação Teams

Os passos seguintes ajudam-no a configurar a capacidade de separador numa aplicação do Teams:

Atualizar manifesto do aplicativo
Configurar o ambiente de depuração local
Aprovisionar aplicação no Azure

Dica

Se desenvolver uma aplicação de separador do lado do servidor, não precisa de atualizar a estrutura de pastas, o perfil de depuração ou a infraestrutura do bíceps. Adicione novas rotas ao separador no seu serviço de bot e atualize o manifesto da aplicação no Teams Toolkit. Para obter mais informações, veja exemplo de aplicação.

Atualizar manifesto do aplicativo

Para configurar o separador numa conversa pessoal, chat de grupo ou canal, atualize o manifest.json ficheiro com o seguinte código:

  "staticTabs": [
      {
          "entityId": "index",
          "name": "Personal Tab",
          "contentUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
          "websiteUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
          "scopes": [
              "personal",
              "groupChat",
              "team"
          ]
      }
  ],

Atualize o valor de validDomains com o domínio do separador.
```
"validDomains": [
    "${{TAB_DOMAIN}}"
],
```
Observação

TAB_ENDPOINT e TAB_DOMAIN são variáveis incorporadas do Teams Toolkit. São substituídos pelo ponto final verdadeiro durante o runtime com base no seu ambiente atual.

Configurar o ambiente de depuração local

Introduza o código da aplicação de separador no seu projeto no Visual Studio Code. Se não tiver uma, pode criar uma nova aplicação de separador com o Teams Toolkit e copiar o código fonte para o seu projeto atual. Por predefinição, a estrutura de pastas da sua aplicação de separador tem o seguinte aspeto:
```
    |-- appPackage/
    |-- env/
    |-- infra/
    |-- tab/            
    |   |-- src/
    |   |   |-- app.ts
    |   |-- package.json
    |-- index.ts        
    |-- package.json
    |-- teamsapp.yml
```

Reorganize a estrutura de pastas da seguinte forma:

    |-- appPackage/
    |-- infra/
    |-- tab/           <!--tab app source code-->
    |   |-- src/
    |   |   |-- app.ts
    |   |-- package.json
    |-- bot/            <!--move your current source code to a new sub folder-->
    |   |-- index.ts
    |   |-- package.json
    |-- teamsapp.yml

Atualize o seguinte código em teamsapp.yml e teamsapp.local.yml ficheiros para alinhar com a estrutura de pastas:

    deploy:
      # Run npm command
      - uses: cli/runNpmCommand
        with:
          args: install --no-audit
          workingDirectory: ./bot

Para configurar o perfil de depuração para o projeto de separador, adicione o seguinte código ao tasks.json ficheiro:

{
    "label": "Start application",
    "dependsOn": [
        "Start bot",
        "Start frontend"
    ]
},
{
    "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": "Compiled|Failed|compiled|failed"
        }
    }
}

Para obter mais informações sobre como configurar o perfil de depuração, veja exemplo de aplicação.

Para permitir que o seu projeto de separador funcione com o Teams Toolkit, adicione as seguintes ações ao teamsapp.local.yml ficheiro:

provision:
  - uses: script # Set TAB_DOMAIN for local launch
    name: Set TAB_DOMAIN for local launch
    with:
      run: echo "::set-output TAB_DOMAIN=localhost:53000"
  - uses: script # Set TAB_ENDPOINT for local launch
    name: Set TAB_ENDPOINT for local launch
    with:
      run: echo "::set-output TAB_ENDPOINT=https://localhost:53000"
deploy:
  - uses: devTool/install # Install development tool(s)
    with:
      devCert:
        trust: true
    writeToEnvironmentFile: # Write the information of installed development tool(s) into environment file for the specified environment variable(s).
      sslCertFile: SSL_CRT_FILE
      sslKeyFile: SSL_KEY_FILE
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: install --no-audit
      workingDirectory: ./tab
  - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables for tab
    with:
      target: ./tab/.localConfigs
      envs:
        BROWSER: none
        HTTPS: true
        PORT: 53000
        SSL_CRT_FILE: ${{SSL_CRT_FILE}}
        SSL_KEY_FILE: ${{SSL_KEY_FILE}}

Selecione a chave F5 para depurar a sua aplicação localmente.

Aprovisionar aplicação no Azure

Para criar uma aplicação de separador do lado do servidor, não precisa de atualizar os ficheiros bicep ou a infraestrutura do Azure. Pode alojar a sua aplicação de separador na mesma Serviço de Aplicativo do Azure que o bot.

Para aprovisionar uma Aplicação Web Estática do Azure para a sua aplicação de separador, adicione o seguinte código ao ficheiro azure.bicep :

@maxLength(20)
@minLength(4)
param resourceBaseName string
param storageSku string
param staticWebAppName string = resourceBaseName

// Azure Static Web Apps that hosts your static web site
resource swa 'Microsoft.Web/staticSites@2022-09-01' = {
  name: staticWebAppName
  // SWA do not need location setting
  location: 'centralus'
  sku: {
    name: staticWebAppSku
    tier: staticWebAppSku
  }
  properties: {}
}
var siteDomain = swa.properties.defaultHostname

output AZURE_STATIC_WEB_APPS_RESOURCE_ID string = swa.id
output TAB_DOMAIN string = siteDomain
output TAB_ENDPOINT string = 'https://${siteDomain}'

Para garantir que os parâmetros necessários estão definidos corretamente, atualize o ficheiro da azure.parameters.json seguinte forma:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resourceBaseName": {
      "value": "helloworld${{RESOURCE_SUFFIX}}"
    },
    "storageSku": {
      "value": "Free"
    },
  }
}

Para alojar a sua aplicação de separador no Aplicativos Web Estáticos do Azure, defina a ação azureStaticWebApps/getDeploymentToken no seu teamsapp.yml ficheiro. A ação depende do AZURE_STATIC_WEB_APPS_RESOURCE_ID, uma saída das implementações do bíceps. Adicione o seguinte código após a ação arm/deploy :
```
 provision:
   ...
   - uses: arm/deploy
     ...
   # Add this action
   - uses: azureStaticWebApps/getDeploymentToken
     with:
       resourceId: ${{AZURE_STATIC_WEB_APPS_RESOURCE_ID}}
       writeToEnvironmentFile:
         deploymentToken: SECRET_TAB_SWA_DEPLOYMENT_TOKEN
   ...
```
Aceda a Ver>Paleta de Comandos... ou selecione Ctrl+Shift+P.
Introduza Teams: Provision o comando para aplicar o bicep ao Azure.

Para automatizar a compilação e implementação da sua aplicação de separador, adicione o seguinte build e deploy as ações ao seu teamsapp.yml ficheiro:

  - uses: cli/runNpmCommand # Run npm command
    with:
      args: install
      workingDirectory: ./tab
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: run build
      workingDirectory: ./tab
  # Deploy bits to Azure Storage Static Website
 - uses: cli/runNpxCommand
     name: deploy to Azure Static Web Apps
     with:
       args: '@azure/static-web-apps-cli deploy ./build -d ${{SECRET_TAB_SWA_DEPLOYMENT_TOKEN}} --env production'

Aceda a Ver>Paleta de Comandos... ou selecione Ctrl+Shift+P.
Introduza Teams: Deploy para implementar o código da aplicação de separador no Azure.
Em Executar e Depurar, selecione Iniciar Remoto (Edge) ou Iniciar Remoto (Chrome).
Selecione a chave F5 para depurar e pré-visualizar a sua aplicação Teams.

Próxima etapa

Manuais de instruções para adicionar capacidades

Partilhar via