Servicio de plantillas de tarjetas adaptables

El servicio de plantillas de Tarjetas adaptables es un servicio de prueba de concepto que permite a todos los usuarios compartir un conjunto de tarjetas adaptables conocidas, buscar en él y realizar contribuciones.

Resulta útil si quieres mostrar algunos datos, pero no quieres molestarte en escribir una tarjeta adaptable personalizada.

Sigue leyendo para obtener una introducción a las plantillas de tarjetas adaptables.

Importante

Términos y contrato

Este servicio de nivel alfa se proporciona "tal cual", con todos los errores, y no recibe ningún tipo de soporte técnico. Toda recopilación de datos a partir del servicio está sujeta a la Declaración de privacidad de Microsoft.

Estas características se encuentran en versión preliminar y están sujetas a cambios. Sus comentarios son bienvenidos y son fundamentales para garantizar la entrega de las características que usted necesita.

¿En qué me ayuda el servicio?

Supongamos que acabo de recibir algunos datos, puede que sean datos financieros, datos de Microsoft Graph, datos de schema.org o datos personalizados de mi organización.

Ahora quiero mostrar los datos a un usuario.

Tradicionalmente, esto significa escribir código de UI personalizado en todas las pilas de front-end que entrego a los usuarios finales.

Pero ¿qué ocurre si hubiera un mundo donde mi aplicación pudiera "aprender" nuevas plantillas de UI en función del tipo de datos? Un mundo en el que cualquiera pudiera aportar, mejorar y compartir plantillas de UI comunes, dentro de sus propios proyectos, dentro de una organización o para todo Internet.

¿Qué es el servicio de plantillas de tarjetas?

El servicio de plantillas de tarjetas es un punto de conexión de REST sencillo que ayuda a:

• Buscar una plantilla mediante el análisis de la estructura de los datos
• Obtener una plantilla para que puedas enlazarla directamente en el cliente, sin enviar los datos al servidor ni salir jamás del dispositivo
• Rellenar una plantilla en el servidor, cuando el enlace de datos del lado cliente no sea adecuado o posible

Por encima de todo, es:

• Un repositorio compartido de plantillas de código abierto respaldado por GitHub. (Actualmente, el repositorio es privado, pero se hará público en cuanto se aten algunos cabos sueltos).
• Todas las plantillas son archivos JSON sin formato en el repositorio, lo que hace que editar, aportar y compartir sea una parte natural del flujo de trabajo de un desarrollador.
• El código para el servicio estará disponible para que puedas hospedar donde te resulte más conveniente.

Uso del servicio

Obtener todas las plantillas

Este punto de conexión devuelve una lista de todas las plantillas conocidas.

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

Extracto de respuesta

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

Búsqueda de una plantilla

Este punto de conexión intenta buscar una plantilla mediante el análisis de la estructura de los datos.

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

Ejemplo

Supongamos que accedo a un punto de conexión de Microsoft Graph para obtener datos de la organización sobre mí.

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

La API devolvió datos JSON, pero ¿cómo los muestro a los usuarios mediante tarjetas adaptables?

En primer lugar, quiero ver si existe una plantilla para este tipo de datos, así que hago una solicitud HTTP al punto de conexión /find con mis datos en 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"
}

Respuesta:

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

El servicio devuelve una lista de las plantillas correspondientes, junto con un valor de confidence que indica la precisión de la coincidencia. Ahora puedo usar la dirección URL de la plantilla para obtener la plantilla o rellenarla en el lado servidor.

Obtención de una plantilla

Una plantilla recuperada de este punto de conexión se puede rellenar con datos en tiempo de ejecución mediante los SDK de plantillas.

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

También puedes incluir "datos de ejemplo" con la plantilla, lo que hace que la edición en el diseñador sea más sencilla:

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

Ejemplo

Vamos a obtener la plantilla de perfil de Microsoft Graph que se devolvió antes en /find.

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

Extracto de respuesta

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

Ahora usa esta plantilla con los SDK de plantillas para crear una tarjeta adaptable lista para su representación.

Rellenar una plantilla del lado servidor

En algunos casos, puede que no tenga sentido rellenar una plantilla en el cliente. En estos casos de uso, puedes hacer que el servicio devuelva una tarjeta adaptable totalmente rellenada, lista para pasarla a cualquier representador de tarjetas adaptables.

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

Ejemplo

Vamos a rellenar la plantilla de perfil de Microsoft Graph que se devolvió antes en /find usando los datos anteriores.

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"
}

Extracto de respuesta

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

Observa cómo la respuesta ha reemplazado el texto del primer TextBlock por "Megan Bowen", en lugar de "{name}", como en la solicitud GET. Esta tarjeta adaptable ahora se puede pasar a cualquier representador de tarjetas adaptables sin pasar por las plantillas del lado cliente.

Aportación de plantillas

Las plantillas se hospedan en GitHub en el repositorio adaptivecards-templates.

Tenemos la esperanza de que, al usar GitHub como almacén auxiliar para las plantillas, podamos "democratizar" el proceso de creación, mejora y uso compartido de plantillas. Cualquier persona puede enviar una solicitud de incorporación de cambios que incluya una plantilla completamente nueva, o hacer mejoras en las existentes… Todo dentro de la experiencia para desarrolladores de GitHub.

Autohospedaje del servicio

No todos los tipos de datos son adecuados para el servicio "central" de plantillas de tarjetas adaptables hospedado en https://templates.adaptivecards.io.

Queremos asegurarnos de que cualquier usuario pueda hospedar el servicio de plantillas dentro de tu organización, por lo que el código fuente está disponible en GitHub y se puede implementar fácilmente en tu propia función de Azure.

Comienza aquí ➡ adaptivecards-templates