API-Based extensión de mensaje para principiantes
Nota:
- Las extensiones de mensaje basadas en API solo admiten comandos de búsqueda.
- Teams Toolkit admite las versiones 2.0 y 3.0.x de OpenAPI Specification.
Las extensiones de mensaje creadas mediante una API (basada en API) mejoran significativamente la funcionalidad de las aplicaciones de Teams al permitirles interactuar con servicios externos. Ayuda a simplificar los flujos de trabajo al reducir la necesidad de cambiar entre diferentes aplicaciones.
Puede usar la extensión de mensajes de API para integrar servicios externos que se usan habitualmente en el flujo de trabajo empresarial. Por ejemplo, una empresa que usa con frecuencia un sistema CRM para la administración de clientes podría usar una extensión de mensajería para capturar y mostrar datos de clientes directamente desde Teams. Al reducir la necesidad de cambiar entre diferentes aplicaciones, el usuario ahorra tiempo y mejora. La extensión de mensajes basada en API se admite en los clientes de escritorio, web y móviles de Teams.
Requisitos previos
Esta es una lista de las herramientas que necesita para compilar e implementar las aplicaciones.
| Instalar | Para usar... |
|---|---|
| Kit de herramientas de Teams | Extensión de Microsoft Visual Studio Code que crea un scaffolding de proyecto para la aplicación. Use la versión más reciente. |
| Microsoft Teams | Microsoft Teams para colaborar con todos los usuarios con los que trabaje a través de aplicaciones para chat, reuniones y llamadas a todos en un solo lugar. |
| Node.js | Entorno de tiempo de ejecución de JavaScript de back-end. Para obtener más información, vea Node.js tabla de compatibilidad de versiones para el tipo de proyecto. |
| Microsoft Edge (recomendado) o Google Chrome | Un explorador con herramientas de desarrollo. |
| Visual Studio Code | Entornos de compilación de JavaScript, TypeScript o SharePoint Framework (SPFx). Use la versión 1.55 o posterior. |
| Cuenta de desarrollador de Microsoft 365 | Acceso a la cuenta de Teams con los permisos adecuados para instalar una aplicación. |
| Portal para desarrolladores de Teams | Portal basado en web para configurar, administrar y publicar la aplicación de Teams en su organización o en microsoft Teams Store. |
| Documento de descripción de OpenAPI (OAD) | Documento en el que se describen las funcionalidades de la API. Para obtener más información, consulte Descripción de OpenAPI. |
Preparación del entorno de desarrollo
Después de instalar las herramientas necesarias, configure el entorno de desarrollo.
Instalación del kit de herramientas de Teams
El kit de herramientas de Teams ayuda a simplificar el proceso de desarrollo con herramientas para aprovisionar e implementar recursos en la nube para la aplicación, publicar en la Tienda Teams y mucho más.
Puede usar el kit de herramientas con Visual Studio Code o la CLI (interfaz de línea de comandos), denominada Teamsapp.
Abra Visual Studio Code y seleccione la vista Extensiones (Ctrl+Mayús+X / ⌘⇧-X o Ver > extensiones).
En el cuadro de búsqueda, escriba Kit de herramientas de Teams.
Seleccione Instalar junto al kit de herramientas de Teams.
El icono del kit de herramientas de Teams aparece en la barra de actividad de Visual Studio Code.
También puede encontrar el kit de herramientas de Teams en Visual Studio Code Marketplace.
Nota:
La versión más reciente del kit de herramientas de Teams es v5.
Configuración del inquilino de desarrollo de Teams
Un inquilino es como un espacio o un contenedor para su organización en Teams, donde chatea, comparte archivos y ejecuta reuniones. Este espacio también es donde carga y prueba la aplicación personalizada. Vamos a comprobar si está listo para desarrollar con el inquilino.
Comprobación de la opción de carga de aplicaciones personalizadas
Después de crear la aplicación, debe cargarla en Teams sin distribuirla. Este proceso se conoce como carga de aplicaciones personalizada. Inicie sesión en su cuenta de Microsoft 365 para ver esta opción.
Nota:
La carga de aplicaciones personalizada es necesaria para obtener una vista previa y probar aplicaciones en el entorno local de Teams. Si no está habilitada, no puede obtener una vista previa y probar la aplicación en el entorno local de Teams.
¿Ya tiene un inquilino y tiene acceso de administrador? ¡Vamos a comprobar si realmente lo haces!
Compruebe si puede cargar una aplicación personalizada en Teams:
En el cliente de Teams, seleccione el icono Aplicaciones .
Seleccione Administrar las aplicaciones.
Seleccione Cargar una aplicación.
Busque la opción Cargar una aplicación personalizada. Si ve la opción , la carga de aplicaciones personalizada está habilitada.
Nota:
Póngase en contacto con el administrador de Teams si no encuentra la opción de cargar una aplicación personalizada.
Creación de un inquilino para desarrolladores de Teams gratuito (opcional)
Si no tiene una cuenta de desarrollador de Teams, puede obtenerla de forma gratuita. ¡Únete al programa para desarrolladores de Microsoft 365!
Seleccione Unirse ahora y siga las instrucciones en pantalla.
En la pantalla de bienvenida, seleccione Configurar suscripción A5.
Configure su cuenta de administrador. Cuando haya terminado, aparecerá la siguiente pantalla.
Inicie sesión en Teams con la cuenta de administrador que acaba de configurar. Compruebe que tiene la opción Cargar una aplicación personalizada en Teams.
Obtener una cuenta gratuita de Azure
Si desea hospedar la aplicación o acceder a los recursos en Azure, debe tener una suscripción a Azure. Cree una cuenta gratuita antes de empezar.
Ahora tiene todas las herramientas para configurar su cuenta. A continuación, vamos a configurar el entorno de desarrollo y empezar a compilar. Seleccione primero la aplicación que desea compilar.
Compilación de una extensión de mensaje basada en API
Después de configurar el área de trabajo del proyecto con Teams Toolkit, compile el proyecto de bot. Asegúrese de que ha iniciado sesión en su cuenta de Microsoft 365.
Inicio de sesión en su cuenta de Microsoft 365
Use esta cuenta para iniciar sesión en Teams. Si usa un inquilino del programa para desarrolladores de Microsoft 365, la cuenta de administrador que configuró al registrarse es la cuenta de Microsoft 365.
Abrir Visual Studio Code.
Seleccione el icono kit de herramientas de
Teams en la barra lateral.Seleccione Iniciar sesión en M365.
Se abre el explorador web predeterminado para permitirle iniciar sesión en la cuenta.
Inicie sesión en su cuenta de Microsoft 365 con sus credenciales.
Cierre el explorador cuando se le solicite y vuelva a Visual Studio Code.
Vuelva al kit de herramientas de Teams en Visual Studio Code.
Use esta cuenta para iniciar sesión en Teams. Si usa un inquilino del programa para desarrolladores de Microsoft 365, la cuenta de administrador que configuró al registrarse es la cuenta de Microsoft 365.
Ahora ya está listo para compilar la aplicación y ejecutarla localmente.
Crear documento de descripción de OpenAPI
OpenAPI Description (OAD) es la especificación estándar del sector que describe cómo se estructuran y describen los archivos OpenAPI. Es un formato legible y independiente del lenguaje para describir las API. Es fácil para los humanos y las máquinas leer y escribir. El esquema es legible y se representa en YAML o JSON.
Debe tener un documento de descripción de OpenAPI (OAD) antes de crear una extensión de mensaje basada en API. La especificación de API debe cumplir los criterios siguientes:
- No se debe especificar la
authpropiedad . - JSON y YAML son los formatos admitidos.
- Se admiten las versiones 2.0 y 3.0.x de OpenAPI.
- Teams no admite las construcciones oneOf, anyOf, allOf y not (swagger.io).
- No se admite la construcción de matrices para la solicitud; sin embargo, se admiten objetos anidados dentro de un cuerpo de solicitud JSON.
- El cuerpo de la solicitud, si está presente, debe ser application/Json para garantizar la compatibilidad con una amplia gama de API.
- Defina una dirección URL del servidor de protocolo HTTPS para la
servers.urlpropiedad . - Solo se admite la búsqueda de parámetros únicos.
- Solo se permite un parámetro necesario sin un valor predeterminado.
- Solo se admiten los métodos HTTP POST y GET.
- El documento Descripción de OpenAPI debe tener un .
operationId - La operación no debe tener los parámetros Header o Cookie necesarios sin valores predeterminados.
- Un comando debe tener exactamente un parámetro.
- Asegúrese de que no haya referencias remotas en el documento Descripción de OpenAPI.
- Un parámetro obligatorio con un valor predeterminado se considera opcional.
Hemos usado la siguiente descripción de OpenAPI como ejemplo para este tutorial:
Documento de descripción de OpenAPI
openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
get:
operationId: searchTools
summary: Search for AI Tools
parameters:
- in: query
name: search
required: true
schema:
type: string
description: Used to search for AI tools by their category based on the keywords. For example, search="tool to create music" gives tools that can create music.
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsResponse'
"400":
description: Search Error
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsError'
components:
schemas:
searchToolsResponse:
required:
- search
type: object
properties:
tools:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tool.
opentools_url:
type: string
description: The URL to access the tool.
main_summary:
type: string
description: A summary of what the tool is.
pricing_summary:
type: string
description: A summary of the pricing of the tool.
categories:
type: array
items:
type: string
description: The categories assigned to the tool.
platforms:
type: array
items:
type: string
description: The platforms that this tool is available on.
description: The list of AI tools.
searchToolsError:
type: object
properties:
message:
type: string
description: Message of the error.
Nota:
Teams Toolkit admite las versiones 2.0 y 3.0.x de OpenAPI Specification.
Ahora que tiene el documento Descripción de OpenAPI, también requiere una plantilla de representación de respuesta para que la aplicación responda a las solicitudes GET o POST. La plantilla de representación de respuesta consta de una plantilla de tarjeta adaptable, una plantilla de tarjeta de vista previa y metadatos. Si crea una aplicación mediante el Kit de herramientas de Teams o el portal para desarrolladores de Teams, la plantilla de representación de respuesta se extrae automáticamente del documento Descripción de OpenAPI.
El código siguiente es un ejemplo de la plantilla de representación de respuesta:
Plantilla de representación de respuesta
{
"version": "1.0.0",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "${if(name, name, 'N/A')}",
"size": "Large",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "Categories: ${join(categories, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(main_summary, main_summary, 'N/A')}",
"size": "Medium",
"wrap": true
},
{
"type": "TextBlock",
"text": "Supported Platforms: ${join(platforms, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "Pricing Summary:",
"size": "Medium",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(pricing_summary, pricing_summary, 'N/A')}",
"size": "Small",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "${opentools_url}",
"$when": "${opentools_url != null}"
},
{
"type": "Action.OpenUrl",
"title": "Chat with Chatbot",
"url": "${chatbot_short_url}",
"$when": "${chatbot_short_url != null}"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}"
}
}
Ahora puede crear una extensión de mensaje que use el documento Descripción de OpenAPI. Para crear una extensión de mensaje mediante el documento Descripción de OpenAPI, siga estos pasos:
Abrir Visual Studio Code.
Seleccione el icono Kit de herramientas de
Teams en la barra de actividad de Visual Studio Code.Seleccione Crear una nueva aplicación.
Seleccione Extensión de mensaje.
Seleccionar resultados de búsqueda personalizados
Seleccione Iniciar con un documento de descripción de OpenAPI.
Seleccione Examinar y seleccione el documento Descripción de OpenAPI que guardó anteriormente. Aparece una lista de las API disponibles en el documento.
Seleccione las API de la lista y seleccione Aceptar.
Seleccione Carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada.
También puede cambiar la ubicación predeterminada mediante los pasos siguientes:
Seleccione Examinar.
Seleccione la ubicación del área de trabajo del proyecto.
Seleccione seleccionar carpeta.
Escriba un nombre adecuado para la aplicación y, a continuación, seleccione Entrar.
Aparece un cuadro de diálogo. Seleccione Sí, Confío en los autores o No, no confío en los autores según sus necesidades.
La aplicación de Teams con una funcionalidad de extensión de mensaje basada en API se crea en pocos segundos.
Una vez creada la aplicación, el kit de herramientas de Teams muestra el siguiente mensaje:
Seleccione Depuración local para obtener una vista previa del proyecto.
Una vez realizado el scaffolding, vea los directorios y archivos del proyecto en el Explorador en Visual Studio Code.
| Nombre de la carpeta | Contenido |
|---|---|
env/.env.dev.user |
Archivo de configuración para el entorno local utilizado por teamsapp.yml para personalizar las reglas de aprovisionamiento e implementación. |
appPackage |
Archivos de plantilla de manifiesto de aplicación e iconos de aplicación (color.png y outline.png). |
appPackage/manifest.json |
Manifiesto de aplicación para ejecutar la aplicación en un entorno local y remoto. |
appPackage/apiSpecificationFiles/openapi.yml |
Un archivo de descripción que contiene la estructura y la sintaxis de una API en la descripción de OpenAPI. |
appPackage/responseTemplates |
La plantilla de representación de respuesta, que consta de la plantilla de tarjeta adaptable, la plantilla de tarjeta de vista previa y los metadatos. |
teamsapp.yml |
Este es el proyecto principal del kit de herramientas de Teams que define las propiedades y las definiciones de la fase de configuración. |
Sugerencia
Familiarícese con bots fuera de Teams antes de integrar el primer bot en Teams.
Aprovisionamiento de la aplicación
Para aprovisionar la aplicación en Azure:
Vaya al kit de herramientas de Teams y, en el panel izquierdo, seleccione Ejecutar y depurar (Ctrl+Mayús+D).
Seleccione Iniciar remoto en Teams (Edge) en la lista desplegable de configuración de inicio.
El kit de herramientas de Teams aprovisiona la aplicación en Azure e la implementa en Teams.
Nota:
La primera vez que aprovisiones la aplicación, tarda unos minutos en completarse. Las disposiciones posteriores son más rápidas.
Vaya a un mensaje de chat y seleccione el icono Acciones y aplicaciones . En el menú flotante, busque la aplicación.
Seleccione la aplicación en la lista y desencadene los comandos de búsqueda desde el área del mensaje de redacción.
Teams envía el resultado de la búsqueda como una tarjeta adaptable en el mensaje de chat.
Desafío completo
¿Se te ocurrió algo como esto?
Enhorabuena.
¡Lo ha conseguido! Ha creado una extensión de mensaje basada en API.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.