Kits SDK de création de modèles de cartes adaptatives
Article
Les kits SDK de création de modèles de cartes adaptatives facilitent le remplissage d’un modèle de carte avec des données réelles sur n’importe quelle plateforme prise en charge.
Changements cassants dans la version RC (Release Candidate) de mai 2020
Nous avons travaillé dur à la publication des modèles et nous sommes dans la dernière ligne droite ! Nous avons dû apporter des modifications mineures avant de finaliser la version.
Changements cassants de mai 2020
La syntaxe de liaison a changé et passe de {...} à ${...}.
Par exemple : "text": "Hello {name}" devient "text": "Hello ${name}"
L’API JavaScript ne contient plus d’objet EvaluationContext. Passez simplement vos données à la fonction expand. Consultez la page du SDK pour obtenir les détails complets.
L’API .NET a été reconçue pour correspondre davantage à l’API JavaScript. Vous trouverez des informations détaillées ci-dessous.
JavaScript
La bibliothèque adaptivecards-Templating est disponible sur npm et par le biais de CDN. Suivez le lien du package pour obtenir une documentation complète.
L’exemple ci-dessous part du principe que vous avez également installé la bibliothèque adaptivecards pour afficher la carte.
Si vous n’envisagez pas d’afficher la carte, vous pouvez supprimer le code parse et render.
import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
// Define a template payload
var templatePayload = {
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Hello ${name}!"
}
]
};
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
$root: {
name: "Matt Hidinger"
}
});
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());
.NET
dotnet add package AdaptiveCards.Templating
Usage
// Import the library
using AdaptiveCards.Templating;
var templateJson = @"
{
""type"": ""AdaptiveCard"",
""version"": ""1.2"",
""body"": [
{
""type"": ""TextBlock"",
""text"": ""Hello ${name}!""
}
]
}";
// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);
// You can use any serializable object as your data
var myData = new
{
Name = "Matt Hidinger"
};
// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);
Fonctions personnalisées
Les fonctions personnalisées peuvent être ajoutées à la bibliothèque d’expressions adaptatives, en plus des fonctions prédéfinies.
Dans l’exemple ci-dessous, la fonction personnalisée stringFormat est ajoutée, et elle est utilisée pour la mise en forme d’une chaîne.
string jsonTemplate = @"{
""type"": ""AdaptiveCard"",
""version"": ""1.0"",
""body"": [{
""type"": ""TextBlock"",
""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
}]
}";
string jsonData = @"{
""strings"": {
""myName"": ""My name is {0} {1}""
},
""person"": {
""firstName"": ""Andrew"",
""lastName"": ""Leader""
}
}";
AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);
var context = new EvaluationContext
{
Root = jsonData
};
// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
string formattedString = "";
// argument is packed in sequential order as defined in the template
// For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
// args will have following entries
// args[0]: strings.myName
// args[1]: person.firstName
// args[2]: strings.lastName
if (args[0] != null && args[1] != null && args[2] != null)
{
string formatString = args[0];
string[] stringArguments = {args[1], args[2] };
formattedString = string.Format(formatString, stringArguments);
}
return formattedString;
});
string cardJson = template.Expand(context);
Résolution des problèmes
Q. Pourquoi une exception AdaptiveTemplateException est-elle levée lorsque j’appelle expand() ?
A. Si votre message d’erreur ressemble à « <offending item>' at line, '<line number>' is malformed for '$data : ' pair » (<élément problématique> à la ligne est incorrect pour $data : pair).
Vérifiez que la valeur fournie pour « $data » correspond à du code JSON valide, tel qu’un nombre, une valeur booléenne, un objet ou un tableau, que la syntaxe est correcte pour le langage AEL, et que l’entrée existe dans le contexte de données au numéro de ligne indiqué.
Q. Pourquoi une exception ArgumentNullException est-elle levée lorsque j’appelle expand() ?
A. Si votre message d’erreur ressemble à « Check if parent data context is set, or please enter a non-null value for '<offending item>' at line, '<line number> » (Vérifiez si le contexte de données parent est défini ou entrez une valeur non nulle pour <élément problématique> à la ligne ).
Celui-ci indique qu’il n’existe aucun contexte de données pour la liaison de données demandée. Vérifiez que le contexte de données racine est défini, le cas échéant, et vérifiez qu’un contexte de données est disponible pour la liaison actuelle, comme indiqué par le numéro de ligne.
Q. Pourquoi le format de date/heure dans la RFC 3389, par ex. « 2017-02-14T06:08:00Z », ne fonctionne pas avec les fonctions TIME/DATE quand il est utilisé avec le modèle ?
A. Le SDK .NET nuget version 1.0.0-rc.0 expose ce comportement. Ce comportement est corrigé dans les prochaines mises en production. Le comportement par défaut du désérialiseur json.Net change la chaîne au format date/heure et est désactivé dans les prochaines mises en production. Utilisez la fonction formatDateTime() pour mettre en forme la chaîne date/heure dans la RFC 3389, comme montré dans cet exemple, ou vous pouvez contourner les fonctions TIME/DATE et utiliser juste formatDateTime(). Pour plus d’informations sur formatDateTime(), rendez-vous ici.
Découvrez comment améliorer l’expérience utilisateur des agents déclaratifs à l’aide de cartes adaptatives pour afficher visuellement les données d’API. Créez et configurez des modèles de carte adaptative, intégrez-les dans des plug-ins d’API et testez la configuration dans Microsoft 365 Copilot. Découvrez les étapes pratiques pour créer et afficher un aperçu des cartes adaptatives dans Visual Studio Code.