Service de modèles de cartes adaptativesAdaptive Cards Template Service

Le service de modèles de cartes adaptatives est un service de preuve de concept qui permet à quiconque de trouver, modifier et partager un ensemble de modèles bien connus.The Adaptive Cards Template Service is a proof-of-concept service that allows anyone to find, contribute to, and share a set of well-known templates.

Il est utile si vous voulez afficher des données sans avoir à écrire une carte adaptative personnalisée pour celles-ci.It's useful if you want to display some data but don't want to bother writing a custom adaptive card for it.

Lisez la vue d’ensemble de la création de modèles de cartes adaptatives.Please read this for an overview of Adaptive Card Templating

Important

Termes et contratTerms and agreement

Ce service de niveau alpha est fourni « en l’état », avec tous ses défauts et sans aucun support.This alpha-level service is provided "as-is", with all faults and is not supported in any way. Toute collecte de données à partir du service est soumise à la déclaration de confidentialité de Microsoft.Any data collection from the service is subject to the Microsoft privacy statement.

Ces fonctionnalités sont en préversion et sujettes à modification.These features are in preview and subject to change. Vos commentaires sont non seulement bienvenus, mais essentiels pour garantir que nous fournissions les fonctionnalités dont vous avez besoin.Your feedback is not only welcome, but critical to ensure we deliver the features you need.

En quoi le service peut-il m’aider ?How does the service help me?

Prenons un exemple : je viens de recevoir des données. Il peut s’agir de données financières, de données Microsoft Graph, de données schema.org ou de données personnalisées provenant de mon organisation.Let's say I just got a piece of data, maybe it's financial data, Microsoft Graph data, schema.org data, or custom data from within my organization.

Je souhaite les présenter à un utilisateur.Now I want to display the data to a user.

Pour cela, je dois normalement écrire un code d’interface utilisateur personnalisé dans toutes les piles front-end que je livre aux utilisateurs finaux.Traditionally that means writing custom UI code in all of the front-end stacks that I deliver to end-users.

Imaginons maintenant un monde dans lequel mon application pourrait « apprendre » de nouveaux modèles d’interface utilisateur en fonction du type de données.But what if there were a world where my app could "learn" new UI templates based on the type of data? Un monde où quiconque pourrait participer à l’élaboration de modèles d’interface utilisateur communs, les améliorer et les partager au sein de leurs propres projets, au sein d’une organisation voire à l’échelle de l’Internet.A world where anyone could contribute, enhance, and share common UI templates, within their own projects, within an organization, or for the entire internet.

Qu’est-ce que le service de modèles de cartes ?What is the card template service?

Le service de modèles de cartes est un point de terminaison REST simple qui vous aide à effectuer les tâches suivantes :The card template service is a simple REST endpoint that helps:

  • Rechercher un modèle en analysant la structure de vos donnéesFind a template by analyzing the structure of your data
  • Obtenir un modèle pour pouvoir le lier directement sur le client sans envoyer vos données au serveur ni quitter l’appareilGet a template so you can bind it directly on the client, without sending your data to the server or ever leaving the device
  • Remplir un modèle sur le serveur quand la liaison de données côté client n’est pas appropriée ou possiblePopulate a template on the server, when client-side data binding isn't appropriate or possible

Derrière tout cela :Behind it all, is:

  • Un dépôt de modèles open source et partagés, basé sur GitHub.A shared, open-source template repository backed by GitHub. (Le dépôt est actuellement privé, mais il sera rendu public dès que nous aurons réglé quelques détails.)(The repo is currently private but will be made public as soon as we tie up some loose ends)
  • Tous les modèles étant des fichiers JSON plats dans le dépôt, les opérations de modification, de contribution et de partage s’inscrivent naturellement dans un workflow de développeur.All the templates are flat JSON files in the repo, which makes editing, contributing, and sharing a natural part of a developer workflow.
  • Vous aurez également accès au code du service pour pouvoir l’héberger là où vous le souhaitez.The code for the service will be made available so you can host wherever makes the most sense to you.

Utilisation du serviceUsing the service

Obtenir tous les modèlesGet all templates

Ce point de terminaison retourne une liste de tous les modèles connus.This endpoint returns a list of all known templates.

HTTP GET https://templates.adaptivecards.io/list

Extrait de la réponseResponse excerpt

{
  "graph.microsoft.com": {
    "templates": [
      {
        "file": "Files.json",
        "fullPath": "graph.microsoft.com/Files.json"
      },
      {
        "file": "Profile.json",
        "fullPath": "graph.microsoft.com/Profile.json"
      }
   ]
}

Trouver un modèleFind a template

Ce point de terminaison tente de trouver un modèle en analysant la structure de vos données.This endpoint tries to find a template by analyzing the structure of your data.

HTTP POST https://templates.adaptivecards.io/find

ExempleExample

Prenons un exemple : je viens d’accéder à un point de terminaison Microsoft Graph pour obtenir des données organisationnelles me concernant.Let's say I access a Microsoft Graph endpoint to get organizational data about me.

HTTP GET https://graph.microsoft.com/v1.0/me/

Capture d’écran de l’Afficheur Graph

Cette API retourne des données JSON, mais comment puis-je les présenter aux utilisateurs au moyen de cartes adaptatives ?That API returned JSON data, but how do I display it to users using Adaptive Cards?

Tout d’abord, je souhaite voir s’il existe un modèle pour ce type de données. J’envoie donc une requête HTTP au point de terminaison /find avec mes données dans POST body.First I want to see if a template exists for this type of data, so I make an HTTP request to the /find endpoint with my data in the POST body.

HTTP POST https://templates.adaptivecards.io/find

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "+1 412 555 0109"
    ],
    "displayName": "Megan Bowen",
    "givenName": "Megan",
    "jobTitle": "Auditor",
    "mail": "MeganB@M365x214355.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": "12/1110",
    "preferredLanguage": "en-US",
    "surname": "Bowen",
    "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
    "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
}

Réponse :Response:

[
  {
    "templateUrl": "graph.microsoft.com/Profile.json",
    "confidence": 1
  }
]

Le service retourne une liste de tous les modèles correspondants, ainsi qu’une valeur confidence indiquant le degré de correspondance.The service returns a list of any matching templates, along with a confidence indicating how close the match is. Je peux à présent utiliser l’URL de ce modèle pour obtenir le modèle ou le remplir côté serveur.Now I can use that template URL to get the template, or populate it server-side.

Obtenir un modèleGet a template

Un modèle récupéré à partir de ce point de terminaison peut être rempli avec des données au moment de l’exécution à l’aide des kits SDK de création de modèles.A template retrieved from this endpoint can be populated with data at runtime using the templatng SDKs.

HTTP GET https://templates.adaptivecards.io/[TEMPLATE-PATH]

Vous pouvez également inclure un « exemple de données » avec le modèle, ce qui rend la modification dans le concepteur plus conviviale :You can also include "sample data" with the template, which makes editing in the designer more friendly:

HTTP GET https://templates.adaptivecards.io/[TEMPLATE-PATH]?sampleData=true

ExempleExample

Nous obtenons le modèle de profil Microsoft Graph retourné par /find ci-dessus.Let's get the Microsoft Graph profile template that was returned from /find above.

HTTP GET https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

Extrait de la réponseResponse excerpt

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "{name}"
    },
    {
        // ...snip
    }
  ]
}

Utilisez maintenant ce modèle avec les kits SDK de création de modèles pour créer une carte adaptative prête pour l’affichage.Now use this template with the templating SDKs to create a ready-to-render Adaptive Card.

Remplir un modèle côté serveurPopulate a template server-side

Dans certains cas, il est inutile de remplir un modèle sur le client.In some cases it may not make sense to populate a template on the client. Vous pouvez alors faire en sorte que le service retourne une carte adaptative entièrement remplie, prête à être passée à n’importe quel renderer de carte adaptative.For these use cases, you can have the service return a fully-populated Adaptive Card, ready to be passed to any Adaptive Card Renderer.

HTTP POST https://templates.adaptivecards.io/[TEMPLATE-PATH]

ExempleExample

Remplissons le modèle de profil Microsoft Graph retourné par /find à l’aide des données ci-dessus.Let's populate the Microsoft Graph profile template that was returned from /find using the data above.

HTTP POST https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "+1 412 555 0109"
    ],
    "displayName": "Megan Bowen",
    "givenName": "Megan",
    "jobTitle": "Auditor",
    "mail": "MeganB@M365x214355.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": "12/1110",
    "preferredLanguage": "en-US",
    "surname": "Bowen",
    "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
    "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
}

Extrait de la réponseResponse excerpt

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "Megan Bowen"
    },
    {
        // ...snip
    }
  ]
}

Notez que la réponse remplace le texte "{name}" du premier TextBlock par "Megan Bowen", comme dans la requête GET.Notice how the response replaced the text of the first TextBlock with "Megan Bowen" instead of "{name}", as in the GET request. Cette carte adaptative peut désormais être passée à n’importe quel renderer de carte adaptative sans passer par la création de modèles côté client.This AdaptiveCard can now be passed to any Adaptive Card renderer without going through client-side templating.

Contribution aux modèlesContributing templates

Les modèles sont hébergés sur GitHub dans le dépôt adaptivecards-templates.The templates are hosted on GitHub in the adaptivecards-templates repo.

Nous espérons que l’utilisation de GitHub comme magasin de stockage pour les modèles nous permettra de « démocratiser » le processus de création, d’amélioration et de partage de modèles.Our hope is that by using GitHub as a backing store for the templates, we can "democratize" the process of authoring, enhancing, and sharing templates. N’importe qui peut envoyer une demande de tirage (pull request) incluant un modèle entièrement nouveau ou améliorer des modèles existants... le tout dans l’expérience de développement conviviale de GitHub.Anyone can submit a Pull Request that includes an entirely new template, or make enhancements to existing ones... all within the developer-friendly experience of GitHub.

Auto-hébergement du serviceSelf-hosting the service

Tous les types de données ne sont pas appropriés pour le service de modèles de cartes adaptatives « central » hébergé sur https://templates.adaptivecards.io.Not all types of data are appropriate for the "central" Adaptive Cards template service hosted at https://templates.adaptivecards.io.

Nous voulons nous assurer que tout le monde peut héberger le service de modèles au sein de votre organisation, c’est pourquoi le code source est disponible sur GitHub et peut être facilement déployé sur votre propre fonction Azure.We want to make sure anyone can host the template service within your organization, so the source code is available on GitHub and can be easily deployed to your own Azure Function.

Commencez ici ➡ adaptivecards-templatesGet started here ➡ adaptivecards-templates