Trabajar con Acciones universales para tarjetas adaptables

  • Artículo

Las acciones universales para tarjetas adaptables proporcionan una manera de implementar escenarios basados en tarjeta adaptable para Teams y Outlook. En este documento se tratan los temas siguientes:

Guía de inicio rápido para usar las acciones universales para tarjetas adaptables en Teams

  1. Reemplace todas las instancias de Action.Submit con Action.Execute para actualizar un escenario existente en Teams.

  2. Agregue una cláusula refresh a su tarjeta adaptable si quiere usar el modelo de actualización automática o si su escenario requiere vistas específicas del usuario.

    Nota:

    Especifique la userIds propiedad para identificar qué usuarios obtienen actualizaciones automáticas.

  3. Controle adaptiveCard/action las solicitudes de invocación en su bot.

  4. Use el contexto de la solicitud de invocación para responder con tarjetas creadas para un usuario.

    Nota:

    Cada vez que el bot devuelve una nueva tarjeta como resultado del procesamiento de un Action.Execute, la respuesta debe ajustarse al formato de respuesta.

Esquema para acciones universales para tarjetas adaptables

Las acciones universales para tarjetas adaptables se introducen en la versión 1.5 del esquema de tarjetas adaptables. Para usar la tarjeta adaptable de forma eficaz, la propiedad de la version tarjeta adaptable debe establecerse en 1.5.

Nota:

Establecer la version propiedad en 1.5 hace que la tarjeta adaptable sea incompatible con clientes anteriores de las plataformas o aplicaciones, como Outlook y Teams, ya que no admiten las acciones universales para tarjetas adaptables.

Si establece la versión de la tarjeta en menos de 1.5 y usa o ambas, refresh la propiedad y Action.Execute, sucede lo siguiente:

Cliente Comportamiento
Teams Su tarjeta deja de funcionar. La tarjeta no se actualiza y Action.Execute no se representa en función de la versión del cliente de Teams. Para garantizar la máxima compatibilidad en Teams, defina Action.Execute con una Action.Submit en la propiedad de reserva.

Para obtener más información sobre cómo admitir clientes más antiguos, consulte compatibilidad con versiones anteriores.

Action.Execute

Al crear tarjetas adaptables, reemplace Action.Submit y Action.Http por Action.Execute. El esquema paraAction.Execute es similar al de Action.Submit.

Para obtener más información, consulteesquema Action.Execute y propiedades.

Ahora, puede usar el modelo de actualización para permitir que las tarjetas adaptables se actualicen automáticamente.

Actualizar modelo

Para actualizar automáticamente la tarjeta adaptable, defina su propiedad, refreshque inserta una acción del tipo Action.Execute y una matrizuserIds.

Para obtener más información, consulteactualizar esquema y propiedades.

Identificadores de usuario en la actualización

Estas son las características de UserIds en la actualización:

  • UserIds es una matriz de MRI de usuario, que forma parte de la propiedad refresh en Tarjetas adaptables.

  • Si la userIds propiedad list se especifica como userIds: [] en la sección de actualización de la tarjeta, la tarjeta no se actualiza automáticamente. En su lugar, se muestra una opción Actualizar tarjeta al usuario en el menú de puntos triples del cliente web o escritorio de Teams y en el menú contextual de prensa larga en Teams mobile, es decir, Android o iOS para actualizar manualmente la tarjeta. Como alternativa, puede optar por omitir userIds por completo la propiedad de actualización en caso de que el escenario implique <=60 miembros en los canales o chats de grupo de Teams. El cliente de Teams invoca automáticamente llamadas de actualización para todos los usuarios si el grupo o canal tiene <=60 usuarios.

  • Se ha agregado la propiedad UserIds porque los canales de Teams pueden incluir un gran número de miembros. Si todos los miembros ven el canal al mismo tiempo, una actualización automática incondicional da como resultado muchas llamadas simultáneas al bot. La propiedad userIds siempre debe incluirse para identificar qué usuarios deben obtener una actualización automática con un máximo de 60 (sesenta) MRI de usuario.

  • Puede capturar las MRI de usuario del miembro de conversación de Teams. Para obtener más información sobre cómo agregar en la lista userIds en la sección de actualización de la tarjeta adaptable, consulte captura de la lista o el perfil de usuario.

Puede obtener la MRI del usuario para el canal, el chat de grupo o el chat 1:1 mediante el ejemplo siguiente:

  1. Uso de TurnContext

    userMRI= turnContext.Activity.From.Id

  2. Uso del método GetMemberAsync

    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);var userMRI = member.Id;

  • Un ejemplo de MRI de usuario de Teams es29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk

Nota:

La propiedad userIds se omite en Outlook y la propiedad refresh siempre se activa automáticamente. No hay ningún problema de escala en Outlook porque los usuarios ven la tarjeta en momentos diferentes.

El siguiente paso consiste en usaradaptiveCard/actionla actividad de invocación para comprender qué solicitud se debe realizar luego de que Action.Executees ejecutado.

adaptiveCard/action invocar actividad

Cuando se ejecuta Action.Execute en el cliente, se realiza un nuevo tipo de actividad Invoke adaptiveCard/action en su bot.

Para obtener más información, consulteel formato de solicitud y las propiedades de una típica adaptiveCard/actionactividad de invocación .

Para obtener más información, consulteel formato de respuesta y las propiedades de una típica adaptiveCard/actionactividad de invocación con los tipos de respuesta admitidos.

A continuación, puede aplicar compatibilidad con versiones anteriores a clientes más antiguos en distintas plataformas y hacer que la tarjeta adaptable sea compatible.

Compatibilidad con versiones anteriores

Las acciones universales para tarjetas adaptables le permiten establecer propiedades que permiten la compatibilidad con versiones anteriores de Outlook y Teams.

Teams

Para garantizar la compatibilidad de versiones anteriores de sus tarjetas adaptables con versiones anteriores de Teams, debe incluir la propiedad fallback y establecer su valor en Action.Submit. Además, el código de su bot debe procesar tantoAction.Execute como Action.Submit.

Para obtener más información, consulte compatibilidad con versiones anteriores en Teams.

Ejemplos de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Bot de servicio de alimentos de Teams En este ejemplo se muestra un bot que acepta el pedido de alimentos mediante tarjetas adaptables. View ND ND
Tarjetas adaptables de flujos de trabajo secuenciales En este ejemplo se muestra la implementación de flujos de trabajo secuenciales, vistas específicas del usuario y tarjetas adaptables actuales en bots. View View Ver

Consulte también