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

Importante

Les plug-ins d’API sont uniquement pris en charge en tant qu’actions au sein d’agents déclaratifs. Ils ne sont pas activés dans 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 générée par Microsoft 365 Copilot en fonction de la réponse reçue 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 de carte adaptative de deux manières : en tant que modèle statique défini dans le manifeste du plug-in d’API, ou en tant que modèle dynamique retourné dans le cadre de la réponse de l’API. Les développeurs de plug-in ont défini des modèles à l’aide du schéma de carte adaptative en combinaison avec le langage de modèle Cartes adaptatives.

Modèles de réponse statiques

Les modèles de réponse statique sont un bon choix si votre API retourne toujours des éléments du même type et que le format de la carte adaptative n’a pas besoin de changer souvent. Un modèle statique est défini dans la static_template propriété de l’objet response_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
                }
              ]
            }
          ]
        }
      }
    }
  },
]

• La response_semantics.data_path propriété est définie sur $. Cette valeur est une requête JSONPath qui indique que la racine de la réponse JSON contient les données pertinentes.
• La static_template.body["$data"] propriété a la ${$root}valeur , qui est la syntaxe du langage du modèle carte adaptative pour remplacer toute étendue de données antérieure et revenir à la racine. La définition de cette valeur ici n’est pas strictement nécessaire, car est data_path déjà défini sur 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 . Cette propriété 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 . Cette propriété fait référence à la availableFunds propriété dans la réponse de l’API. La formatNumber fonction restitue le nombre en une chaîne avec deux décimales.

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

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

Cette combinaison aboutit à 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 retourné. Un ou plusieurs modèles dynamiques sont retournés dans le cadre de la réponse de l’API, et les éléments de données dans la réponse indiquent le modèle à utiliser.

Pour utiliser des modèles dynamiques, indiquez la propriété sur les éléments de données qui 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 propriété a la data_path valeur $.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é a la $.displayTemplatevaleur , ce qui indique que la propriété sur 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 d’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é dans 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.
• Sur displayTemplate chaque objet du transactions tableau est défini sur $.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.

Utilisation de modèles statiques et dynamiques ensemble

Les plug-ins peuvent combiner l’utilisation de modèles statiques et dynamiques. Dans ce scénario, le modèle statique agit comme un modèle par défaut qui est utilisé si l’élément n’a pas la template_selector propriété présente ou si sa valeur ne se résout pas en modèle dans la réponse de l’API.

Garantir la réactivité des cartes adaptatives sur Microsoft 365 Copilot hubs

Les cartes adaptatives doivent être conçues pour être réactives sur différentes tailles de surface. Cela garantit une expérience utilisateur transparente, quel que soit l’appareil ou la plateforme utilisé. Pour ce faire, veillez à valider les cartes adaptatives sur différents hubs Microsoft 365 Copilot, notamment Teams, Word et PowerPoint, et à valider différentes largeurs de fenêtre d’affichage en sous-traitant et en développant l’interface utilisateur Copilot. Cela garantit que les cartes adaptatives fonctionnent de manière optimale et fournissent une expérience cohérente sur toutes les plateformes. Appliquez les meilleures pratiques suivantes :

• Évitez d’utiliser des dispositions à plusieurs colonnes dans la mesure du possible. Les dispositions à une seule colonne ont tendance à s’afficher correctement même aux 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’affecter une largeur fixe aux éléments de la carte adaptative ; au lieu de cela, autorisez-les à se redimensionner en fonction de la largeur de la fenêtre d’affichage. Toutefois, vous pouvez affecter une largeur fixe à de petites images telles que des icônes et des avatars.

Contenu connexe

• Concepteur de cartes adaptatives pour concevoir et tester des cartes adaptatives dans un outil visuel.
• Documentation sur la carte adaptative
• Informations de référence sur le manifeste du plug-in d’API