Travailler avec les actions universelles pour les cartes adaptatives

  • Article

Les actions universelles pour Cartes adaptatives permettent d’implémenter des scénarios basés sur des cartes adaptatives pour Teams et Outlook. Ce document traite des rubriques suivantes :

Guide de démarrage rapide pour utiliser les actions universelles pour Cartes adaptatives dans Teams

  1. Remplacez toutes les instances de Action.Submit par Action.Execute pour mettre à jour un scénario existant sur Teams.

  2. Ajoutez une clause refresh à votre carte adaptative, si vous souhaitez utiliser le modèle d’actualisation automatique ou si votre scénario nécessite des vues spécifiques à l’utilisateur.

    Remarque

    Spécifiez la userIds propriété pour identifier les utilisateurs qui reçoivent les mises à jour automatiques.

  3. Gérez adaptiveCard/action appeler des requêtes dans votre bot.

  4. Utilisez le contexte de la demande d’appel pour répondre avec des cartes créées pour un utilisateur.

    Remarque

    Chaque fois que votre bot retourne une nouvelle carte suite au traitement d’un Action.Execute, la réponse doit être conforme au format de réponse.

Schéma des actions universelles pour Cartes adaptatives

Les actions universelles pour les cartes adaptatives sont introduites dans le schéma cartes adaptatives version 1.5. Pour utiliser efficacement la carte adaptative, la version propriété de votre carte adaptative doit être définie sur 1,5.

Remarque

La définition de la version propriété sur 1.5 rend votre carte adaptative incompatible avec les clients plus anciens des plateformes ou des applications, comme Outlook et Teams, car ils ne prennent pas en charge les actions universelles pour les cartes adaptatives.

Si vous définissez la version carte sur une version inférieure à 1.5 et que vous utilisez l’une ou les deux, refresh propriété et Action.Execute, les opérations suivantes se produisent :

Client Comportement
Équipes Votre carte cesse de fonctionner. La carte n’est pas actualisée et Action.Execute ne s’affiche pas en fonction de la version du client Teams. Pour garantir une compatibilité maximale dans Teams, définissez Action.Execute avec une classe Action.Submit dans la propriété de secours.

Pour plus d’informations sur la prise en charge des clients plus anciens, consultez compatibilité descendante.

Exécution d’action

Lors de la création de Cartes adaptatives, remplacez Action.Submit et Action.Http par Action.Execute. Le schéma de Action.Execute est similaire à celui de Action.Submit.

Pour plus d’informations, consultez Schéma d’exécution et propriétés.

À présent, vous pouvez utiliser le modèle d’actualisation pour permettre à Cartes adaptatives de se mettre à jour automatiquement.

Actualiser le modèle

Pour actualiser automatiquement votre carte adaptative, définissez sa propriété refresh, qui incorpore une action de type Action.Execute et un tableau userIds.

Pour plus d’informations, consultez actualiser le schéma et les propriétés.

ID d’utilisateur en cours d’actualisation

Voici les fonctionnalités des UserIds en cours d’actualisation :

  • UserIds est un tableau de MRIS utilisateur, qui fait partie de la propriété refresh dans Cartes adaptatives.

  • Si la userIds propriété list est spécifiée comme userIds: [] dans la section refresh du carte, le carte n’est pas automatiquement actualisé. Au lieu de cela, une option Carte d’actualisation s’affiche pour l’utilisateur dans le menu à trois points dans le client web ou le bureau Teams et dans le menu contextuel appuyez longuement dans Teams mobile, c’est-à-dire Android ou iOS pour actualiser manuellement le carte. Vous pouvez également choisir d’ignorer userIds complètement la propriété refresh au cas où le scénario implique <=60 membres dans les conversations ou canaux de groupe Teams. Le client Teams appelle automatiquement des appels d’actualisation pour tous les utilisateurs si le groupe ou le canal a <=60 utilisateurs.

  • La propriété UserIds est ajoutée, car les canaux dans Teams peuvent inclure un grand nombre de membres. Si tous les membres consultent le canal en même temps, une actualisation automatique inconditionnelle entraîne de nombreux appels simultanés au bot. La propriété userIds doit toujours être incluse pour identifier les utilisateurs qui doivent recevoir une actualisation automatique avec un maximum de 60 (soixante) MRI utilisateur.

  • Vous pouvez récupérer les MRIS utilisateur du membre de conversation Teams. Pour plus d’informations sur l’ajout de la liste userIds dans la section Actualiser de la carte adaptative, consultez récupérer la liste ou le profil utilisateur.

Vous pouvez obtenir le MRI utilisateur pour le canal, la conversation de groupe ou la conversation privée à l’aide de l’exemple suivant :

  1. Utilisation de TurnContext

    userMRI= turnContext.Activity.From.Id

  2. Utilisation de la méthode GetMemberAsync

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

  • L’exemple d’utilisateur Teams EST 29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk

Remarque

La propriété userIds est ignorée dans Outlook, et la propriété refresh est toujours activée automatiquement. Il n’existe aucun problème de mise à l’échelle dans Outlook, car les utilisateurs consultent la carte à des moments différents.

L’étape suivante consiste à utiliser l’activité adaptiveCard/action appeler pour comprendre quelle demande doit être effectuée après l’exécution de Action.Execute.

adaptiveCard/action appeler l’activité

Quand Action.Execute est exécuté dans le client, un nouveau type d’activité Invoke adaptiveCard/action est créé pour votre bot.

Pour plus d’informations, consultez format de requête et propriétés d’une activité d’invocation classique adaptiveCard/action.

Pour plus d’informations, consultez format de réponse et propriétés d’une activité d’invocation classiqueadaptiveCard/action avec des types de réponse pris en charge.

Ensuite, vous pouvez appliquer la compatibilité descendante aux clients plus anciens sur différentes plateformes et rendre votre carte adaptative compatible.

Compatibilité descendante

Les actions universelles pour Cartes adaptatives vous permettent de définir des propriétés qui permettent la compatibilité descendante avec les versions antérieures d’Outlook et teams.

Teams

Pour garantir la compatibilité descendante de votre Cartes adaptatives avec les versions antérieures de Teams, vous devez inclure la propriété fallback et définir sa valeur sur Action.Submit. En outre, votre code de bot doit traiter Action.Execute et Action.Submit.

Pour plus d’informations, voir Considérations relatives à la compatibilité descendante.

Exemples de code

Exemple de nom Description .NET Node.js Manifeste
Bot de traiteur Teams Cet exemple montre un bot qui accepte la commande alimentaire à l’aide de cartes adaptatives. View N/A N/A
Flux de travail séquentiels Cartes adaptatives Cet exemple illustre l’implémentation des flux de travail séquentiels, des vues spécifiques à l’utilisateur et des cartes adaptatives actuelles dans les bots. View View View

Voir aussi