Поделиться через

Служба шаблонов адаптивных карточек

  • Статья

Служба шаблонов адаптивных карточек является службой проверки концепции, которая позволяет всем пользователям находить шаблоны, вносить свой вклад и делиться набором известных шаблонов.

Она полезна, если вы хотите отобразить определенные данные, но не хотите создавать для них отдельную адаптивную карточку.

Ознакомьтесь с общими сведениями о работе с шаблонами адаптивных карточек.

Важно!

Условия и соглашения

Эта служба уровня альфа предоставляется на условиях "как есть", включая все возможные проблемы, и не обеспечивается никакой поддержкой. Любой сбор данных из этой службы согласуется с заявлением о конфиденциальности корпорации Майкрософт.

Эти функции предоставляются в ознакомительной версии и могут быть изменены. Ваши отзывы не только приветствуются, но и имеют решающее значение: только благодаря им мы сможем предоставлять функции, которые необходимы именно вам.

Как эта служба поможет вам?

Предположим, что у вас уже есть определенный фрагмент данных (например, из финансовой системы, Microsoft Graph, schema.org или пользовательской службы организации).

Эти данные нужно отображать для пользователей.

Обычно для этого приходилось писать пользовательский код во всех интерфейсных стеках, через которые данные доставляются пользователям.

Но что, если бы приложение могло самостоятельно обнаруживать новые шаблоны для пользовательского интерфейса, используя типы предоставленных данных? При этом любой пользователь мог бы добавлять, улучшать и применять в своих проектах общие шаблоны для пользовательского интерфейса. И не только в пределах организации, но и во всем Интернете.

Так что же собой представляет служба шаблонов карточек?

По сути, служба шаблонов карточек — это конечная точка RESTful, которая помогает выполнять следующие операции:

  • поиск шаблона на основе анализа структуры данных;
  • получение шаблона, который можно привязать к данным непосредственно в клиенте, не отправляя данные на сервер или не перемещая их с устройства иным образом;
  • заполнение шаблона на сервере, если привязка данных на стороне клиента невозможна или неудобна.

В основе этой службы лежит следующее:

  • Общий репозиторий шаблонов с открытым кодом на сайте GitHub (сейчас этот репозиторий считается частным, но он станет открытым, как только мы решим самые очевидные проблемы) .
  • Все шаблоны в этим репозитории — это неструктурированные JSON-файлы. Это упрощает редактирование, обсуждение и предоставление шаблонов в рамках обычного рабочего процесса разработки.
  • К коду этой службы будет предоставлен доступ, чтобы вы могли разместить любую полезную для себя информацию.

Использование службы

Получение полного списка шаблонов

Эта конечная точка возвращает список всех известных шаблонов.

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

Фрагмент ответа

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

Поиск шаблона

Эта конечная точка пытается найти шаблон, анализируя структуру данных.

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

Пример

Предположим, что пользователь обращается к конечной точке Microsoft Graph для получения корпоративных сведений о себе.

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

Graph Explorer screenshot

Этот API возвращает данные в формате JSON. Но как отобразить их для пользователя с помощью адаптивных карточек?

Сначала нужно выяснить, есть ли шаблон для данных этого типа. Для этого создается HTTP-запрос к конечной точке /find с данными в 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"
}

Ответ:

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

Служба возвращает полный список подходящих шаблонов с оценкой confidence, которая обозначает точность соответствия. Теперь по URL-адресу шаблона можно получить этот шаблон или заполнить его на стороне сервера.

Получение шаблона

Шаблон, полученный из этой конечной точки, можно заполнить данными во время выполнения с помощью пакетов SDK для работы с шаблонами.

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

Вы также можете включить в шаблон "пример данных". Это упростит редактирование в конструкторе:

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

Пример

Давайте получим шаблон профиля Microsoft Graph, который мы нашли в /find выше.

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

Фрагмент ответа

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

Теперь используйте этот шаблон с пакетами SDK для работы с шаблонами, чтобы создать готовую к просмотру адаптивную карточку.

Заполнение шаблона на стороне сервера

В некоторых случаях нет смысла заполнять шаблон в клиенте. Для таких сценариев служба может возвращать полностью заполненную адаптивную карточку, которую вы передадите любому средству просмотра адаптивных карточек.

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

Пример

Давайте заполним шаблон профиля Microsoft Graph, который мы нашли в /find, используя представленные выше данные.

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

Фрагмент ответа

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

Обратите внимание, что в ответе текст первого вхождения TextBlock содержит "Megan Bowen" вместо "{name}", как в запросе GET. Теперь эту адаптивную карточку можно передать в любое средство просмотра адаптивных карточек, не применяя методы обработки шаблонов на стороне клиента.

Участие в разработке шаблонов

Шаблоны размещаются на сайте GitHub в репозитории adaptivecards-templates.

Мы надеемся, что использование GitHub в качестве резервного хранилища для шаблонов позволит нам сделать более "демократичными" процессы создания, развития и совместного использования шаблонов. Любой желающий может отправить запрос на вытягивание для нового шаблона или внести улучшения в существующие, используя удобный и привычный для разработчика интерфейс GitHub.

Размещение службы на собственном оборудовании

Не все типы данных можно размещать в "централизованной" службе шаблонов адаптивных карт на https://templates.adaptivecards.io.

Мы хотим убедиться, что любой пользователь может разместить службу шаблонов в вашей организации, поэтому на сайте GitHub мы предоставили исходный код, который можно легко развернуть в вашей Функции Azure.

Начало работы ➡ adaptivecards-templates