Compartilhar via

Serviço de Modelo de Cartões Adaptáveis

  • Artigo

O Serviço de Modelo de Cartões Adaptáveis é um serviço de prova de conceito que permite que qualquer pessoa encontre, contribua e compartilhe um conjunto de modelos bem conhecidos.

É útil se você deseja exibir alguns dados, mas não quer se preocupar em escrever um cartão adaptável personalizado para ele.

Leia a Visão geral da Modelagem de Cartão Adaptável

Importante

Termos e contrato

Este serviço de nível alfa é oferecido "no estado em que se encontra", com todas as falhas. e não é compatível. Qualquer coleta de dados do serviço está sujeita à Política de Privacidade da Microsoft.

Esses recursos estão em versão prévia e estão sujeitos a alterações. Seus comentários não são apenas bem-vindos, mas são fundamentais para garantir o fornecimento dos recursos de que você precisa.

Como o serviço pode ajudar você?

Imagine que você recebeu uma parte de dados, que podem ser financeiros, do Microsoft Graph, do schema.org ou dados personalizados da sua organização.

Agora, você quer exibir os dados para um usuário.

Tradicionalmente, isso significa escrever um código de interface do usuário personalizada em todas as pilhas de front-end enviadas aos usuários finais.

Mas e se existisse um mundo em que o aplicativo pudesse "aprender" novos modelos de interface do usuário com base no tipo de dados? Um mundo em que todas as pessoas pudessem contribuir, aprimorar e compartilhar modelos comuns de interface do usuário com projetos, organizações ou toda a Internet.

O que é o serviço de modelo de cartão?

O serviço de modelo de cartão é um ponto de extremidade REST simples que ajuda a:

  • Localizar um modelo por meio da análise da estrutura dos dados
  • Obter um modelo para ser associado diretamente ao cliente, sem que seja preciso enviar os dados para o servidor ou sair do dispositivo
  • Popular um modelo no servidor quando a associação de dados no lado do cliente não é apropriada ou possível

Na base disso tudo, está:

  • um repositório de modelos de software livre e compartilhado desenvolvido pelo GitHub. (No momento, o repositório é privado, mas se tornará público assim que alguns detalhes forem definidos)
  • Todos os modelos são arquivos JSON simples no repositório, o que torna a edição, a contribuição e o compartilhamento partes naturais do fluxo de trabalho do desenvolvedor.
  • O código para o serviço será disponibilizado para que você possa hospedar em qualquer lugar que fizer mais sentido para você.

Usar o serviço

Obter todos os modelos

Esse ponto de extremidade retorna uma lista de todos os modelos conhecidos.

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

Trecho de resposta

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

Descobrir um modelo

Esse ponto de extremidade tenta localizar um modelo analisando a estrutura dos seus dados.

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

Exemplo

Imagine que você tenha acessado um ponto de extremidade do Microsoft Graph para obter dados organizacionais sobre você.

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

Graph Explorer screenshot

Essa API retornou dados JSON, mas como exibi-los aos usuários por meio dos Cartões Adaptáveis?

Primeiro, é preciso verificar se existe um modelo para esse tipo de dados, portanto, faça uma solicitação HTTP para o ponto de extremidade /find com os seus dados no 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"
}

Resposta:

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

O serviço retorna uma lista de todos os modelos correspondentes, juntamente com um confidence indicando o nível de semelhança da correspondência. Agora é possível usar a URL do modelo para obter o modelo ou populá-lo no lado do servidor.

Obter um modelo

Um modelo recuperado desse ponto de extremidade pode ser populado com os dados em runtime usando os SDKs de modelagem.

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

Você também pode incluir "dados de exemplo" com o modelo, o que torna a edição no designer mais amigável:

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

Exemplo

Vamos obter o modelo de perfil do Microsoft Graph que foi retornado do /find acima.

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

Trecho de resposta

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

Agora, use esse modelo com os SDKs de modelagem para criar um Cartão Adaptável pronto para renderização.

Preencher um modelo no lado do servidor

Em alguns casos, talvez não faça sentido popular um modelo no cliente. Nesses casos de uso, é possível fazer com que o serviço retorne um Cartão Adaptável totalmente populado, pronto para ser passado para qualquer processador de Cartão Adaptável.

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

Exemplo

Vamos popular o modelo de perfil do Microsoft Graph que foi retornado de /find usando os dados acima.

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

Trecho de resposta

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

Observe como a resposta substituiu o texto do primeiro TextBlock por "Megan Bowen" em vez de "{name}", como na solicitação de GET. Agora, esse Cartão Adaptável pode ser enviado a qualquer renderizador sem precisar passar por modelagem no lado do cliente.

Modelos de contribuição

Os modelos são hospedados no GitHub no repositório adaptivecards-templates.

Nossa esperança é que, ao usar o GitHub como um repositório de backup para os modelos, possamos "democratizar" o processo de criação, aprimoramento e compartilhamento de modelos. Qualquer pessoa pode enviar uma solicitação de pull que inclui um modelo totalmente novo ou fazer aprimoramentos nos existentes… tudo na experiência amigável para desenvolvedores do GitHub.

Auto-hospedar o serviço

Nem todos os tipos de dados são apropriados para o serviço de modelo "central" de Cartões Adaptáveis hospedados em https://templates.adaptivecards.io.

Queremos ter certeza de que qualquer pessoa possa hospedar o serviço de modelo em sua organização. Por isso, o código-fonte será disponibilizado no GitHub e poderá ser facilmente implantado no seu próprio Azure Function.

Comece aqui ➡ adaptivecards-templates