Modelos de resposta de Cartão Ajustável para plug-ins de API para Microsoft 365 Copilot

Os plug-ins de API podem utilizar modelos de resposta de Cartão Adaptável para melhorar a resposta que Microsoft 365 Copilot gera com base na resposta recebida da API. O Cartão Ajustável compõe citações na resposta gerada.

Os plug-ins de API podem definir um modelo de resposta cartão ajustável de duas formas: como um modelo estático definido no manifesto do plug-in da API ou como um modelo dinâmico devolvido como parte da resposta da API. Os programadores de plug-ins definiram modelos com o esquema cartão ajustável em combinação com a linguagem de modelo Cartões Ajustáveis.

Modelos de resposta estática

Os modelos de resposta estática são uma boa opção se a sua API devolver sempre itens do mesmo tipo e o formato do Cartão Ajustável não precisar de ser alterado frequentemente. Um modelo estático é definido na static_template propriedade do response_semantics objeto no manifesto do plug-in, conforme mostrado no exemplo seguinte.

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

• A propriedade response_semantics.data_path está definida como $. Este valor é uma consulta JSONPath que indica que a raiz da resposta JSON contém os dados relevantes.
• A static_template.body["$data"] propriedade está definida como ${$root}, que é sintaxe de linguagem de modelo de Cartão Adaptável para substituir qualquer âmbito de dados anterior e voltar à raiz. Definir este valor aqui não é estritamente necessário, uma vez que o data_path já está definido para a raiz.
• A text propriedade do primeiro TextBlock utiliza a sintaxe do modelo cartão ajustável ${if(name, name, 'N/A')}. Isto referencia a name propriedade na resposta da API. A if função especifica que, se name tiver um valor, utilize esse valor, caso contrário, utilize N/A.
• A text propriedade do segundo TextBlock utiliza a sintaxe do modelo cartão ajustável ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}. Isto referencia a availableFunds propriedade na resposta da API. A formatNumber função compõe o número numa cadeia com duas casas decimais.

Considere este modelo estático e a seguinte resposta à API.

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

Esta combinação resulta no seguinte Cartão Ajustável.

Modelos de resposta dinâmica

Os modelos de resposta dinâmica são uma boa opção se a API devolver vários tipos. Com modelos dinâmicos, pode atribuir um modelo de resposta a cada item devolvido. Um ou mais modelos dinâmicos são devolvidos como parte da resposta da API e os itens de dados na resposta indicam o modelo a utilizar.

Para utilizar modelos dinâmicos, indique que propriedade nos itens de dados especifica o modelo na response_semantics.properties.template_selector propriedade no manifesto do plug-in da API, conforme mostrado neste exemplo.

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

Neste exemplo, a data_path propriedade está definida como $.transactions, indicando que os dados dos cartões são encontrados na transactions propriedade na raiz da resposta da API. A template_selector propriedade está definida como $.displayTemplate, indicando que a propriedade em cada item na transactions matriz que especifica o modelo a utilizar é a displayTemplate propriedade .

A propriedade indicada pela template_selector propriedade contém uma consulta JSONPath para localizar o modelo do item na resposta.

Considere este modelo e a seguinte resposta à 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"
    }
  }
}

• A transactions propriedade na resposta contém uma matriz de itens.
• A templates propriedade é um objeto, com cada propriedade nesse objeto que contém um modelo de Cartão Ajustável.
• O displayTemplate em cada objeto na transactions matriz está definido como $.templates.debit ou $.templates.credit.

A combinação deste manifesto de plug-in e da resposta da API resulta nos seguintes Cartões Ajustáveis.

Utilizar modelos estáticos e dinâmicos em conjunto

Os plug-ins podem combinar a utilização de modelos estáticos e dinâmicos. Neste cenário, o modelo estático funciona como um modelo predefinido que é utilizado se o item não tiver a propriedade presente ou se o template_selector respetivo valor não resolve a um modelo na resposta da API.

Garantir cartões adaptáveis reativos em vários hubs Microsoft 365 Copilot

Os cartões ajustáveis têm de ser concebidos para serem reativos em vários tamanhos de superfície. Isto garante uma experiência de utilizador totalmente integrada, independentemente do dispositivo ou plataforma que está a ser utilizado. Para tal, confirme que valida os Cartões Ajustáveis em diferentes hubs de Microsoft 365 Copilot, incluindo o Teams, o Word e o PowerPoint, e valide várias larguras de viewport ao contrair e expandir a IU do Copilot. Isto garante que os Cartões Ajustáveis funcionam da melhor forma e proporcionam uma experiência consistente em todas as plataformas. Aplique as seguintes melhores práticas:

• Evite utilizar esquemas de várias colunas sempre que possível. Os esquemas de coluna única tendem a compor bem mesmo com as larguras de viewport mais estreitas.
• Evite colocar texto e elementos de imagem na mesma linha, a menos que a imagem seja um pequeno ícone ou avatar.
• Evite atribuir uma largura fixa a elementos dentro do Cartão Ajustável; em vez disso, permita que sejam redimensionadas de acordo com a largura da janela viewport. No entanto, pode atribuir uma largura fixa a pequenas imagens, como ícones e avatares.

Conteúdo relacionado

• Estruturador de Cartões Ajustável para estruturar e testar Cartões Ajustáveis numa ferramenta visual.
• Documentação do Cartão Ajustável
• Referência do manifesto do plug-in da API