Шаблоны ответов адаптивных карточек для подключаемых модулей API для #REF!

Важно!

Подключаемые модули поддерживаются только как действия в декларативных агентах. Они не включены в #REF!.

Подключаемые модули API могут использовать шаблоны ответов адаптивной карточки для улучшения ответа, который #REF! создает на основе ответа, полученного от API. Адаптивная карточка отображает ссылки в созданном ответе.

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

Шаблоны статических ответов

Статические шаблоны ответов являются хорошим выбором, если API всегда возвращает элементы одного типа, а формат адаптивной карточки не требуется часто менять. Статический шаблон определяется в свойстве static_templateresponse_semantics объекта в манифесте подключаемого модуля, как показано в следующем примере.

"functions": [
  {
    "name": "GetBudgets",
    "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
    "capabilities": {
      "response_semantics": {
        "data_path": "$",
        "properties": {
          "title": "$.name",
          "subtitle": "$.availableFunds"
        },
        "static_template": {
          "type": "AdaptiveCard",
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "version": "1.5",
          "body": [
            {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Name: ${if(name, name, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
                  "wrap": true
                }
              ]
            }
          ]
        }
      }
    }
  },
]

Для свойства response_semantics.data_path задано значение $. Это значение представляет собой запрос JSONPath , указывающий, что корень ответа JSON содержит соответствующие данные.
Свойству static_template.body["$data"] присвоено значение ${$root}, которое является синтаксисом языка шаблона адаптивной карточки, чтобы переопределить все предыдущие области данных и вернуться к корню. Задание этого значения здесь не требуется строго, так как data_path для параметра уже задан корневой каталог.
Свойство text первого TextBlock использует синтаксис ${if(name, name, 'N/A')}шаблона адаптивной карточки . Он ссылается на name свойство в ответе API. Функция if указывает, что если name имеет значение, используйте это значение, в противном случае — .N/A
Свойство text второго TextBlock использует синтаксис ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}шаблона адаптивной карточки . Он ссылается на availableFunds свойство в ответе API. Функция formatNumber преобразует число в строку с двумя десятичными знаками.

Рассмотрим этот статический шаблон и следующий ответ API.

[
    {
        "name": "Fourth Coffee lobby renovation",
        "availableFunds": 12000
    }
]

Это сочетание приводит к следующей адаптивной карточке.

Адаптивная карточка, отрисовывая ссылку в #REF!

Динамические шаблоны ответов

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

Чтобы использовать динамические шаблоны, укажите, какое свойство элементов данных указывает шаблон в свойстве response_semantics.properties.template_selector манифеста подключаемого модуля API, как показано в этом примере.

{
  "name": "GetTransactions",
  "description": "Returns details of transactions identified from filters like budget name or category. Multiple filters can be used in combination to refine the list of transactions returned",
  "capabilities": {
    "response_semantics": {
      "data_path": "$.transactions",
      "properties": {
        "template_selector": "$.displayTemplate"
      }
    }
  }
}

В этом примере свойству data_path присвоено значение $.transactions, указывающее, что данные для карточек находятся в свойстве transactions в корне ответа API. Свойство template_selector имеет значение $.displayTemplate, указывающее, что свойство для каждого элемента массива transactions , указывающего используемый шаблон, является свойством displayTemplate .

Свойство, указанное свойством template_selector , содержит запрос JSONPath для поиска шаблона для элемента в ответе.

Рассмотрим этот шаблон и следующий ответ API.

{
  "transactions": [
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -2000,
      "description": "Property survey for permit application",
      "expenseCategory": "permits",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -7200,
      "description": "Lumber and drywall for lobby",
      "expenseCategory": "materials",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": 5000,
      "description": "Additional funds to cover cost overruns",
      "expenseCategory": null,
      "displayTemplate": "$.templates.credit"
    }
  ],
  "templates": {
    "debit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "attention",
          "text": "Debit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Category",
              "value": "${if(expenseCategory, expenseCategory, 'N/A')}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    },
    "credit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "good",
          "text": "Credit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    }
  }
}

Свойство transactions в ответе содержит массив элементов.
Свойство templates представляет собой объект , при этом каждое свойство в этом объекте содержит шаблон адаптивной карточки.
Для displayTemplate каждого объекта в массиве transactions задано значение $.templates.debit или $.templates.credit.

Сочетание манифеста подключаемого модуля и ответа API приводит к получению следующих адаптивных карточек.

Адаптивная карточка, отрисовывавая дебетовую транзакцию.

Адаптивная карта, отрисовывавая кредитную транзакцию.

Совместное использование статических и динамических шаблонов

Подключаемые модули могут сочетать использование статических и динамических шаблонов. В этом сценарии статический шаблон выступает в качестве шаблона по умолчанию, который используется, если у элемента нет template_selector свойства или если его значение не разрешается в шаблон в ответе API.

Примечание.

При использовании Action.OpenUrlобязательно включите домен целевого URL-адреса в раздел validDomains манифеста приложения. Если домен отсутствует в списке, Teams отображает URL-адрес сообщения, который может привести к недоверенным содержимому.

Обеспечение адаптивных карточек в центрах #REF!

Адаптивные карточки должны быть разработаны так, чтобы реагировать на различные размеры поверхности. Это обеспечивает беспроблемное взаимодействие с пользователем независимо от используемого устройства или платформы. Для этого обязательно проверьте адаптивные карточки в разных центрах #REF!, включая Teams, #REF! и #REF!, а также проверьте ширину окна просмотра, заключив и расширив пользовательский интерфейс Copilot. Это гарантирует оптимальную работу адаптивных карточек и обеспечивает согласованное взаимодействие на всех платформах. Примените следующие рекомендации.

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

Конструктор адаптивных карточек для проектирования и тестирования адаптивных карточек в визуальном инструменте.
Документация по адаптивной карточке
Справочник по манифесту подключаемого модуля

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-06