Vue d’ensemble du modèle d’action universelle

Article
04/29/2024

Importante

L’intégration de nouveaux fournisseurs de messages actionnables avec une étendue globale est temporairement suspendue jusqu’au 30 juin 2024 en raison de mises à niveau du service. Les fournisseurs globaux existants et l’intégration des fournisseurs d’étendue d’organisation et de test ne sont pas affectés. Pour plus d’informations, consultez Forum aux questions sur les messages actionnables.

Les cartes adaptatives sont des extraits de code d’interface utilisateur indépendants de la plateforme, créés à l’aide d’un format JSON léger, que les applications et les services peuvent partager. Les cartes adaptatives s’adaptent non seulement à l’apparence de l’hôte, mais fournissent également des fonctionnalités d’interaction enrichies.

À mesure que les cartes adaptatives ont gagné en popularité, différents hôtes ont commencé à prendre en charge différents modèles d’action, ce qui a entraîné une fragmentation. Pour résoudre ce problème, les équipes Teams, Outlook et Cartes adaptatives ont travaillé à la création d’un modèle d’action bot universel compatible entre les hôtes. Cet effort a conduit à ce qui suit :

La généralisation des bots et du Bot Framework comme moyen d’implémenter des scénarios basés sur des cartes adaptatives pour Outlook (messages actionnables) et Teams (bots)
Action.Execute pour remplacer les deux Action.Http (actuellement utilisés par les messages actionnables) et Action.Submit (actuellement utilisés par les bots).

Schéma

Importante

Le modèle d’action universel est introduit dans le schéma carte adaptatif version 1.4 et ultérieure. Pour pouvoir utiliser ces nouvelles fonctionnalités, la version propriété de votre carte adaptative doit être définie sur 1.4 ou une version ultérieure, comme indiqué dans les exemples ci-dessous.

Exécution d’action

Lors de la création de cartes adaptatives pour Outlook, utilisez Action.Execute à la place de Action.Http. Voici un exemple de carte adaptatifs utilisant Action.Execute dans la charge utile JSON.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit"
        }
      ]
    }
  ]
}

Propriétés

Propriété	Type	Requis	Description
type	`string`	Oui	Doit être `Action.Execute`.
Verbe	`string`	Non	Chaîne pratique qui peut être utilisée par le développeur pour identifier l’action
data	`string`, `object`	Non	Données initiales avec laquelle les champs d’entrée seront combinés. Il s’agit essentiellement de propriétés masquées.
title	`string`	Non	Étiquette du bouton ou du lien qui représente cette action.
iconUrl	`uri`	Non	Icône facultative à afficher sur l’action conjointement avec le titre. Prend en charge l’URI de données dans les cartes adaptatives version 1.2+
style	`ActionStyle`	Non	Contrôle le style d’une action, qui influence la façon dont l’action est affichée, parlée, etc.
Secours	`<action object>`, `"drop"`	Non	Décrit ce qu’il faut faire quand Action.Execute n’est pas pris en charge par le client affichant le carte.
Exige	`Dictionary<string>`	Non	Série de paires clé/valeur indiquant les fonctionnalités dont l’élément a besoin avec la version minimale correspondante. Lorsqu’une fonctionnalité est manquante ou dont la version est insuffisante, le secours est déclenché.

Mécanisme d’actualisation

Action.ExecuteOutre , un nouveau mécanisme d’actualisation est désormais pris en charge, ce qui permet de créer des cartes adaptatives qui se mettent automatiquement à jour au moment où elles sont affichées. Cela garantit que les utilisateurs voient toujours les données à jour. Pour permettre à une carte adaptative de s’actualiser automatiquement dans Outlook, définissez sa refresh propriété, qui incorpore un action de type Action.Execute.

Propriété	Type	Requis	Description
action	`"Action.Execute"`	Oui	Doit être une action instance de type `"Action.Execute"`.
userIds	`Array<string>`	Oui	Tableau d’identificateur de ressource de message (`MRI`) des utilisateurs pour lesquels l’actualisation automatique doit être activée dans Teams. Pour Teams, reportez-vous aux ID d’utilisateur dans l’actualisation pour en savoir plus. Notez que la `userIds` propriété est ignorée dans Outlook et qu’elle `refresh` est toujours honorée automatiquement.

Exemple JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Compatibilité descendante

Le nouveau Action.Execute modèle d’action universel s’écarte du modèle d’action utilisé dans la Action.Http version carte adaptative inférieure à 1.4, où les actions sont encodées dans la carte adaptative sous forme d’appels HTTP explicites. Le modèle Action.Execute permet aux développeurs d’implémenter des scénarios qui fonctionnent à la fois dans Outlook et Teams. Les scénarios de message actionnables peuvent utiliser le Action.Http modèle ou le nouveau Action.Execute modèle, mais pas les deux. Les scénarios qui utilisent le modèle universel Action.Execute doivent être implémentés en tant que bots et s’abonner au canal Messages actionnables Outlook .

Exemples de code

Une fois que vous avez parcouru la documentation, vous êtes prêt à commencer à essayer avec quelques exemples.

Partager via