Antwortvorlagen für adaptive Karten für API-Plug-Ins für Microsoft 365 Copilot

API-Plug-Ins können Antwortvorlagen für adaptive Karten verwenden, um die Antwort zu verbessern, die Microsoft 365 Copilot basierend auf der von der API empfangenen Antwort generiert. Die adaptive Karte rendert Zitate innerhalb der generierten Antwort.

API-Plug-Ins können eine Antwortvorlage für adaptive Karten auf zwei Arten definieren: als statische Vorlage, die im API-Plug-In-Manifest definiert ist, oder als dynamische Vorlage, die als Teil der API-Antwort zurückgegeben wird. Plug-In-Entwickler haben Vorlagen mithilfe des Schemas für adaptive Karten in Kombination mit der Vorlagensprache für adaptive Karten definiert.

Vorlagen für statische Antworten

Statische Antwortvorlagen sind eine gute Wahl, wenn Ihre API immer Elemente desselben Typs zurückgibt und das Format der adaptiven Karte nicht häufig geändert werden muss. Eine statische Vorlage wird in der static_template -Eigenschaft des response_semantics -Objekts im Plug-In-Manifest definiert, wie im folgenden Beispiel gezeigt.

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

• Die response_semantics.data_path-Eigenschaft ist auf $ gesetzt. Dieser Wert ist eine JSONPath-Abfrage , die angibt, dass der Stamm der JSON-Antwort die relevanten Daten enthält.
• Die static_template.body["$data"] -Eigenschaft ist auf ${$root}festgelegt. Dies ist die Sprachsyntax für adaptive Kartenvorlagen, um alle vorherigen Datenbereichsgrenzen außer Kraft zu setzen und zum Stamm zurückzukehren. Das Festlegen dieses Werts ist hier nicht unbedingt erforderlich, da bereits data_path auf den Stamm festgelegt ist.
• Die text -Eigenschaft des ersten TextBlock verwendet die Vorlagensyntax ${if(name, name, 'N/A')}für adaptive Karten. Dies verweist auf die name -Eigenschaft in der API-Antwort. Die if Funktion gibt an, dass, wenn name über einen Wert verfügt, diesen Wert verwenden, andernfalls N/Averwenden.
• Die text -Eigenschaft der zweiten TextBlock verwendet die Vorlagensyntax ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}für adaptive Karten. Dies verweist auf die availableFunds -Eigenschaft in der API-Antwort. Die formatNumber Funktion rendert die Zahl in eine Zeichenfolge mit zwei Dezimalstellen.

Betrachten Sie diese statische Vorlage und die folgende API-Antwort.

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

Diese Kombination führt zu der folgenden adaptiven Karte.

Vorlagen für dynamische Antworten

Dynamische Antwortvorlagen sind eine gute Wahl, wenn Ihre API mehrere Typen zurückgibt. Mit dynamischen Vorlagen können Sie jedem zurückgegebenen Element eine Antwortvorlage zuweisen. Eine oder mehrere dynamische Vorlagen werden als Teil der API-Antwort zurückgegeben, und die Datenelemente in der Antwort geben an, welche Vorlage verwendet werden soll.

Um dynamische Vorlagen zu verwenden, geben Sie an, welche Eigenschaft für die Datenelemente die Vorlage in der response_semantics.properties.template_selector -Eigenschaft im API-Plug-In-Manifest angibt, wie in diesem Beispiel gezeigt.

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

In diesem Beispiel wird die data_path -Eigenschaft auf $.transactionsfestgelegt, was angibt, dass die Daten für die Karten in der transactions -Eigenschaft im Stamm der API-Antwort gefunden werden. Die template_selector -Eigenschaft ist auf $.displayTemplatefestgelegt, was angibt, dass die -Eigenschaft für jedes Element im transactions Array, das die zu verwendende Vorlage angibt, die displayTemplate -Eigenschaft ist.

Die durch die template_selector -Eigenschaft angegebene Eigenschaft enthält eine JSONPath-Abfrage, um die Vorlage für das Element in der Antwort zu suchen.

Betrachten Sie diese Vorlage und die folgende API-Antwort.

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

• Die transactions -Eigenschaft in der Antwort enthält ein Array von Elementen.
• Die templates -Eigenschaft ist ein -Objekt, wobei jede Eigenschaft in diesem Objekt eine Vorlage für adaptive Karten enthält.
• Die displayTemplate für jedes Objekt im transactions Array ist entweder $.templates.debit auf oder $.templates.creditfestgelegt.

Die Kombination aus diesem Plug-In-Manifest und der API-Antwort führt zu den folgenden adaptiven Karten.

Gemeinsames Verwenden von statischen und dynamischen Vorlagen

Plug-Ins können die Verwendung von statischen und dynamischen Vorlagen kombinieren. In diesem Szenario fungiert die statische Vorlage als Standardvorlage, die verwendet wird, wenn die template_selector Eigenschaft für das Element nicht vorhanden ist oder wenn sein Wert nicht in eine Vorlage in der API-Antwort aufgelöst wird.

Sicherstellen von reaktionsfähigen adaptiven Karten in Microsoft 365 Copilot Hubs

Adaptive Karten müssen so konzipiert sein, dass sie über verschiedene Oberflächengrößen hinweg reaktionsfähig sind. Dadurch wird eine nahtlose Benutzererfahrung sichergestellt, unabhängig vom verwendeten Gerät oder der verwendeten Plattform. Um dies zu erreichen, überprüfen Sie die adaptiven Karten auf verschiedenen Microsoft 365 Copilot Hubs, einschließlich Teams, Word und PowerPoint, und überprüfen Sie verschiedene Viewportbreiten, indem Sie die Copilot-Benutzeroberfläche vertraglich festlegen und erweitern. Dadurch wird sichergestellt, dass adaptive Karten optimal funktionieren und plattformübergreifend eine konsistente Erfahrung bieten. Wenden Sie die folgenden bewährten Methoden an:

• Vermeiden Sie nach Möglichkeit die Verwendung von layouts mit mehreren Spalten. Einspaltige Layouts werden in der Regel auch bei den schmalsten Viewportbreiten gut gerendert.
• Verzichten Sie darauf, Text- und Bildelemente in derselben Zeile zu platzieren, es sei denn, das Bild ist ein kleines Symbol oder avatar.
• Vermeiden Sie es, Elementen innerhalb der adaptiven Karte eine feste Breite zuzuweisen. Lassen Sie stattdessen zu, dass sie die Größe entsprechend der Viewportbreite ändern können. Sie können kleinen Bildern wie Symbolen und Avataren jedoch eine feste Breite zuweisen.

Verwandte Inhalte

• Designer für adaptive Karten zum Entwerfen und Testen adaptiver Karten in einem visuellen Tool.
• Dokumentation zu adaptiven Karten
• API-Plug-In-Manifestreferenz