Share via

Extensión de mensaje basada en API de compilación

  • Artículo

Nota:

Las extensiones de mensaje basadas en API solo admiten comandos de búsqueda.

Las extensiones de mensajes basadas en API son una funcionalidad de aplicación de Microsoft Teams que integra las API externas directamente en Teams, lo que mejora la facilidad de uso de la aplicación y ofrece una experiencia de usuario sin problemas. Las extensiones de mensajes basadas en API admiten comandos de búsqueda y se pueden usar para capturar y mostrar datos de servicios externos dentro de Teams, lo que simplifica los flujos de trabajo al reducir la necesidad de cambiar entre aplicaciones.

Antes de empezar, asegúrese de cumplir los siguientes requisitos:


1. Descripción de OpenAPI (OAD)

Asegúrese de cumplir las siguientes directrices para el documento de descripción de OpenAPI (OAD):

  • Se admiten las versiones 2.0 y 3.0.x de OpenAPI.
  • JSON y YAML son los formatos admitidos.
  • El cuerpo de la solicitud, si está presente, debe ser application/Json.
  • Defina una dirección URL del servidor de protocolo HTTPS para la servers.url propiedad .
  • Solo se admiten los métodos HTTP POST y GET.
  • El documento Descripción de OpenAPI debe tener un .operationId
  • Solo se permite un parámetro necesario sin un valor predeterminado.
  • Un parámetro obligatorio con un valor predeterminado se considera opcional.
  • Los usuarios no deben especificar un parámetro para un encabezado o cookie.
  • La operación no debe tener un encabezado o parámetros de cookie necesarios sin valores predeterminados.
  • Asegúrese de que no haya referencias remotas en el documento Descripción de OpenAPI.
  • No se admite la construcción de matrices para la solicitud; sin embargo, se admiten objetos anidados dentro de un cuerpo de solicitud JSON.
  • Teams no admite las oneOfconstrucciones , anyOf, allOfy not (swagger.io).

El código siguiente es un ejemplo de un 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" will give 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.

Para obtener más información, consulte Estructura de OpenAPI.


2. Manifiesto de aplicación

Asegúrese de cumplir las siguientes directrices para el manifiesto de la aplicación:

  • Establezca la versión del manifiesto de la aplicación en 1.17.

  • Establezca en composeExtensions.composeExtensionTypeapiBased.

  • Defina composeExtensions.apiSpecificationFile como la ruta de acceso relativa al archivo de descripción de OpenAPI dentro de la carpeta. Esto vincula el manifiesto de aplicación a la especificación de API.

  • Defina apiResponseRenderingTemplateFile como la ruta de acceso relativa a la plantilla de representación de respuesta. Esto especifica la ubicación de la plantilla que se usa para representar las respuestas de la API.

  • Cada comando debe tener un vínculo a la plantilla de representación de respuesta. Esto conecta cada comando a su formato de respuesta correspondiente.

  • La Commands.id propiedad del manifiesto de la aplicación debe coincidir con en operationId la descripción de OpenAPI.

  • Si un parámetro necesario no tiene un valor predeterminado, el comando parameters.name del manifiesto de la aplicación debe coincidir con el parameters.name del documento Descripción de OpenAPI.

  • Si no hay ningún parámetro necesario, el comando parameters.name del manifiesto de la aplicación debe coincidir con el opcional parameters.name en la descripción de OpenAPI.

  • Asegúrese de que los parámetros de cada comando coinciden exactamente con los nombres de los parámetros definidos para la operación en la especificación de OpenAPI.

  • Se debe definir una plantilla de representación de respuesta por comando, que se usa para convertir respuestas desde una API.

  • La descripción completa no debe superar los 128 caracteres.

    {
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+  "manifestVersion": "devPreview",
"version": "1.0.0",
"id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89",
"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": "AI tools",
    "full": "AI tools"
},
"description": {
    "short": "AI tools",
    "full": "AI tools"
},
"accentColor": "#FFFFFF",
"composeExtensions": [
    {
+      "composeExtensionType": "apiBased",
+      "authorization": {
+        "authType": "apiSecretServiceAuth ",
+        "apiSecretServiceAuthConfiguration": {
+            "apiSecretRegistrationId": "96270b0f-7298-40cc-b333-152f84321813"
+        }
+      },
+      "apiSpecificationFile": "aitools-openapi.yml",
       "commands": [
       {
          "id": "searchTools",
          "type": "query",
          "context": [
             "compose",
             "commandBox"
          ],
          "title": "search for AI tools",
          "description": "search for AI tools",
          "parameters": [
             {
             "name": "search",
             "title": "search query",
             "description": "e.g. search='tool to create music'"
             }
          ],
+          "apiResponseRenderingTemplateFile": "response-template.json"
       }
       ]
    }
],
"validDomains": []
}

Parameters

Nombre Descripción
composeExtensions.composeExtensionType Tipo de extensión Compose. Actualice el valor a apiBased.
composeExtensions.authorization Información relacionada con la autorización para la extensión de mensaje basada en API
composeExtensions.authorization.authType Enumeración de posibles tipos de autorización. Los valores admitidos son none, apiSecretServiceAuthy microsoftEntra.
composeExtensions.authorization.apiSecretServiceAuthConfiguration Detalles de captura de objetos necesarios para realizar la autenticación del servicio. Solo se aplica cuando el tipo de autenticación es apiSecretServiceAuth.
composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId Id. de registro devuelto cuando el desarrollador envía la clave de API a través del Portal para desarrolladores.
composeExtensions.apiSpecificationFile Hace referencia a un archivo de descripción de OpenAPI en el paquete de la aplicación. Incluya cuando el tipo es apiBased.
composeExtensions.commands.id Identificador único que se asigna al comando de búsqueda. La solicitud de usuario incluye este id. El identificador debe coincidir con el OperationId disponible en la descripción de OpenAPI.
composeExtensions.commands.context Matriz donde se definen los puntos de entrada de la extensión de mensaje. Los valores predeterminados son compose y commandBox.
composeExtensions.commands.parameters Define una lista estática de parámetros para el comando. El nombre debe asignarse a en parameters.name la descripción de OpenAPI. Si hace referencia a una propiedad en el esquema del cuerpo de la solicitud, el nombre debe asignarse a properties.name los parámetros de consulta o .
composeExtensions.commands.apiResponseRenderingTemplateFile Plantilla usada para dar formato a la respuesta JSON de la API del desarrollador a la respuesta de tarjeta adaptable. [Obligatorio]

Para obtener más información, vea composeExtensions.


3. Plantilla de representación de respuesta

Nota:

Teams admite tarjetas adaptables hasta la versión 1.5 y las tarjetas adaptables Designer admiten hasta la versión 1.6.

  • Defina la dirección URL de referencia del esquema en la $schema propiedad para establecer la estructura de la plantilla.
  • Los valores admitidos para responseLayout son list y grid, que determinan cómo se presenta visualmente la respuesta.
  • Se recomienda para jsonPath matrices o cuando los datos de la tarjeta adaptable no son el objeto raíz. Por ejemplo, si los datos están anidados en productDetails, la ruta de acceso JSON sería productDetails.
  • Defina jsonPath como la ruta de acceso a los datos o matriz pertinentes en la respuesta de la API. Si la ruta de acceso apunta a una matriz, cada entrada de la matriz se enlaza con la plantilla tarjeta adaptable y devuelve como resultado independiente. [Opcional]
  • Obtenga una respuesta de ejemplo para validar la plantilla de representación de respuesta. Esto sirve como prueba para asegurarse de que la plantilla funciona según lo esperado.
  • Use herramientas como Fiddler o Postman para llamar a la API y asegurarse de que la solicitud y la respuesta son válidas. Este paso es fundamental para solucionar problemas y confirmar que la API funciona correctamente.
  • Puede usar la tarjeta adaptable Designer para enlazar la respuesta de la API a la plantilla de representación de respuesta y obtener una vista previa de la tarjeta adaptable. Inserte la plantilla en el EDITOR DE CARGA ÚTIL DE TARJETA e inserte la entrada de respuesta de ejemplo en EL EDITOR DE DATOS DE EJEMPLO.

El código siguiente es un ejemplo de una plantilla de representación de respuesta:

Ejemplo de plantilla de representación de respuesta 
{
"version": "1.0",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Title: ${if(title, title, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Description: ${if(description, description, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "Image",
                  "url": "${image}",
                  "size": "Medium",
                  "$when": "${image != null}"
                }
              ]
            },
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "${if(image, image, '')}",
                  "size": "Medium"
                }
              ]
            }
          ]
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Repair ID:",
              "value": "${if(id, id, 'N/A')}"
            },
            {
              "title": "Date:",
              "value": "${if(date, date, 'N/A')}"
            }
          ]
        }
      ]
    }
  ]
  },
  "previewCardTemplate": {
  "title": "Title: ${if(title, title, 'N/A')}",
  "subtitle": "Description: ${if(description, description, 'N/A')}",
  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
  "image": {
    "url": "${image}",
    "$when": "${image != null}"
    }
  }
 }

Tarjeta de vista previa

Captura de pantalla que muestra un ejemplo de extensión de redacción que muestra una matriz de tarjetas de vista previa al buscar una palabra específica. En este caso, la búsqueda de

Tarjeta adaptable expandida

Ejemplo de cómo se ve la tarjeta adaptable expandida una vez que un usuario selecciona una tarjeta de vista previa. La tarjeta adaptable muestra los valores Título, Descripción completa, AssignedTo, RepairId y Fecha.

Parameters

Propiedad Tipo Descripción Obligatorio
version string Versión del esquema de la plantilla de representación de respuesta actual. Sí
jsonPath string Ruta de acceso a la sección pertinente en los resultados a los que se deben aplicar responseCardTemplate y previewCardTemplate. Si no se establece, el objeto raíz se trata como la sección pertinente. Si la sección pertinente es una matriz, cada entrada se asigna a responseCardTemplate y previewCardTemplate. No
responseLayout responseLayoutType Especifica el diseño de los resultados en el control flotante de la extensión de mensaje. Los tipos admitidos son list y grid. Sí
responseCardTemplate adaptiveCardTemplate Plantilla para crear una tarjeta adaptable a partir de una entrada de resultado. Sí
previewCardTemplate previewCardTemplate Plantilla para crear una tarjeta de vista previa a partir de una entrada de resultado. La tarjeta de vista previa resultante se muestra en el menú desplegable extensión de mensaje. Sí

Ruta de acceso json

La ruta de acceso JSON es opcional, pero debe usarse para matrices o donde el objeto que se va a usar como datos de la tarjeta adaptable no es el objeto raíz. La ruta de acceso JSON debe seguir el formato definido por Newtonsoft. Si la ruta de acceso JSON apunta a una matriz, cada entrada de esa matriz se enlaza con la plantilla de tarjeta adaptable y devuelve como resultados independientes.

Ejemplo Supongamos que tiene el código JSON siguiente para una lista de productos y desea crear un resultado de tarjeta para cada entrada.

{
   "version": "1.0",
   "title": "All Products",
   "warehouse": {
      "products": [
        ...
      ]
   }
}

Como puede ver, la matriz de resultados está en "products", que está anidada en "warehouse", por lo que la ruta de acceso JSON sería "warehouse.products".

Use https://adaptivecards.io/designer/ para obtener una vista previa de la tarjeta adaptable insertando la plantilla en la carga útil de la tarjeta Editor, tome una entrada de respuesta de ejemplo de la matriz o del objeto e insértelo en el editor De los mismos datos de la derecha. Asegúrese de que la tarjeta se representa correctamente y es a su gusto. Tenga en cuenta que Teams admite tarjetas hasta la versión 1.5, mientras que el diseñador admite la versión 1.6.

Asignación de esquemas

Las propiedades del documento Descripción de OpenAPI se asignan a la plantilla tarjeta adaptable como se indica a continuación:

  • string, number, integer, boolean los tipos se convierten en textblock.

    Ejemplo

    • Esquema de origen: string, number, integery boolean

       name:
   type: string
   example: doggie

    • Esquema de destino: Textblock

      {
"type": "TextBlock",
"text": "name: ${if(name, name, 'N/A')}",
"wrap": true
}

  • array: una matriz se convierte en un contenedor dentro de la tarjeta adaptable.

    Ejemplo

    • Esquema de origen: array

          type: array
              items:
              required:
                - name
              type: object
                properties:
                id:
                  type: integer
                category:
                  type: object
                  properties:
                  name:
                    type: string

    • Esquema de destino: Container

          {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "id: ${if(id, id, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
                  "wrap": true
                }
              ]
            }

  • object: un objeto se convierte en una propiedad anidada en la tarjeta adaptable.

    Ejemplo

    • Esquema de origen: object

      components:
  schemas:
    Pet:
        category:
          type: object
        properties:
          id:
            type: integer
          name:
            type: string

    • Esquema de destino: propiedad anidada en una tarjeta adaptable

      {
  "type": "TextBlock",
  "text": "category.id: ${if(category.id, category.id, 'N/A')}",
  "wrap": true
},
{
  "type": "TextBlock",
  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
  "wrap": true
}

  • image: si una propiedad es una dirección URL de imagen, se convierte en un elemento Image de la tarjeta adaptable.

    Ejemplo

    • Esquema de origen: image

          image:
      type: string
      format: uri
      description: The URL of the image of the item to be repaired

    • Esquema de destino: "Image"

      {
      "type": "Image",
      "url": "${image}",
      "$when": "${image != null}"
    }

Autenticación

Puede implementar la autenticación en extensiones de mensajes basadas en API para proporcionar acceso seguro y sin problemas a las aplicaciones. Si la extensión de mensaje requiere autenticación, agregue la authorization propiedad en composeExtensions en el manifiesto de la aplicación y defina el tipo de autenticación de la aplicación estableciendo la authType propiedad en authorization. Para habilitar la autenticación para la extensión de mensaje, actualice el manifiesto de la aplicación con cualquiera de los métodos de autenticación siguientes:

Ninguno

Puede actualizar none como un valor para authorization en una extensión de mensaje basada en API cuando la extensión de mensaje no requiere ninguna autenticación para que el usuario acceda a la API.

    "authorization": {
      "authType": "none"
      }
    },

Autenticación del servicio secreto

La autenticación del servicio secreto de API es un método seguro para que la aplicación se autentique con la API. Puede registrar una clave de API a través del Portal para desarrolladores para Teams y generar un identificador de registro de clave de API. Actualice el manifiesto de aplicación con el apiSecretServiceAuthConfiguration objeto con una apiSecretRegistrationId propiedad . Esta propiedad debe contener el identificador de referencia devuelto al enviar la clave de API a través del portal.

Cuando se inicia una solicitud de API, el sistema recupera la clave de API de una ubicación de almacenamiento segura e la incluye en el encabezado de autorización mediante el esquema de token de portador. El punto de conexión de API, tras recibir la solicitud, comprueba la validez de la clave de API. Si la comprobación se realiza correctamente, el punto de conexión procesa la solicitud y devuelve la respuesta deseada, lo que garantiza que solo las solicitudes autenticadas reciban acceso a los recursos de la API.

Registro de una clave de API

El registro de claves de API le permite proteger sus API que están detrás de una autenticación y usarlas en extensiones de mensaje. Puede registrar una clave de API y especificar el dominio, el inquilino y la aplicación que pueden acceder a las API y proporcionar los secretos necesarios para autenticar las llamadas API. A continuación, puede pegar el identificador de clave de API en la extensión de mensaje simplificada y el identificador de clave de API habilita la autenticación para las llamadas API que están detrás de una autenticación.

Para registrar una clave de API, siga estos pasos:

  1. Vaya alregistro de claves de APIde herramientas>.

    Captura de pantalla que muestra la opción de registro de claves de API en el Portal para desarrolladores para Teams.

  2. Seleccione + Nueva clave de API.

  3. En la página Registro de claves de API , en Registrar una clave de API, actualice lo siguiente:

    1. Descripción: descripción de la clave de API.

    2. Agregar dominio: actualice la ruta de acceso base para los puntos de conexión de API. La ruta de acceso debe ser una dirección URL HTTPS segura, incluir un nombre de dominio completo y, opcionalmente, puede incluir una ruta de acceso específica. Por ejemplo, https://api.yelp.com.

      Captura de pantalla que muestra las opciones Descripción y Agregar dominio en la página de registro de claves de API del Portal para desarrolladores para Teams.

  4. En Establecer un inquilino de destino, seleccione cualquiera de las siguientes opciones:

    • Inicio tenent
    • Cualquier inquilino
    Opción Cuándo usarlo Descripción
    Inquilino principal Al desarrollar la aplicación en el inquilino y probarla como una aplicación personalizada o una aplicación personalizada creada para su organización. La clave de API solo se puede usar en el inquilino donde está registrada la API.
    Cualquier inquilino Una vez completada la prueba de la aplicación y desea habilitar la aplicación en distintos inquilinos. Asegúrese de actualizar el inquilino de destino a Cualquier inquilino antes de enviar el paquete de la aplicación al Centro de partners. La clave de API se puede usar en otros inquilinos después de que la aplicación esté disponible en la Tienda Teams.

    Captura de pantalla que muestra las opciones Inquilino principal y Cualquier inquilino en Establecer un encabezado de inquilino de destino en Portal para desarrolladores para Teams.

  5. En Establecer una aplicación de Teams, seleccione cualquiera de las siguientes opciones:

    • Cualquier aplicación de Teams
    • Identificador de aplicación de Teams existente
    Opción Cuándo usarlo Descripción
    Cualquier aplicación de Teams Al desarrollar la aplicación en el inquilino y probarla como una aplicación personalizada o una aplicación personalizada creada para su organización. La clave de API se puede usar con cualquier aplicación de Teams. Resulta útil cuando la aplicación personalizada o la aplicación personalizada creada para su organización tienen identificadores generados después de la carga de la aplicación.
    Identificador de aplicación de Teams existente Después de haber completado las pruebas de la aplicación dentro del inquilino como una aplicación personalizada o una aplicación personalizada creada para su organización. Actualice el registro de clave de API y seleccione Aplicación de Teams existente e introduzca el identificador de manifiesto de la aplicación. La opción Aplicación de Teams existente enlaza el registro de secretos de API a la aplicación específica de Teams.

    Captura de pantalla que muestra las opciones Cualquier aplicación de Teams y Aplicación existente de Teams en Establecer un encabezado de aplicación de Teams en Portal para desarrolladores para Teams.

  6. Seleccione + Agregar secreto. Aparece un cuadro de diálogo Agregar una clave de API .

  7. Escriba un valor para el secreto y seleccione Guardar.

    Nota:

    • Puede mantener hasta dos secretos para cada registro de clave de API. Si una clave está en peligro, se puede quitar rápidamente y permite a Teams cambiar a la segunda clave.
    • El valor secreto debe tener al menos 10 caracteres y como máximo 128 caracteres.
    • Si la primera clave produce un error 401, Teams intenta usar automáticamente la segunda clave. Ayuda con un servicio ininterrumpido para los usuarios y elimina cualquier posible tiempo de inactividad durante la creación de un nuevo secreto.

    Captura de pantalla que muestra la opción Escribir el valor de este secreto para agregar un secreto a la clave de API.

Se genera un identificador de registro de clave de API .

Captura de pantalla que muestra el identificador de registro de clave de API generado en el Portal para desarrolladores para Teams.

Copie y guarde el identificador de registro de la clave de API y actualícelo como un valor para la apiSecretRegistrationId propiedad en el manifiesto de la aplicación.

Actualizar el manifiesto de la aplicación

Puede autorizar las solicitudes entrantes al servicio mediante la configuración de una clave de API estática. La clave de API se almacena de forma segura y se agrega a la llamada API. Agregue un apiSecretServiceAuthConfiguration objeto con una apiSecretRegistrationId propiedad, que contiene el identificador de referencia al enviar la clave de API a través del portal para desarrolladores de Teams. Para obtener más información, vea composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Microsoft Entra

microsoftEntra El método de autenticación usa la identidad de Teams de un usuario de la aplicación para proporcionarle acceso a la aplicación. Un usuario que haya iniciado sesión en Teams no tiene que volver a iniciar sesión en la aplicación en el entorno de Teams. Con solo un consentimiento necesario del usuario de la aplicación, la aplicación de Teams recupera los detalles de acceso de Microsoft Entra ID. Una vez que el usuario de la aplicación ha dado su consentimiento, puede acceder a la aplicación incluso desde otros dispositivos sin tener que volver a validarla.

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

  • Una cuenta de Azure con una suscripción activa.
  • Conocimientos básicos sobre Microsoft Entra ID y el desarrollo de aplicaciones de Teams.

En la imagen siguiente se muestra cómo funciona el inicio de sesión único cuando un usuario de la aplicación de Teams intenta acceder a la aplicación de extensión de mensajes bsed api:

Captura de pantalla que muestra cómo funciona Microsoft Entra autorización de SSO en la API de autenticación.

  • El usuario invoca la aplicación de extensión de mensajes basada en API desde una extensión de mensaje en Teams y solicita un comando que requiere autenticación.
  • La aplicación envía una solicitud al servicio back-end de Teams con el identificador de aplicación y el ámbito necesario (access_as_user).
  • El servicio back-end de Teams comprueba si el usuario ha aceptado la aplicación y el ámbito. Si no es así, muestra una pantalla de consentimiento al usuario y solicita permiso.
  • Si el usuario da su consentimiento, el servicio back-end de Teams genera un token de acceso para el usuario y la aplicación, y lo envía a la aplicación en el encabezado de autorización de la solicitud.
  • La aplicación valida el token. El usuario puede extraer la información del usuario del token, como el nombre, el correo electrónico y el identificador de objeto.
  • La aplicación puede usar el token para llamar a su propia API.
  • La aplicación devuelve la respuesta al usuario en Teams.

Para habilitar el microsoftEntra método de autenticación para la extensión de mensajes basada en API, siga estos pasos:

Registro de una nueva aplicación en Microsoft Entra ID

  1. Abra el Azure Portal en el explorador web.

  2. Seleccione el icono Registros de aplicaciones.

    Centro de administración Microsoft Entra página.

    Aparece la página Registros de aplicaciones.

  3. Seleccione + Nuevo icono de registro..

    Nueva página de registro en Centro de administración Microsoft Entra.

    Aparece la página Registrar una aplicación.

  4. Escriba el nombre de la aplicación que desea que se muestre al usuario de la aplicación. Si lo desea, puede cambiar el nombre en una fase posterior.

    Página de registro de aplicaciones en Centro de administración Microsoft Entra.

  5. Seleccione el tipo de cuenta de usuario que puede acceder a su aplicación. Puede seleccionar entre opciones únicas o multiinquilino en directorios organizativos o restringir el acceso solo a cuentas personales de Microsoft.

    Opciones para tipos de cuenta admitidos
    Opción Seleccione esta opción para...
    Solo cuentas en este directorio organizativo (solo Microsoft: inquilino único) Compile una aplicación para que solo la usen los usuarios (o invitados) de su inquilino.
    A menudo denominada aplicación personalizada creada para su organización (aplicación LOB), esta aplicación es una aplicación de inquilino único en el Plataforma de identidad de Microsoft.
    Cuentas en cualquier directorio organizativo (cualquier inquilino Microsoft Entra ID multiinquilino) Permitir que los usuarios de cualquier Microsoft Entra inquilino usen la aplicación. Esta opción es adecuada si, por ejemplo, está creando una aplicación SaaS y tiene previsto que esté disponible para varias organizaciones.
    Este tipo de aplicación se conoce como una aplicación multiinquilino en el Plataforma de identidad de Microsoft.
    Cuentas en cualquier directorio organizativo (cualquier inquilino Microsoft Entra ID multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox) Dirigirse al conjunto más amplio de clientes.
    Al seleccionar esta opción, va a registrar una aplicación multiinquilino que puede admitir a los usuarios de la aplicación que también tienen cuentas personales de Microsoft.
    Solo cuentas personales de Microsoft Cree una aplicación solo para los usuarios que tengan cuentas personales de Microsoft.

    Nota:

    No es necesario escribir el URI de redirección para habilitar el inicio de sesión único para una aplicación de extensión de mensajes basada en API.

  6. Seleccione Registrar. Aparece un mensaje en el explorador que indica que se ha creado la aplicación.

    Captura de pantalla que muestra un ejemplo de la notificación después de que el registro de la aplicación se haya realizado correctamente en Azure Portal.

    Se muestra la página con el identificador de la aplicación y otras configuraciones.

    Captura de pantalla que muestra la página de detalles de la aplicación en Azure Portal.

  7. Tenga en cuenta y guarde el identificador de aplicación del identificador de aplicación (cliente) para actualizar el manifiesto de la aplicación más adelante.

    La aplicación está registrada en Microsoft Entra ID. Ahora tiene el identificador de aplicación para la aplicación de extensión de mensajes basada en API.

Configurar el ámbito para el token de acceso

Después de crear un nuevo registro de aplicaciones, configure las opciones de ámbito (permiso) para enviar el token de acceso al cliente de Teams y autorizar aplicaciones cliente de confianza para habilitar el inicio de sesión único.

Para configurar el ámbito y autorizar aplicaciones cliente de confianza, necesita:

  • Agregar URI de identificador de aplicación: configure las opciones de ámbito (permiso) para la aplicación. Exponga una API web y configure el URI del identificador de aplicación.
  • Configurar ámbito de API: defina el ámbito de la API y los usuarios que pueden dar su consentimiento para un ámbito. Solo puede permitir que los administradores proporcionen consentimiento para permisos con privilegios superiores.
  • Configuración de la aplicación cliente autorizada: cree identificadores de cliente autorizados para las aplicaciones que desea autenticar previamente. Permite al usuario de la aplicación acceder a los ámbitos de la aplicación (permisos) que ha configurado, sin necesidad de ningún consentimiento adicional. Autorice previamente solo las aplicaciones cliente en las que confíe, ya que los usuarios de la aplicación no tienen la oportunidad de rechazar el consentimiento.

URI de Id. de la aplicación:

  1. Seleccione Administrar>Exponer una API en el panel izquierdo.

    Aparece la página Exponer una API.

  2. Seleccione Agregar para generar el URI del identificador de aplicación en forma de api://{AppID}.

    Establecer URI de id. de aplicación

    Aparece la sección para establecer el URI del ID de la aplicación.

  3. Escriba el URI del identificador de aplicación en el formato que se explica aquí.

    URI del identificador de aplicación

    • El URI del identificador de aplicación se rellena previamente con el identificador de aplicación (GUID) en el formato api://{AppID}.
    • El formato uri del identificador de aplicación debe ser: api://fully-qualified-domain-name.com/{AppID}.
    • Inserte el fully-qualified-domain-name.com entre api:// y {AppID} (el cual es, GUID). Por ejemplo, api://example.com/{AppID}.

    Importante

    • Información confidencial: el URI del identificador de aplicación se registra como parte del proceso de autenticación y no debe contener información confidencial.

    • URI de identificador de aplicación para la aplicación con varias funcionalidades: si va a compilar una extensión de mensaje basada en API, escriba el URI del identificador de aplicación como api://fully-qualified-domain-name.com/{YourClientId}, donde {YourClientId} es el identificador de aplicación de Microsoft Entra.

    • Formato para el nombre de dominio: use letras minúsculas para el nombre de dominio. No use mayúsculas.

      Por ejemplo, para crear una aplicación web o un servicio de aplicaciones con el nombre del recurso, demoapplication:

      Si el nombre del recurso base usado es La dirección URL será... El formato es compatible con...
      demoapplication https://demoapplication.example.net Todas las plataformas
      DemoApplication https://DemoApplication.example.net Solo para escritorio, web e iOS. No se admite en Android.

      Use la demoapplication de la opción en minúsculas como nombre de recurso base.

  4. Haga clic en Guardar.

    Aparece un mensaje en el explorador que indica que se ha actualizado el URI del identificador de aplicación.

    Mensaje de URI de id. de la aplicación

    El URI del identificador de aplicación se muestra en la página.

    URI de id. de aplicación actualizado

  5. Tenga en cuenta y guarde el URI del identificador de aplicación para actualizar el manifiesto de la aplicación más adelante.

Configuración del ámbito de API

Nota:

La extensión de mensajes basada en API solo admite access_as_user ámbito.

  1. Seleccione + Agregar un ámbito en la sección Ámbitos definidos por esta API.

    Seleccionar un ámbito

    Aparece la página Agregar un ámbito.

  2. Introduzca los detalles para configurar el ámbito.

    En la captura de pantalla se muestra cómo agregar detalles de ámbito en Azure.

    1. Introduzca el nombre del ámbito. Este campo es obligatorio.
    2. Seleccione el usuario que puede dar su consentimiento para este ámbito. La opción predeterminada es Solo administradores.
    3. Introduzca el nombre para mostrar del consentimiento del administrador. Este campo es obligatorio.
    4. Introduzca la descripción para el consentimiento del administrador. Este campo es obligatorio.
    5. Introduzca el nombre para mostrar del consentimiento del usuario.
    6. Introduzca la descripción del consentimiento del usuario.
    7. Seleccione la opción Habilitado para el estado.
    8. Seleccione Agregar ámbito.

    Aparece un mensaje en el explorador que indica que se ha agregado el ámbito.

    Se ha agregado un mensaje de ámbito

    El nuevo ámbito definido se muestra en la página.

    Captura de pantalla que muestra un ejemplo del ámbito agregado a la aplicación en Azure Portal.

Configuración de la aplicación cliente autorizada

  1. Desplácese por la página Exponer una API hasta la sección Aplicación cliente autorizada, y seleccione + Agregar una aplicación cliente.

    A aplicación cliente autorizada

    Aparece la página Agregar una aplicación cliente.

  2. Escriba el identificador de cliente de Microsoft 365 adecuado para las aplicaciones que desea autorizar para la aplicación web de la aplicación.

    Captura de pantalla que muestra la opción Id. de cliente y Ámbitos autorizados para agregar una aplicación cliente a la aplicación en Azure Portal. Adición de una aplicación cliente

    Nota:

    • Los identificadores de cliente de Microsoft 365 para aplicaciones móviles, de escritorio y web para Teams son los identificadores reales que debe agregar.
    • Para una aplicación de extensión de mensajes basada en API de Teams, necesita Web o SPA, ya que no puede tener una aplicación cliente de escritorio o móvil en Teams.

    1. Seleccione uno de los siguientes identificadores de cliente:

      Usar Id. de cliente Para autorizar...
      1fec8e78-bli4-4aaf-ab1b-5451cc387264 Aplicación móvil o de escritorio de Teams
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Aplicación web de Teams

    2. Seleccione el URI de identificador de aplicación que creó para la aplicación en Ámbitos autorizados para agregar el ámbito a la API web que ha expuesto.

    3. Seleccione Agregar aplicación.

      Aparece un mensaje en el explorador que indica que se ha agregado la aplicación cliente autorizada.

      Se ha agregado un mensaje a la aplicación cliente

      El identificador de cliente de la aplicación autorizada se muestra en la página.

      Aplicación cliente agregada y mostrada

Nota:

Puede autorizar más de una aplicación cliente. Repita los pasos de este procedimiento para configurar otra aplicación cliente autorizada.

Ha configurado correctamente el ámbito de la aplicación, los permisos y las aplicaciones cliente. Asegúrese de anotar y guardar el URI del identificador de aplicación. A continuación, configure la versión del token de acceso.

Actualizar el manifiesto de la aplicación

Nota:

webApplicationInfo se admite en la versión 1.5 o posterior del manifiesto de la aplicación.

Actualice las siguientes propiedades en el archivo de manifiesto de la aplicación:

  • webApplicationInfo: habilita el inicio de sesión único para la aplicación para ayudar a los usuarios de la aplicación a acceder a la aplicación de extensión de mensajes basada en API sin problemas. sección, que contiene detalles cruciales sobre la aplicación. El URI del identificador de aplicación que registró en Microsoft Entra ID está configurado con el ámbito de la API que ha expuesto. Configure el URI de subdominio de la aplicación en resource para asegurarse de que la solicitud de autenticación que usa getAuthToken() procede del dominio especificado en el manifiesto de la aplicación. Para obtener más información, consulte webApplicationInfo.

      Captura de pantalla que muestra la configuración del manifiesto de la aplicación.

  • microsoftEntraConfiguration: habilita la autenticación de inicio de sesión único para la aplicación. Configure la supportsSingleSignOn propiedad para true admitir el inicio de sesión único y reducir la necesidad de varias autenticaciones.

Para configurar el manifiesto de aplicación:

  1. Abra el proyecto de aplicación de extensión de mensajes basado en API.

  2. Abra la carpeta del manifiesto de la aplicación.

    Nota:

  3. Abrir el manifest.json archivo

  4. Agregue el siguiente fragmento de código al archivo de manifiesto de la aplicación:

    WebApplicationInfo

    "webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}

    donde,

    • {Microsoft Entra AppId}es el identificador de aplicación que creó al registrar la aplicación en Microsoft Entra ID. Es el GUID.
    • subdomain.example.comes el URI del identificador de aplicación que registró al crear el ámbito en Microsoft Entra ID.

    MicrosoftEntraConfiguration

    "authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

  5. Actualice la URL del subdominio en las propiedades siguientes:

    1. contentUrl
    2. configurationUrl

  6. Guarde el archivo de manifiesto de la aplicación.

Para obtener más información, vea composeExtensions.commands.

Autenticación del token

Cuando la extensión de mensaje llama a la API durante la autenticación, recibe una solicitud con el token de autenticación del usuario (token de AED). A continuación, la extensión de mensaje agrega el token en el encabezado de autorización de la solicitud HTTP saliente. El formato de encabezado es Authorization: Bearer <token_value>. Por ejemplo, cuando una extensión de mensaje realiza una llamada API a un servicio que requiere autenticación. La extensión crea una solicitud HTTP de la siguiente manera:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Una vez que la extensión de mensaje basada en API obtiene un encabezado de solicitud con token, realice los pasos siguientes:

  • Autenticar: compruebe el token de las notificaciones de audiencia, ámbito, emisor y firma para comprobar si el token es para la aplicación.

    A continuación se muestra un ejemplo de un token web JSON (JWT) con un encabezado y una respuesta:

    {
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

  • Usar el token: extraiga la información de usuario del token, como el nombre, el correo electrónico y el identificador de objeto, y use el token para llamar a la propia API de la aplicación de extensión de mensaje.

    Nota:

    La API recibe un token de Microsoft Entra con el ámbito establecido access_as_user en como registrado en el Azure Portal. Sin embargo, el token no está autorizado para llamar a ninguna otra API de bajada, como Microsoft Graph.


Solución de problemas

  • Si recibe un mensaje de error de análisis de manifiestos al cargar la aplicación en los equipos, use el validador de aplicaciones de Teams para validar el paquete de la aplicación, incluidos el manifiesto de la aplicación y el archivo de especificación de OpenAPI. Revise el manifiesto de la aplicación y los requisitos del documento Descripción de OpenAPI para resolver errores o advertencias e intente cargar la aplicación.

    Captura de pantalla que muestra el mensaje de error al cargar una aplicación en Teams junto con la opción de copiar los detalles del error en el Portapapeles.

  • Si encuentra algún problema al ejecutar la aplicación en Teams, siga estos pasos para identificar y resolver el problema:

    • Red: seleccione la pestaña Red en Herramientas de desarrollo para inspeccionar la actividad de red.

      1. Abra el cliente web de Teams.

      2. Inicie sesión con sus credenciales de Microsoft 365.

      3. Vaya a un chat y ejecute la aplicación de extensión de mensajes.

      4. En la parte superior derecha, seleccione Configuración y mucho más (...). Vaya a Más herramientas>Herramientas de desarrollo.

      5. Seleccione Red. Seleccione la opción de filtro y escriba invoke en el campo de búsqueda.

      6. Seleccione un error de la lista.

      7. En el panel derecho, seleccione la pestaña Respuesta .

      8. Se muestra un objeto JSON que representa una respuesta de error de un servicio o API. Contiene un standardizedError objeto con errorCode, errorSubCodey errorDescription, que tienen más detalles sobre el error.

        Capturas de pantalla que muestran la pestaña de red, la lista de errores de invocación y los detalles del error en la pestaña respuesta de Herramientas de desarrollo mientras se ejecuta una extensión de mensaje en Teams y se obtiene un error.

      Respuestas de error HTTP comunes:

      • Puede producirse un error de solicitud incorrecta 400 si falta un parámetro de solicitud o tiene un formato incorrecto.
      • Un error 401 No autorizado o 403 Prohibido sugiere problemas con la clave de API, como que falta o no está autorizada.
      • Un error interno del servidor 500 indica que el servicio no sabe cómo responder, debido a un problema del lado servidor.

  • Solución de problemas con herramientas: si la información del seguimiento de red es insuficiente, puede crear una solicitud siguiendo el documento de descripción de OpenAPI y usar herramientas como Swagger Editor o Postman para probar la solicitud, incluido el encabezado de autorización de la clave de API si es necesario.

Si no puede resolver los errores, se recomienda ponerse en contacto con el soporte técnico del producto de Microsoft Teams para obtener más ayuda.