Microsoft 365 Copilot用 API プラグインのアダプティブカード応答テンプレート

重要

API プラグインは、宣言型エージェント内のアクションとしてのみサポートされます。 Microsoft 365 Copilotでは有効になっていません。

API プラグインでは、アダプティブカード応答テンプレートを使用して、API から受信した応答に基づいてMicrosoft 365 Copilot生成される応答を強化できます。アダプティブカードは、生成された応答内で引用をレンダリングします。

API プラグインは、API プラグインマニフェストで定義された静的テンプレートとして、または API 応答の一部として返される動的テンプレートとして、2 つの方法でアダプティブカード応答テンプレートを定義できます。プラグイン開発者は、アダプティブカードテンプレート言語と組み合わせてアダプティブカードスキーマを使用してテンプレートを定義しました。

静的応答テンプレート

静的応答テンプレートは、API が常に同じ種類の項目を返し、アダプティブカードの形式を頻繁に変更する必要がない場合に適しています。静的テンプレートは、次の例に示すように、プラグインマニフェストの response_semantics オブジェクトの static_template プロパティで定義されます。

"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 プロパティは $ に設定されています。この値は、JSON 応答のルートに関連するデータが含まれていることを示す JSONPath クエリです。
static_template.body["$data"] プロパティは ${$root} に設定されています。これは、事前のデータスコープをオーバーライドしてルートに戻すアダプティブカードテンプレート言語構文です。 data_pathは既にルートに設定されているため、ここでこの値を設定する必要はありません。
最初のTextBlockの text プロパティでは、アダプティブカードテンプレート構文${if(name, name, 'N/A')}が使用されます。これにより、API 応答の name プロパティが参照されます。 if関数は、nameに値がある場合は、その値を使用し、それ以外の場合は N/A を使用することを指定します。
2 番目のTextBlockの text プロパティでは、アダプティブカードテンプレート構文${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}が使用されます。これにより、API 応答の availableFunds プロパティが参照されます。 formatNumber関数は、小数点以下 2 桁の文字列に数値をレンダリングします。

この静的テンプレートと次の API 応答を検討してください。

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

この組み合わせにより、次のアダプティブカードが生成されます。

Microsoft 365 Copilotでの引用をレンダリングするアダプティブカード

動的応答テンプレート

動的応答テンプレートは、API が複数の型を返す場合に適しています。動的テンプレートを使用すると、返された各項目に応答テンプレートを割り当てることができます。 API 応答の一部として 1 つ以上の動的テンプレートが返され、応答のデータ項目は使用するテンプレートを示します。

動的テンプレートを使用するには、この例に示すように、API プラグインマニフェストの response_semantics.properties.template_selector プロパティでテンプレートを指定するデータ項目のプロパティを指定します。

{
  "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 に設定し、カードのデータが API 応答のルートにある transactions プロパティにあることを示します。 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 プロパティはオブジェクトであり、そのオブジェクトの各プロパティにはアダプティブカードテンプレートが含まれています。
transactions配列内の各オブジェクトのdisplayTemplateは、$.templates.debitまたは$.templates.creditに設定されます。

このプラグインマニフェストと API 応答の組み合わせは、次のアダプティブカードになります。

デビットトランザクションをレンダリングするアダプティブカード。

クレジットトランザクションをレンダリングするアダプティブカード。

静的テンプレートと動的テンプレートの併用

プラグインは、静的テンプレートと動的テンプレートの両方の使用を組み合わせることができます。このシナリオでは、静的テンプレートは、項目に template_selector プロパティが存在しない場合、またはその値が API 応答のテンプレートに解決されない場合に使用される既定のテンプレートとして機能します。

Microsoft 365 Copilot ハブ間で応答性の高いアダプティブカードを確保する

アダプティブカードは、さまざまなサーフェスサイズにわたって応答性が高いよう設計されている必要があります。これにより、使用されているデバイスやプラットフォームに関係なく、シームレスなユーザーエクスペリエンスが保証されます。これを実現するには、Teams、Word、PowerPointなど、さまざまなMicrosoft 365 Copilot ハブ上のアダプティブカードを検証し、Copilot UI を縮小して展開することで、さまざまなビューポートの幅を検証します。これにより、アダプティブカードが最適に機能し、すべてのプラットフォームで一貫性のあるエクスペリエンスが提供されます。次のベストプラクティスを適用します。

可能な限り、複数列レイアウトを使用しないでください。単一列レイアウトは、最も狭いビューポートの幅でもうまくレンダリングされる傾向があります。
画像が小さなアイコンまたはアバターでない限り、同じ行にテキストと画像の要素を配置することは控えます。
アダプティブカード内の要素に固定幅を割り当てないでください。代わりに、ビューポートの幅に応じてサイズを変更できます。ただし、アイコンやアバターなどの小さな画像に固定幅を割り当てることができます。

ビジュアルツールでアダプティブカードを設計およびテストするためのアダプティブカードデザイナー。
アダプティブカードのドキュメント
API プラグインマニフェストリファレンス

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-02-03

次の方法で共有

Microsoft 365 Copilot用 API プラグインのアダプティブ カード応答テンプレート

静的応答テンプレート

動的応答テンプレート

静的テンプレートと動的テンプレートの併用

Microsoft 365 Copilot ハブ間で応答性の高いアダプティブ カードを確保する

関連コンテンツ

フィードバック

その他のリソース

Microsoft 365 Copilot用 API プラグインのアダプティブカード応答テンプレート

Microsoft 365 Copilot ハブ間で応答性の高いアダプティブカードを確保する