Tutorial avanzado para compilar la extensión de mensajes basada en API
Nota:
- Las extensiones de mensaje basadas en API solo admiten comandos de búsqueda.
- Las extensiones de mensajes basadas en API solo están disponibles en la versión preliminar del desarrollador público.
Las extensiones de mensaje creadas mediante API (basada en API) mejoran significativamente la funcionalidad de las aplicaciones de Teams al permitirles interactuar con servicios externos. Las extensiones de mensajes basadas en API pueden ayudar a simplificar los flujos de trabajo al reducir la necesidad de cambiar entre diferentes aplicaciones.
Puede usar extensiones de mensajes basadas en 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 mensaje para capturar y mostrar datos de clientes directamente desde Teams. Esta aplicación ayuda a ahorrar tiempo y mejora la eficiencia al reducir la necesidad de cambiar entre diferentes aplicaciones. Esta característica se admite en todas las plataformas en las que Teams está disponible, incluidos los dispositivos móviles, web y de escritorio.
Requisitos previos
Esta es una lista de las herramientas que necesita para compilar e implementar las aplicaciones.
| Instalar | Para usar... |
|---|---|
| Microsoft Teams | Microsoft Teams para colaborar con todos los usuarios con los que trabaje a través de aplicaciones para chat, reuniones o llamadas, todo en un solo lugar. |
| 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. |
| Cuenta de Azure | Acceso a recursos de Azure. |
| 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. |
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.
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.
Crear documento de descripción de OpenAPI
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.
Para interactuar con las API, es necesario un documento de descripción de OpenAPI. El documento Descripción de OpenAPI debe cumplir los siguientes criterios:
- 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 requerir parámetros Header o Cookie 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:
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, a search for "tool to create music" provides a list of 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:
Asegúrese de que la required: true propiedad solo está disponible para un parámetro. Si hay más de un parámetro necesario, puede actualizar la propiedad requerida a required: false para los demás parámetros.
Puede validar si el documento Descripción de OpenAPI es válido. Para comprobarlo, siga estos pasos:
Vaya al validador de Swagger/OpenAPI y valide el documento Descripción de OpenAPI.
Guarde el documento Descripción de OpenAPI.
Vaya a Swagger Editor.
En el panel izquierdo, pegue la descripción de OpenAPI en el editor.
En el panel derecho, seleccione GET.
Seleccione Probar.
Escriba los valores del parámetro de búsqueda como Herramienta para crear música.
Seleccione Ejecutar. El editor swagger muestra una respuesta con una lista de productos.
Vaya a Cuerpoderespuesta de respuesta> del servidor.
En
products, copie el primer producto de la lista y guárdelo para futuras referencias.
Creación de una plantilla de representación de respuesta
Un documento de descripción de OpenAPI 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.
Plantilla de tarjeta adaptable
Para crear una plantilla de tarjeta adaptable, siga estos pasos:
Vaya a ChatGPT y pregunte a la siguiente consulta en el área de redacción del mensaje:
Create an Adaptive Card Template that binds to the following response: "categories": [ "Music Generation", "AI Detection" ], "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator", "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.", "name": "AI Music Generator", "opentools_url": "https://goto.opentools.ai/ai-music-generator", "platforms": [ "Web", "App", "API" ]Seleccione Enviar mensaje.
ChatGPT genera una respuesta con una plantilla de tarjeta adaptable que se enlaza a los datos de ejemplo. Guarde la plantilla tarjeta adaptable para futuras referencias.
A continuación se muestra un ejemplo de la plantilla tarjeta adaptable:
Plantilla de tarjeta adaptable
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.4", "body": [ { "type": "TextBlock", "text": "AI Music Generator", "weight": "Bolder", "size": "Large" }, { "type": "TextBlock", "text": "Categories", "size": "Medium" }, { "type": "TextBlock", "text": "Music Generation, AI Detection", "wrap": true }, { "type": "TextBlock", "text": "Description", "size": "Medium" }, { "type": "TextBlock", "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.", "wrap": true }, { "type": "TextBlock", "text": "Platform", "size": "Medium" }, { "type": "TextBlock", "text": "Web, App, API", "wrap": true } ], "actions": [ { "type": "Action.OpenUrl", "title": "Learn More", "url": "https://goto.opentools.ai/ai-music-generator" }, { "type": "Action.OpenUrl", "title": "Try It", "url": "https://goto.opentools.ai/c/ai-music-generator" } ] }Para comprobar si la tarjeta adaptable generada se enlaza a los datos de ejemplo, siga estos pasos:
Vaya a Designer de tarjeta adaptable.
Vaya a Seleccionar aplicación host y, a continuación, seleccione Microsoft Teams en la lista desplegable.
Vaya a CARD PAYLOAD EDITOR y pegue el código de plantilla de tarjeta adaptable.
Vaya a SAMPLE DATA EDITOR (EDITOR DE DATOS DE EJEMPLO ) y pegue la respuesta GET API que guardó anteriormente.
Seleccione Modo de vista previa. El diseñador de tarjetas adaptables muestra una tarjeta adaptable con los datos que enlazan la respuesta a la plantilla.
Creación de una plantilla de tarjeta en versión preliminar
La plantilla de tarjeta de vista previa puede contener propiedades titley subtitleimage . Si la respuesta de API no tiene una imagen, puede quitar la propiedad image.
A continuación se muestra un ejemplo de una plantilla de tarjeta en versión preliminar:
Plantilla de tarjeta de vista previa
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}",
}
Cree una condición if para y titlesubtitle, donde:
- Si el nombre existe, el bot usa el nombre.
- Si el nombre no existe, el bot usa NA.
Por ejemplo, "title": "Name: ${if(name, name, 'N/A')}".
Guarde la plantilla de tarjeta de vista previa para futuras referencias.
Plantilla de representación de respuesta
La plantilla de representación de respuesta debe ajustarse al esquema hospedado en https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json.
Para crear una plantilla de representación de respuesta, siga estos pasos:
Cree un archivo JSON y agregue el código siguiente al archivo:
{ "version": "1.0.0", "$schema": "<URL_REFERENCE_TO_SCHEMA>", "jsonPath": "", "responseLayout": "", "responseCardTemplate": { }, "previewCardTemplate": { } }Actualice las propiedades de la plantilla de representación de respuesta como se indica a continuación:
"version":"1.0.0""$schema":"http://adaptivecards.io/schemas/adaptive-card.json""jsonPath":"tools"jsonPathes la ruta de acceso a uno o más resultados en la respuesta JSON de respuesta. Agregue ajsonPathlos datos o matrices pertinentes de la lista de productos en la respuesta de la API. En este caso, son herramientasjsonPath. Para obtener más información sobre cómo determinar la ruta de acceso JSON, consulte Consulta de JSON con ruta de acceso JSON."responseLayout":"list"responseLayoutespecifica el diseño de los datos adjuntos. Se usa para las respuestas del resultado de tipo. Los tipos admitidos son list y grid. Si el cuerpo de la respuesta contiene un objeto con varios elementos, como texto, título e imagen, el diseño de la respuesta debe establecerse enlist. Si la respuesta de API solo contiene imágenes o miniaturas, el diseño de la respuesta debe establecerse engrid."responseCardTemplate": pegue el código de plantilla de tarjeta adaptable que guardó anteriormente.responseCardTemplatees una plantilla de tarjeta adaptable para asignar la respuesta JSON a una tarjeta adaptable."previewCardTemplate": pegue el código de plantilla de tarjeta de vista previa que guardó anteriormente.previewCardTemplatees una plantilla de tarjeta de vista previa que se usa para mostrar una vista previa de los resultados en el control flotante de la extensión de mensaje.
Guarde la plantilla de representación de respuesta en la misma carpeta en la que guardó el documento Descripción de OpenAPI.
El código siguiente es un ejemplo de una plantilla de representación de respuesta:
Plantilla de representación de respuesta
{
"version": "devPreview",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "AI Music Generator",
"weight": "Bolder",
"size": "Large"
},
{
"type": "TextBlock",
"text": "Categories",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Music Generation, AI Detection",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
"wrap": true
},
{
"type": "TextBlock",
"text": "Platform",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Web, App, API",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "https://goto.opentools.ai/ai-music-generator"
},
{
"type": "Action.OpenUrl",
"title": "Try It",
"url": "https://goto.opentools.ai/c/ai-music-generator"
}
]
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}",
}
}
Creación de un manifiesto de aplicación
Ahora, debe crear un manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams). En el manifiesto de la aplicación se describe cómo se integra la aplicación en el producto de Microsoft Teams.
Creación de un manifiesto de aplicación de Teams
Para crear el manifiesto, siga estos pasos:
Cree un nuevo archivo JSON. El manifiesto de la aplicación debe ajustarse al esquema definido en el esquema de manifiesto de aplicación de versión preliminar para desarrolladores públicos.
Agregue el código siguiente al archivo JSON:
Manifiesto de aplicación
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", "manifestVersion": "devPreview", "version": "1.0.3", "id": "<<YOUR-MICROSOFT-APP-ID>>", "packageName": "com.microsoft.teams.extension", "developer": { "name": "Teams App, Inc.", "websiteUrl": "https://www.example.com", "privacyUrl": "https://www.example.com/termofuse", "termsOfUseUrl": "https://www.example.com/privacy" }, "icons": { "color": "color.png", "outline": "outline.png" }, "name": { "short": "Search ME API", "full": "Search ME API full" }, "description": { "short": "product app for testing API Message Extensions", "full": "product app for testing API Message Extensions" }, "accentColor": "#FFFFFF", "composeExtensions": [ { "composeExtensionType": "", "apiSpecificationFile": "", "commands": [ { "context": [ "compose" ], "type": "query", "title": "API for fetching Klarna.", "id": "", "parameters": [ { "name": "", "title": "", "description": "" } ], "description": "", "apiResponseRenderingTemplateFile": "" } ] } ], "permissions": [ "identity", "messageTeamMembers" ], "validDomains": [] }Actualice las propiedades del manifiesto de la aplicación de la siguiente manera:
- Reemplace por
<<YOUR-MICROSOFT-APP-ID>>el identificador de aplicación de Microsoft del bot. - Actualice el valor de a
composeExtensionTypeapiBased. - Actualice el valor de
apiSpecificationFilea la ruta de acceso del archivo de descripción de OpenAPI. - Actualice el valor de a
commands.idsearchTools. - Actualice el valor de a
commands.titleSearch for AI Tools. - Actualice el valor de a
commands.descriptionSearch for AI Tools. - Actualice el valor de a
parameters.namesearch. Si no hay parámetros, los valores deben ser parámetros de consulta oproperties.namesi hacen referencia a una propiedad en el esquema del cuerpo de la solicitud. - Actualice a
apiResponseRenderingTemplateFilela ruta de acceso del archivo de plantilla de representación de respuesta. - Actualice el valor de
validDomainsal punto deservice URLconexión definido en el archivo de descripción de OpenAPI.
- Reemplace por
Guarde el manifiesto de aplicación de Teams en la misma carpeta en la que guardó el documento Descripción de OpenAPI y la plantilla de representación de respuesta.
- Necesita una imagen de color y una imagen de esquema. Estas imágenes deben incluirse en la carpeta y hacer referencia a ellas en el manifiesto de la aplicación de Teams.
- Comprima el contenido de la carpeta. El archivo ZIP debe incluir los siguientes archivos:
- Documento de descripción de OpenAPI
- Plantilla de representación de respuesta
- Manifiesto de la aplicación
- Icono de color
- Icono de esquema
Carga de una aplicación personalizada en Teams
Inicie sesión en el entorno de prueba de Teams para probar la aplicación en Teams. Para cargar una aplicación personalizada en Teams, siga estos pasos:
Vaya a Microsoft Teams e inicie sesión con sus credenciales de inquilino de prueba.
Vaya a Aplicaciones>Administrar la aplicación>Carga de una aplicación.
Seleccione Cargar una aplicación personalizada.
Seleccione el archivo ZIP creado y seleccione Abrir.
Seleccione Agregar. La aplicación se agrega a Teams.
Vaya a un chat, seleccione + en el área de redacción del mensaje y busque la aplicación.
Seleccione la aplicación y realice una consulta de búsqueda.
La aplicación responde con una tarjeta adaptable en la ventana de chat.
Seleccione Enviar.
Enhorabuena.
¡Lo ha conseguido! Ha aprendido a crear una extensión de mensaje basada en API mediante el documento Descripción de OpenAPI.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.