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

Wichtig

Plug-Ins werden nur als Aktionen innerhalb deklarativer Agents unterstützt. Sie sind in Microsoft 365 Copilot nicht aktiviert.

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

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

Statische Antwortvorlagen

Statische Antwortvorlagen sind eine gute Wahl, wenn Ihre API immer Elemente des gleichen Typs zurückgibt und das Format der adaptiven Karte nicht oft geändert werden muss. Definieren Sie eine statische Vorlage in der static_template Eigenschaft des Objekts response_semantics im Plug-In-Manifest, 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
                }
              ]
            }
          ]
        }
      }
    }
  },
]

response_semantics.data_path Eigenschaft festlegen auf . This value is a [JSONPath query](https://www.rfc-editor.org/rfc/rfc9535) that indicates that the root of the JSON response contains the relevant data. The static_template.body["$data"]property value is${$root}, which is Adaptive Card template language syntax to override any prior data scoping and break back to the root. Setting this value isn't strictly needed, since the data_path' ist bereits auf den Stamm festgelegt.
Die text Eigenschaft der ersten TextBlock verwendet die Syntax ${if(name, name, 'N/A')}der adaptiven Kartenvorlage . Dies verweist auf die name Eigenschaft in der API-Antwort. Die if Funktion gibt an, dass wenn sie name über einen Wert verfügt, diesen Wert verwenden, andernfalls use N/A.
Die text Eigenschaft der zweiten TextBlock verwendet die Syntax ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}der adaptiven Kartenvorlage . 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.

Eine adaptive Karte, die ein Zitat in Microsoft 365 Copilot rendert

Dynamische Antwortvorlagen

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 ist die data_path Eigenschaft auf festgelegt , $.transactionswas angibt, dass sich die Daten für die Karten in der transactions Eigenschaft am Stamm der API-Antwort befinden. Die template_selector Eigenschaft ist festgelegt auf $.displayTemplate, was angibt, dass die Eigenschaft für jedes Element im Array, das transactions 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 innerhalb der Antwort zu finden.

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 adaptive Kartenvorlage enthält.
Der Wert 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.

Eine adaptive Karte, die eine Soll-Transaktion durchführt.

Eine adaptive Karte, die eine Gutschrifttransaktion durchführt.

Verhindern Sie leere adaptive Karten, wenn ein Array in der API-Antwort leer ist

Adaptive Karten können leer gerendert werden, wenn eine Arrayeigenschaft in der API-Antwort leer ist und die Vorlage keine bedingte Logik enthält, um dieses Szenario zu handhaben.

Das folgende Beispiel zeigt eine API-Antwort, bei der das Array recommendations keine Elemente enthält:

{"answer":"","recommendations":[],"followUpMessage":""}

In diesem Fall:

Das Empfehlungsarray enthält keine Elemente.
Die adaptive Kartenvorlage versucht, über das Array zu iterieren, ohne zu überprüfen, ob Daten verfügbar sind.

Um zu verhindern, dass eine leere Karte gerendert wird, binden Sie die Vorlage an die richtige Arrayeigenschaft, und fügen Sie bedingte Logik zum Steuern des Renderings hinzu.

Binden Sie an das Array, indem Sie Folgendes verwenden data_path:

"data_path": "$.recommendations"

Iterieren Sie nur dann über Objekte, wenn Daten vorhanden sind:

{ "type": "ColumnSet", "$data": "${$root}", "$when": "${title != null && title != ''}" }

Stellen Sie optional Fallbacktext bereit, wenn der Array leer ist:

{ "type": "TextBlock", "text": "No recommendations available", "$when": "${length($root) == 0}" }

Tipp

data_path Überprüfen und fügen Sie immer Bedingungen für leere Arrays ein$when, um leere adaptive Karten zu verhindern.

Statische und dynamische Vorlagen zusammen verwenden

Plugins 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 des Elements nicht vorhanden ist oder wenn sein Wert in der API-Antwort nicht in eine Vorlage aufgelöst wird.

Domänen zu Ihrem App-Manifest hinzufügen

Fügen Sie alle Domänen, die Ihre adaptive Karte verwendet, dem Abschnitt validDomains Ihres App-Manifests hinzu.

Wenn Sie verwenden, stellen Sie Action.OpenUrlsicher, dass Sie die Domäne der Ziel-URL in die validDomains Eigenschaft aufnehmen. Wenn die Domäne nicht aufgeführt ist, zeigt Teams die Meldung an, dass die URL zu nicht vertrauenswürdigen Inhalten führen kann.
Bild-URLs, die Ihr API-Plug-In oder deklarativer Agent in einer Adaptive Card-Antwort zurückgibt, müssen ihre Domäne in der validDomains Eigenschaft haben. Wenn die Domäne nicht aufgeführt ist, rendert Microsoft 365 Copilot das Bild nicht.

Stellen Sie reaktionsfähige adaptive Karten in allen Microsoft 365 Copilot-Hubs sicher

Adaptive Karten müssen so konzipiert sein, dass sie auf verschiedenen Oberflächengrößen reaktionsfähig sind. Dieses Design gewährleistet eine nahtlose Benutzererfahrung, unabhängig vom verwendeten Gerät oder der verwendeten Plattform. Um dieses Ziel zu erreichen, validieren Sie die adaptiven Karten auf verschiedenen Microsoft 365 Copilot-Hubs, einschließlich Teams, Word und PowerPoint. Validieren Sie außerdem verschiedene Viewportbreiten, indem Sie die Copilot-Benutzeroberfläche verkleinern und erweitern. Dieser Prozess stellt sicher, dass Adaptive Karten optimal funktionieren und eine konsistente Erfahrung auf allen Plattformen bieten. Wenden Sie die folgenden bewährten Methoden an:

Vermeiden Sie nach Möglichkeit die Verwendung mehrspaltiger Layouts. Einspaltige Layouts werden in der Regel selbst bei schmalsten Viewportbreiten gut gerendert.
Platzieren Sie keine Text- und Bildelemente in derselben Reihe, es sei denn, das Bild ist ein kleines Symbol oder ein Avatar.
Vermeiden Sie es, Elementen innerhalb der adaptiven Karte eine feste Breite zuzuweisen. erlauben Sie ihnen stattdessen, die Größe entsprechend der Breite des Ansichtsfensters anzupassen. Sie können jedoch kleinen Bildern wie Symbolen und Avataren eine feste Breite zuweisen.

Adaptiver Kartendesigner zum Entwerfen und Testen adaptiver Karten in einem visuellen Tool.
Dokumentation zu adaptiven Karten
Plug-In-Manifestreferenz

Feedback

War diese Seite hilfreich?

Last updated on 2026-08-20