Introducción a la plataforma de Microsoft Teams con Node.js y app Studio

La plataforma de desarrolladores de Microsoft Teams facilita la tarea de ampliar Teams e integrar sus propias aplicaciones y servicios sin problemas en el área de trabajo de Microsoft Teams. A continuación, estas aplicaciones pueden distribuirse a su empresa o a equipos de todo el mundo.

Para ampliar Microsoft Teams, debe crear una aplicación de Microsoft Teams. Una aplicación de Microsoft Teams es una aplicación web que hospeda. A continuación, esta aplicación se puede integrar en el área de trabajo del usuario en Teams.

Preparar el entorno de desarrollo

Lo primero que debe hacer es preparar el entorno de desarrollo. Deberá asegurarse de que la carga de aplicaciones personalizada esté habilitada para la organización de Office 365 en la que desea crear la aplicación. Si necesita un inquilino de desarrollo dedicado, puede registrarse para el programa de desarrolladores de Office 365. Para obtener más información, vea configurar el entorno de desarrollo.

Descargar y hospedar la aplicación

Siga estos pasos para descargar y hospedar una aplicación "Hola a todos" sencilla en Microsoft Teams.

Obtener requisitos previos

Para completar este tutorial, necesitará las siguientes herramientas. Si todavía no los tiene, puede instalarlas desde estos vínculos.

Si ve opciones para agregar git , node , npm y code a la ruta de acceso durante la instalación, elija esta opción. Será útil.

Compruebe que las herramientas están disponibles al ejecutar lo siguiente en una ventana de terminal:

Nota

Use la ventana de terminal que le resulte más cómoda en su plataforma. En estos ejemplos se usa Bash (que se incluye en Git), pero estos scripts se ejecutarán en la mayoría de las plataformas.

$ git --version
git version 2.19.0.windows.1

$ node -v
v8.9.3

$ npm -v
5.5.1

$ gulp -v
CLI version 2.3.0
Local version 4.0.2

Es posible que tenga una versión diferente de estas aplicaciones. Esto no debería ser un problema, excepto para Gulp. Para Gulp tendrá que usar la versión 4.0.0 o posterior.

Si no tiene Gulp instalado (o tiene instalada una versión incorrecta), hágalo ahora ejecutando npm install gulp en la ventana de terminal.

Si ha instalado Visual Studio Code, puede comprobar la instalación ejecutando:

code --version
1.28.2
929bacba01ef658b873545e26034d1a8067445e9

Puede seguir usando esta ventana de terminal para ejecutar los comandos que se indican a continuación en este tutorial.

Descargar el ejemplo

Hemos proporcionado un sencillo Hola a todos. muestra que le ayuda a empezar. En una ventana de terminal, ejecute el siguiente comando para clonar el repositorio de muestra en el equipo local:

git clone https://github.com/OfficeDev/msteams-samples-hello-world-nodejs.git

Sugerencia

Puede bifurcar este repositorio si desea modificar y proteger los cambios en el repositorio de github para futuras referencias.

Compilar y ejecutar el ejemplo

Una vez que se clona el repositorio, cambie al directorio que contiene el ejemplo:

cd msteams-samples-hello-world-nodejs

Para poder compilar el ejemplo, debe instalar todas sus dependencias. Ejecute el siguiente comando para hacerlo:

npm install

Debe ver un conjunto de dependencias que se van a instalar. Una vez que hayan finalizado, puede ejecutar la aplicación:

npm start

Cuando se inicia la aplicación Hello World, se muestra App started listening on port 3333 en la ventana de terminal.

Nota

Si ve que aparece un número de puerto diferente en el mensaje anterior, es porque tiene establecida una variable de entorno PORT. Puede seguir usando ese puerto o cambiar la variable de entorno a 3333.

En este punto, puede abrir una ventana del explorador y navegar a las siguientes direcciones URL para comprobar que todas las direcciones URL de la aplicación se cargan:

Hospedar la aplicación de ejemplo

Recuerde que las aplicaciones de Microsoft Teams son aplicaciones web que exponen una o más capacidades. Para que la plataforma de Microsoft Teams cargue la aplicación, la aplicación debe ser accesible desde Internet. Para hacer que la aplicación sea accesible desde Internet, debe hospedar la aplicación.

Para las pruebas locales, puede ejecutar la aplicación en el equipo local y crear un túnel con un punto de conexión Web. ngrok es una herramienta gratuita que le permite hacer justamente eso. Con ngrok puede obtener una dirección web como https://d0ac14a5.ngrok.io (esta dirección URL es solo un ejemplo). Puede Descargar e instalar ngrok para su entorno. Asegúrese de agregarlo a una ubicación en el PATH .

Una vez instalado, puede abrir una nueva ventana de terminal y ejecutar el siguiente comando para crear un túnel. En el ejemplo se usa el puerto 3333, por lo que debe asegurarse de especificarlo aquí.

ngrok http 3333 -host-header=localhost:3333

Ngrok escuchará solicitudes de Internet y las enrutará a la aplicación que se ejecuta en el puerto 3333. Para comprobarlo, abra el explorador y vaya a https://d0ac14a5.ngrok.io/hello para cargar la página Hello de la aplicación. Asegúrese de usar la dirección de reenvío que muestra ngrok en la sesión de consola en lugar de esta dirección URL.

Nota

Si ha usado un puerto diferente en el paso de compilación y ejecutar anterior, asegúrese de usar el mismo número de puerto para configurar el túnel ngrok .

Sugerencia

Es buena idea ejecutar ngrok en una ventana de terminal diferente para mantenerla en ejecución sin interferir con la aplicación de nodo que, posteriormente, se debe detener, volver a crear y volver a ejecutar. La sesión de ngrok devolverá información de depuración útil en esta ventana.

Hay una versión de pago de ngrok que permite nombres persistentes. Si usa la versión gratuita, la aplicación solo estará disponible durante la sesión actual en el equipo de desarrollo. Si el equipo está apagado o entra en suspensión, el servicio dejará de estar disponible. Recuerde esto cuando comparta la aplicación para que la prueben otros usuarios. Si tiene que reiniciar el servicio, devolverá una nueva dirección y tendrá que actualizar todos los sitios que usen esa dirección.

Recuerde que anote la dirección URL de la aplicación, ya que la necesitará más adelante cuando registre la aplicación con Teams mediante App Studio. El Bloc de notas funciona bien para este propósito.

Implementar la aplicación en Microsoft Teams

En este punto, tiene una aplicación hospedada en Internet, pero todavía no tiene ninguna manera de indicar a teams dónde buscarla, o incluso qué se llama a la aplicación. Para ello, ahora tiene que crear un paquete de la aplicación. Esto es algo más que un archivo de texto que contiene el manifiesto de la aplicación y algunos iconos que usará el cliente de Microsoft Teams para mostrar y marcar correctamente la aplicación. Puede crear manualmente este paquete de la aplicación o puede usar App Studio, una herramienta que se ejecuta en Microsoft teams que simplificará el proceso de registro de la aplicación. App Studio es la forma recomendada de crear y actualizar el paquete de la aplicación.

Para cualquiera de los dos métodos, necesitará lo siguiente:

  • La dirección URL en la que se puede encontrar la aplicación en Internet.
  • Iconos que los equipos usarán para personalizar la aplicación. El ejemplo incluye iconos de marcador de posición ubicados en "src\static\images. App Studio también proporcionará los iconos predeterminados, si es necesario.

Usar App Studio para actualizar el paquete de la aplicación

App Studio es una aplicación de Microsoft teams que se puede instalar desde la tienda Teams. Simplifica la creación y el registro de una aplicación.

Para instalar App Studio en Teams, haga clic en el icono App Store situado en la parte inferior de la barra izquierda y busque App Studio.

Finding App Studio in the Store View

Una vez que encuentre el icono de App Studio, haga clic en él y elija instalar en el cuadro de diálogo que aparece.

Installing App Studio

Una vez instalado App Studio, haga clic en la pestaña del editor de manifiestos para empezar a crear el paquete de la aplicación para la aplicación de Teams.

App Studio

El ejemplo incluye su propio manifiesto predefinido y está diseñado para compilar un paquete de la aplicación cuando se crea el proyecto. En .NET esto se hace en Visual Studio y en el nodo JS esto se hace escribiendo gulp en la línea de comandos en el directorio raíz del proyecto.

$ gulp
[13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
[13:39:27] Starting 'clean'...
[13:39:27] Starting 'generate-manifest'...
[13:39:27] Finished 'generate-manifest' after 11 ms
[13:39:27] Finished 'clean' after 21 ms
[13:39:27] Starting 'default'...
Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 μs

El nombre del paquete de la aplicación generado es helloworldapp.zip. Puede buscar este archivo si la ubicación no está clara en la herramienta que está usando.

En la siguiente parte de este tutorial, va a modificar este paquete de la aplicación seleccionando el icono importar una aplicación existente en el editor de manifiestos.

Importing an existing app

Una vez que se ha importado el paquete de la aplicación, App Studio debería tener el siguiente aspecto:

Importing the app package

Haga clic en el icono de la aplicación recién importada, Hello World.

Newly imported app view

Hay una lista de pasos en el lado izquierdo del editor de manifiestos y, a la derecha, una lista de propiedades que deben rellenarse para cada uno de estos pasos. Desde que empezó con una aplicación de muestra, gran parte de la información ya se ha rellenado. Los pasos siguientes le guiarán por el cambio de las partes que todavía deben actualizarse.

Detalles de la aplicación

Haga clic en la entrada detalles de la aplicación en detalles. Haga clic en el botón generar para crear un nuevo identificador de aplicación.

El nuevo identificador de la aplicación debe tener un aspecto similar al siguiente: 2322041b-72bf-459d-b107-f4f335bc35bd .

Mire el resto de los detalles de la aplicación en el panel de la derecha y familiarícese con algunas de las entradas, como información de desarrolladores y Personalización de marca. Estas secciones son importantes si está escribiendo una nueva aplicación para la distribución.

Capacidades: pestañas

Las pestañas se encuentran entre los elementos más simples para agregar a una aplicación de Teams. La aplicación de ejemplo ya admite varias pestañas y puede habilitarlas de la siguiente manera.

Ficha equipo

La aplicación solo puede tener una pestaña de equipo.

Adding a Teams tab

En este ejemplo, la ficha equipo es donde se encuentra la página de configuración. Haga clic en el símbolo ... al final de la entrada y elija Editar en la lista desplegable. Cambie la dirección URL a https://yourteamsapp.ngrok.io/configure donde yourteamsapp.ngrok.io se debe reemplazar la dirección URL que usó al hospedar la aplicación.

Pestañas personales

La aplicación puede tener hasta 16 pestañas, incluida la pestaña equipo.

Las pestañas personales se representan de forma diferente a la ficha equipo. Debe ver la ficha Hello que ya aparece en la lista de pestañas personales. En el momento tiene un valor de marcador de posición com.contoso.helloworld.hellotab . Haga clic en el símbolo ... al final de la entrada y elija Editar en la lista desplegable. Aparecerá el siguiente cuadro de diálogo.

Adding a personal tab dialog

Hay dos campos que debe actualizar con la dirección URL de la aplicación.

  • Cambiar la dirección URL del contenido a https://yourteamsapp.ngrok.io/hello
  • Cambiar la dirección URL del sitio web a https://yourteamsapp.ngrok.io/hello

Donde yourteamsapp.ngrok.io se debe reemplazar por la dirección URL que ha usado anteriormente al hospedar la aplicación.

Bots

Los bots son la forma más común de agregar funcionalidad a la aplicación. La muestra Hello World ya tiene un bot como parte de la muestra, pero todavía no se ha registrado con Microsoft.

Adding a bot

El bot que se importó desde el ejemplo no tiene un identificador de aplicación asociado todavía. Tendrá que crear un nuevo bot para que App Studio pueda crear un nuevo identificador de aplicación y registrarlo en Microsoft. Tenga en cuenta que este es el identificador de la aplicación para bot, que es diferente del identificador de aplicación que se ha creado para la aplicación en un paso anterior. Cada bot en una aplicación requiere su propio identificador de aplicación.

Haga clic en el botón eliminar situado junto al Bot importado en la lista de robots.

Ahora no quedan bots para mostrar. Haga clic en configurar. Se mostrará el cuadro de diálogo configurar un bot .

Adding a bot dialog

Agregue un nombre de bot, por ejemplo Contoso bot , y seleccione los tres botones bajo ámbito.

Elija crear bot para salir del cuadro de diálogo. App Studio dedicará un momento a registrar el bot con Microsoft y, a continuación, deberá mostrar el nuevo bot en la lista de robots. Ahora sería un buen momento para abrir un archivo de texto en el Bloc de notas y copiar y pegar el nuevo identificador de bot en él. Necesitará este identificador más adelante.

Haga clic en generar nueva contraseñay anote la contraseña en el mismo archivo de texto que anotó con el identificador de la aplicación de bot en. Esta es la única vez que se mostrará su contraseña, por lo que debe asegurarse de hacerlo ahora.

Actualice la dirección del punto de conexión del bot con https://yourteamsapp.ngrok.io/api/messages , donde yourteamsapp.ngrok.io debe reemplazarse por la dirección URL que usó al hospedar la aplicación.

Ahora sería un buen momento para guardar el archivo de texto si todavía no lo ha hecho. Esta información se agregará a la aplicación hospedada más adelante en este tutorial, lo que permitirá la comunicación segura con el bot.

Extensiones de mensajería

Las extensiones de mensajería permiten a los usuarios solicitar información de su servicio y publicarla, en forma de tarjetas, directamente en la conversación del canal. Las extensiones de mensajería aparecen a lo largo de la parte inferior del cuadro de redacción.

Haga clic en extensiones de mensajería en funcionalidades en la columna izquierda de App Studio para comenzar a configurar la extensión de mensajería.

Adding a messaging extension

La extensión de mensajería de muestra aparece en el panel de la derecha, en extensiones de mensajería. Haga clic en eliminar de nuevo para quitar esta entrada y, a continuación, haga clic en el botón configurar siguiendo los mismos pasos que siguió para los bots. Se mostrará el cuadro de diálogo de la extensión de mensajería .

Seleccione la pestaña usar bot existente y, a continuación, Seleccione uno de los bots existentes. En el menú desplegable, seleccione el bot que creó en la sección anterior. Agregue un nombre de bot y haga clic en Guardar para cerrar el cuadro de diálogo.

En la sección comando , haga clic en Agregar. Estamos agregando un comando basado en la búsqueda, por lo que debe elegir la opción permitir que los usuarios consulten su servicio...

En el cuadro de diálogo nuevo comando , escriba los siguientes valores.

En nuevo comando:

  • Identificador de comando = getRandomText
  • Title = obtener texto aleatorio para divertirse
  • Description = obtiene texto e imágenes aleatorios

En parámetro:

  • Name = cardTitle
  • Title = título de la tarjeta
  • Description = título de la tarjeta para usar

Una vez que haya introducido la información, haga clic en Guardar para cerrar el cuadro de diálogo.

Registrar la aplicación en Microsoft Teams

Ya ha completado la especificación de los detalles de la aplicación, pero quedan dos pasos. En primer lugar, debe usar la sección probar y distribuir de App Studio para instalar la aplicación en Teams y, en segundo lugar, debe actualizar la aplicación hospedada con el identificador de aplicación y la contraseña de su bot. Recuerde que el ejemplo espera usar el mismo identificador de aplicación y la misma contraseña para el bot y la extensión de mensajería.

Haga clic en el elemento probar y distribuir en Finalizar en la columna izquierda de App Studio.

Testing your app

Para cargar la aplicación en Teams, haga clic en el botón instalar en probar y distribuir.

Adding a messaging extension dialog

Haga clic en el cuadro de búsqueda en la sección Agregar a un equipo y seleccione un equipo al que desee agregar la aplicación de ejemplo. Normalmente querrá configurar un equipo especial para realizar las pruebas.

Haga clic en el botón instalar situado en la parte inferior del cuadro de diálogo.

Esto finaliza la parte de App Studio de este tutorial. Ahora debería ver que la aplicación se está ejecutando en Teams, pero el bot y la extensión de mensajería no funcionarán hasta que actualice el entorno de aplicaciones hospedadas para conocer los identificadores de aplicación y las contraseñas.

The finished app

Actualizar la aplicación hospedada

La aplicación de ejemplo requiere que se establezcan las siguientes variables de entorno en los valores que ha anotado anteriormente.

MICROSOFT_APP_ID=<YOUR BOT'S APP ID>
MICROSOFT_APP_PASSWORD=<YOUR BOT'S PASSWORD>
WEBSITE_NODE_DEFAULT_VERSION=8.9.4

La forma de hacerlo varía en función de cómo hospedaste la aplicación. Lo más importante sobre el uso de variables de entorno es que estos valores forman parte de su entorno: se puede acceder a ellos mediante el código de la aplicación, pero no están expuestos a terceros que puedan examinar los archivos que componen el sitio.

Si está ejecutando la aplicación con ngrok, tendrá que configurar algunas variables de entorno local. Hay muchas formas de hacerlo, pero la más sencilla, si usa Visual Studio Code, es agregar una configuración de inicio:

{
    "type": "node",
    "request": "launch",
    "name": "Launch - Teams Debug",
    "program": "${workspaceRoot}/src/app.js",
    "cwd": "${workspaceFolder}/src",
    "env": {
        "BASE_URI": "https://yourNgrokURL.ngrok.io",
        "MICROSOFT_APP_ID": "00000000-0000-0000-0000-000000000000",
        "MICROSOFT_APP_PASSWORD": "yourBotAppPassword",
        "NODE_DEBUG": "botbuilder",
        "SUPPRESS_NO_CONFIG_WARNING": "y",
        "NODE_CONFIG_DIR": "../config"
    }
}

Donde:

MICROSOFT_APP_ID y MICROSOFT_APP_PASSWORD es el identificador y la contraseña, respectivamente, para el bot. NODE_DEBUG le mostrarán lo que está sucediendo en su bot en la consola de depuración de Visual Studio Code. NODE_CONFIG_DIR apunta al directorio de la raíz del repositorio (de forma predeterminada, cuando la aplicación se ejecuta de forma local, la busca en la carpeta src).

Nota

Si no ha detenido NPM de anteriormente en el tutorial, deberá ejecutar para que npm stop Visual Studio Code devuelva las variables de configuración de inicio correctamente.

Configurar la pestaña de la aplicación

Una vez que haya instalado la aplicación en un equipo, tendrá que configurarla para mostrar el contenido. Vaya a un canal del equipo y haga clic en el botón "+" para agregar una nueva pestaña. A continuación, puede elegir Hello World en la lista Agregar una pestaña . A continuación, se mostrará un cuadro de diálogo de configuración. Este cuadro de diálogo le permitirá elegir la pestaña que desea mostrar en este canal. Una vez que seleccione la pestaña y haga clic en Save , puede ver la Hello World ficha cargada con la pestaña que eligió.

Probar el bot en Microsoft Teams

Ahora puede interactuar con el bot en Teams. Elija un canal del equipo en el que haya registrado la aplicación y escriba @your-bot-name , seguido del mensaje. Esto se denomina una @ mención. Cualquier mensaje que envíe al bot se le enviará como respuesta.

Probar la extensión de mensajería

Para probar la extensión de mensajería, puede hacer clic en los tres puntos situados debajo del cuadro de entrada en la vista de conversación. Se mostrará un menú con la aplicación "Hola a todos" . Al hacer clic en él, verá un número de textos aleatorios. Puede elegir una de ellas y se insertará en la conversación.

Elija uno de los textos aleatorios y verá una tarjeta con formato y lista para enviar con su propio mensaje en la parte inferior.