Agregar funcionalidad de tabulación a la aplicación Teams

Artículo
12/17/2024

Las pestañas son páginas web incrustadas en Microsoft Teams. Las pestañas funcionan como etiquetas HTML iframe simples que apuntan a dominios declarados en el manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams). Puede agregar una pestaña como funcionalidad a una aplicación de Teams en un canal dentro de un equipo, chat en grupo o aplicación personal para un usuario individual. Puede incluir pestañas personalizadas con la aplicación para insertar su propio contenido web en Teams o agregar una funcionalidad específica de Teams a su contenido web. Para obtener más información, consulte pestañas de compilación para Teams.

Antes de empezar, se recomienda crear y pasar por una aplicación de pestaña. Para obtener más información, consulte Creación de una aplicación de pestaña con Teams Toolkit.

Requisitos previos

Asegúrese de que se cumplen los siguientes requisitos previos para configurar la funcionalidad de tabulación en una aplicación de Teams:

Aplicación de Teams y su archivo de manifiesto de aplicación
Cuenta de Microsoft 365 para probar la aplicación
Cuenta de Microsoft Azure

Pestaña Configurar en la aplicación Teams

Los pasos siguientes le ayudan a configurar la funcionalidad de tabulación en una aplicación de Teams:

Actualizar el manifiesto de la aplicación
Configuración del entorno de depuración local
Aprovisionamiento de una aplicación en Azure

Sugerencia

Si desarrolla una aplicación de pestaña del lado servidor, no es necesario actualizar la estructura de carpetas, el perfil de depuración o la infraestructura de bicep. Agregue nuevas rutas a la pestaña en el servicio bot y actualice el manifiesto de la aplicación en el kit de herramientas de Teams. Para obtener más información, consulte aplicación de ejemplo.

Actualizar el manifiesto de la aplicación

Para configurar la pestaña en un chat personal, chat de grupo o canal, actualice el manifest.json archivo con el código siguiente:

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

Actualice el valor de validDomains con el dominio de la pestaña.
```
"validDomains": [
    "${{TAB_DOMAIN}}"
],
```
Nota:

TAB_ENDPOINT y TAB_DOMAIN son variables integradas del kit de herramientas de Teams. Se reemplazan por el punto de conexión verdadero durante el tiempo de ejecución en función del entorno actual.

Configuración del entorno de depuración local

Incorpore el código de la aplicación de pestaña al proyecto en Visual Studio Code. Si no tiene una, puede crear una nueva aplicación de pestaña con Teams Toolkit y copiar el código fuente en el proyecto actual. De forma predeterminada, la estructura de carpetas de la aplicación de pestaña tiene el siguiente aspecto:
```
    |-- appPackage/
    |-- env/
    |-- infra/
    |-- tab/            
    |   |-- src/
    |   |   |-- app.ts
    |   |-- package.json
    |-- index.ts        
    |-- package.json
    |-- teamsapp.yml
```

Reorganizar la estructura de carpetas de la siguiente manera:

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

Actualice el código siguiente en teamsapp.yml y teamsapp.local.yml los archivos para que se alineen con la estructura de carpetas:

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

Para configurar el perfil de depuración para el proyecto de pestaña, agregue el código siguiente al tasks.json archivo:

{
    "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 obtener más información sobre cómo configurar el perfil de depuración, consulte aplicación de ejemplo.

Para permitir que el proyecto de pestaña funcione con el kit de herramientas de Teams, agregue las siguientes acciones al teamsapp.local.yml archivo:

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

Seleccione la tecla F5 para depurar la aplicación localmente.

Aprovisionamiento de una aplicación en Azure

Para crear una aplicación de pestaña del lado servidor, no es necesario actualizar los archivos bicep ni la infraestructura de Azure. Puede hospedar la aplicación de pestaña en el mismo Azure App Service que el bot.

Para aprovisionar una aplicación web estática de Azure para la aplicación de pestaña, agregue el código siguiente al azure.bicep archivo:

@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 asegurarse de que los parámetros necesarios se establecen correctamente, actualice el archivo de la azure.parameters.json siguiente manera:

{
  "$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 hospedar la aplicación de pestaña en Azure Static Web Apps, defina la acción en teamsapp.yml el azureStaticWebApps/getDeploymentToken archivo. La acción se basa en AZURE_STATIC_WEB_APPS_RESOURCE_ID, una salida de las implementaciones de bicep. Agregue el código siguiente después de la arm/deploy acción:
```
 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
   ...
```
Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.
Escriba Teams: Provision el comando para aplicar el bicep a Azure.

Para automatizar la compilación e implementación de la aplicación de pestaña, agregue las siguientes build acciones y deploy al teamsapp.yml archivo:

  - 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'

Vaya a Ver>paleta de comandos... o seleccione Ctrl+Mayús+P.
Escriba Teams: Deploy para implementar el código de la aplicación de pestaña en Azure.
En Ejecutar y depurar, seleccione Iniciar remoto (Edge) o Iniciar remoto (Chrome).
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

Compartir a través de