Modèles de réponse de carte adaptative pour les plug-ins d’API pour Microsoft 365 Copilot

Les plug-ins d’API peuvent utiliser des modèles de réponse de carte adaptative pour améliorer la réponse que Microsoft 365 Copilot génère en fonction de la réponse qu’il reçoit de l’API. La carte adaptative affiche les citations dans la réponse générée.

Les plug-ins d’API peuvent définir un modèle de réponse Adaptive Card de deux manières : en tant que modèle statique défini dans le manifeste du plug-in ou en tant que modèle dynamique renvoyé dans le cadre de la réponse de l’API. Les développeurs de plug-ins définissent des modèles en utilisant le schéma Adaptive Card en combinaison avec le langage de modèle Cartes adaptatives.

Modèles de réponse statiques

Les modèles de réponse statiques sont un bon choix si votre API renvoie toujours des éléments du même type et que le format de la carte adaptative n’a pas besoin de changer souvent. Définissez un modèle statique dans la propriété de l’objet static_templateresponse_semantics dans le manifeste du plug-in, comme illustré dans l’exemple suivant.

"functions": [
  {
    "name": "GetBudgets",
    "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
    "capabilities": {
      "response_semantics": {
        "data_path": "$",
        "properties": {
          "title": "$.name",
          "subtitle": "$.availableFunds"
        },
        "static_template": {
          "type": "AdaptiveCard",
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "version": "1.5",
          "body": [
            {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Name: ${if(name, name, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
                  "wrap": true
                }
              ]
            }
          ]
        }
      }
    }
  },
]

• Définissez la response_semantics.data_path propriété sur . This value is a [JSONPath query](https://www.rfc-editor.org/rfc/rfc9535) that indicates that the root of the JSON response contains the relevant data. The static_template.body["$data"]property value is${$root}, which is Adaptive Card template language syntax to override any prior data scoping and break back to the root. Setting this value isn't strictly needed, since the data_path' est déjà définie à la racine.
• La text propriété de la première TextBlock utilise la syntaxe ${if(name, name, 'N/A')}du modèle de carte adaptative. Cela fait référence à la name propriété dans la réponse de l’API. La if fonction spécifie que si name a une valeur, utilisez cette valeur, sinon, utilisez N/A.
• La text propriété de la seconde TextBlock utilise la syntaxe ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}du modèle de carte adaptative. Cela fait référence à la availableFunds propriété dans la réponse de l’API. La formatNumber fonction affiche le nombre dans une chaîne avec deux décimales.

Considérez ce modèle statique et la réponse API suivante.

[
    {
        "name": "Fourth Coffee lobby renovation",
        "availableFunds": 12000
    }
]

Cette combinaison donne la carte adaptative suivante.

Modèles de réponse dynamique

Les modèles de réponse dynamique sont un bon choix si votre API retourne plusieurs types. Avec les modèles dynamiques, vous pouvez attribuer un modèle de réponse à chaque élément renvoyé. Un ou plusieurs modèles dynamiques sont renvoyés dans le cadre de la réponse de l’API et les éléments de données de la réponse indiquent quel modèle utiliser.

Pour utiliser des modèles dynamiques, indiquez quelle propriété sur les éléments de données spécifie le modèle dans la response_semantics.properties.template_selector propriété dans le manifeste du plug-in d’API, comme illustré dans cet exemple.

{
  "name": "GetTransactions",
  "description": "Returns details of transactions identified from filters like budget name or category. Multiple filters can be used in combination to refine the list of transactions returned",
  "capabilities": {
    "response_semantics": {
      "data_path": "$.transactions",
      "properties": {
        "template_selector": "$.displayTemplate"
      }
    }
  }
}

Dans cet exemple, la data_path propriété est définie sur $.transactions, ce qui indique que les données des cartes se trouvent dans la transactions propriété à la racine de la réponse de l’API. La template_selector propriété est définie sur $.displayTemplate, indiquant que la propriété de chaque élément du transactions tableau qui spécifie le modèle à utiliser est la displayTemplate propriété.

La propriété indiquée par la template_selector propriété contient une requête JSONPath pour localiser le modèle de l’élément dans la réponse.

Considérez ce modèle et la réponse API suivante.

{
  "transactions": [
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -2000,
      "description": "Property survey for permit application",
      "expenseCategory": "permits",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -7200,
      "description": "Lumber and drywall for lobby",
      "expenseCategory": "materials",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": 5000,
      "description": "Additional funds to cover cost overruns",
      "expenseCategory": null,
      "displayTemplate": "$.templates.credit"
    }
  ],
  "templates": {
    "debit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "attention",
          "text": "Debit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Category",
              "value": "${if(expenseCategory, expenseCategory, 'N/A')}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    },
    "credit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "good",
          "text": "Credit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    }
  }
}

• La transactions propriété de la réponse contient un tableau d’éléments.
• La templates propriété est un objet, chaque propriété de cet objet contenant un modèle de carte adaptative.
• Le displayTemplate sur chaque objet du transactions tableau est défini sur soit $.templates.debit ou $.templates.credit.

La combinaison de ce manifeste de plug-in et de la réponse de l’API entraîne les cartes adaptatives suivantes.

Éviter les cartes adaptatives vides lorsqu’un tableau dans la réponse API est vide

Les cartes adaptatives peuvent être rendues vides lorsqu’une propriété de tableau dans la réponse de l’API est vide et que le modèle n’inclut pas de logique conditionnelle pour gérer ce scénario.

L’exemple suivant montre une réponse d’API où le recommendations tableau ne contient aucun élément :

{"answer":"","recommendations":[],"followUpMessage":""}

Dans ce cas :

1. Le tableau de recommandations n’comporte aucun élément.
2. Le modèle Carte adaptative tente d’itérer sur le tableau sans vérifier si les données sont disponibles.

Pour éviter le rendu d’une carte vierge, liez le modèle à la propriété de tableau correcte et ajoutez une logique conditionnelle pour contrôler le rendu.

Lier au tableau à l’aide de data_path:

"data_path": "$.recommendations"

Itérer sur les objets uniquement lorsque les données existent :

{ "type": "ColumnSet", "$data": "${$root}", "$when": "${title != null && title != ''}" }

Si vous le souhaitez, fournissez un texte de secours lorsque le tableau est vide :

{ "type": "TextBlock", "text": "No recommendations available", "$when": "${length($root) == 0}" }

Utilisation conjointe de modèles statiques et dynamiques

Les plugins peuvent combiner l’utilisation de modèles statiques et dynamiques. Dans ce scénario, le modèle statique fait office de modèle par défaut utilisé si l’élément n’a pas la template_selector propriété présente ou si sa valeur n’est pas résolue en modèle dans la réponse API.

Ajouter des domaines à votre manifeste d’application

Ajoutez tous les domaines utilisés par votre carte adaptative à la section validDomains du manifeste de votre application.

• Lorsque vous utilisez Action.OpenUrl, veillez à inclure le domaine de l’URL cible dans la validDomains propriété. Si le domaine n’est pas répertorié, Teams affiche le message que l’URL peut conduire à un contenu non approuvé.
• Les URL d’image que votre plug-in API ou agent déclaratif retourne dans une réponse Adaptive Card doivent avoir leur domaine répertorié dans la validDomains propriété. Si le domaine n’est pas répertorié, Microsoft 365 Copilot ne restitue pas l’image.

Garantir des cartes adaptatives réactives dans les hubs Microsoft 365 Copilot

Les cartes adaptatives doivent être conçues pour être réactives sur différentes tailles de surface. Cette conception garantit une expérience utilisateur transparente, quel que soit l’appareil ou la plateforme utilisée. Pour atteindre cet objectif, validez les cartes adaptatives sur différents hubs Microsoft 365 Copilot, notamment Teams, Word et PowerPoint. Validez également différentes largeurs de fenêtre d’affichage en contractant et en développant l’interface utilisateur Copilot. Ce processus garantit que les cartes adaptatives fonctionnent de manière optimale et offrent une expérience cohérente sur toutes les plateformes. Appliquez les bonnes pratiques suivantes :

• Évitez d’utiliser des dispositions à plusieurs colonnes autant que possible. Les dispositions à colonne unique ont tendance à bien s’afficher, même avec les largeurs de fenêtre d’affichage les plus étroites.
• Évitez de placer des éléments de texte et d’image dans la même ligne, sauf si l’image est une petite icône ou un avatar.
• Évitez d’attribuer une largeur fixe aux éléments de la carte adaptative ; Autorisez-les plutôt à se redimensionner en fonction de la largeur de la fenêtre d’affichage. Vous pouvez toutefois attribuer une largeur fixe aux petites images telles que les icônes et les avatars.

Contenu connexe

• Adaptive Card Designer pour concevoir et tester des cartes adaptatives dans un outil visuel.
• Documentation sur les cartes adaptatives
• Référence du manifeste du plug-in