Plantillas de respuesta de tarjeta adaptable para complementos de API para Microsoft 365 Copilot

Los complementos de API pueden usar plantillas de respuesta de tarjeta adaptable para mejorar la respuesta que Microsoft 365 Copilot genera en función de la respuesta recibida de la API. La tarjeta adaptable representa las citas dentro de la respuesta generada.

Los complementos de API pueden definir una plantilla de respuesta de tarjeta adaptable de dos maneras: como una plantilla estática definida en el manifiesto del complemento de API o como una plantilla dinámica devuelta como parte de la respuesta de la API. Los desarrolladores de complementos definieron plantillas mediante el esquema de tarjeta adaptable en combinación con el lenguaje de plantilla Tarjetas adaptables.

Plantillas de respuesta estática

Las plantillas de respuesta estática son una buena opción si la API siempre devuelve elementos del mismo tipo y el formato de la tarjeta adaptable no tiene que cambiar con frecuencia. Una plantilla estática se define en la static_template propiedad del response_semantics objeto en el manifiesto del complemento, como se muestra en el ejemplo siguiente.

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

• La propiedad response_semantics.data_path se configura como $. Este valor es una consulta JSONPath que indica que la raíz de la respuesta JSON contiene los datos pertinentes.
• La static_template.body["$data"] propiedad se establece en ${$root}, que es sintaxis de lenguaje de plantilla de tarjeta adaptable para invalidar cualquier ámbito de datos anterior y volver a la raíz. Establecer este valor aquí no es estrictamente necesario, ya que data_path ya está establecido en la raíz.
• La text propiedad de la primera TextBlock usa la sintaxis ${if(name, name, 'N/A')}de plantilla de tarjeta adaptable . Hace referencia a la name propiedad en la respuesta de la API. La if función especifica que si name tiene un valor, use ese valor; de lo contrario, use N/A.
• La text propiedad del segundo TextBlock usa la sintaxis ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}de plantilla de tarjeta adaptable . Hace referencia a la availableFunds propiedad en la respuesta de la API. La formatNumber función representa el número en una cadena con dos posiciones decimales.

Tenga en cuenta esta plantilla estática y la siguiente respuesta de API.

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

Esta combinación da como resultado la siguiente tarjeta adaptable.

Plantillas de respuesta dinámica

Las plantillas de respuesta dinámica son una buena opción si la API devuelve varios tipos. Con las plantillas dinámicas, puede asignar una plantilla de respuesta a cada elemento devuelto. Una o más plantillas dinámicas se devuelven como parte de la respuesta de la API y los elementos de datos de la respuesta indican qué plantilla se va a usar.

Para usar plantillas dinámicas, indique qué propiedad de los elementos de datos especifica la plantilla de la response_semantics.properties.template_selector propiedad en el manifiesto del complemento de API, como se muestra en este ejemplo.

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

En este ejemplo, la data_path propiedad se establece $.transactionsen , lo que indica que los datos de las tarjetas se encuentran en la transactions propiedad en la raíz de la respuesta de la API. La template_selector propiedad se establece $.displayTemplateen , lo que indica que la propiedad de cada elemento de la transactions matriz que especifica la plantilla que se va a usar es la displayTemplate propiedad .

La propiedad indicada por la template_selector propiedad contiene una consulta JSONPath para buscar la plantilla del elemento dentro de la respuesta.

Tenga en cuenta esta plantilla y la siguiente respuesta de 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"
    }
  }
}

• La transactions propiedad de la respuesta contiene una matriz de elementos.
• La templates propiedad es un objeto, con cada propiedad de ese objeto que contiene una plantilla de tarjeta adaptable.
• en displayTemplate cada objeto de la transactions matriz se establece $.templates.debit en o $.templates.credit.

La combinación de este manifiesto de complemento y la respuesta de API da como resultado las siguientes tarjetas adaptables.

Uso conjunto de plantillas estáticas y dinámicas

Los complementos pueden combinar el uso de plantillas estáticas y dinámicas. En este escenario, la plantilla estática actúa como plantilla predeterminada que se usa si el elemento no tiene la template_selector propiedad presente o si su valor no se resuelve en una plantilla en la respuesta de la API.

Garantizar tarjetas adaptables con capacidad de respuesta en Microsoft 365 Copilot hubs

Las tarjetas adaptables deben estar diseñadas para que respondan en varios tamaños de superficie. Esto garantiza una experiencia de usuario sin problemas, independientemente del dispositivo o plataforma que se use. Para ello, asegúrese de validar las tarjetas adaptables en diferentes centros de Microsoft 365 Copilot, incluidos Teams, Word y PowerPoint, y de validar varios anchos de ventanilla mediante la contratación y expansión de la interfaz de usuario de Copilot. Esto garantiza que las tarjetas adaptables funcionen de forma óptima y proporcionen una experiencia coherente en todas las plataformas. Aplique los procedimientos recomendados siguientes:

• Evite usar diseños de varias columnas siempre que sea posible. Los diseños de columna única tienden a representarse bien incluso en los anchos de ventanilla más estrechos.
• Evite colocar elementos de texto e imagen en la misma fila a menos que la imagen sea un icono o avatar pequeño.
• Evite asignar un ancho fijo a los elementos de la tarjeta adaptable; en su lugar, permita que cambien el tamaño según el ancho de la ventanilla. Sin embargo, puede asignar un ancho fijo a imágenes pequeñas, como iconos y avatares.

Contenido relacionado

• Diseñador de tarjetas adaptables para diseñar y probar tarjetas adaptables en una herramienta visual.
• Documentación de tarjeta adaptable
• Referencia del manifiesto del complemento de API