Microsoft 365 Copilot용 API 플러그 인용 적응형 카드 응답 템플릿

중요

MCP 및 API 플러그인은 선언적 에이전트 내에서 작업을 제공합니다. 독립형 설치 가능한 플러그인 패키지가 아닙니다. 포함된 에이전트만 해당 기능과 도구에 액세스할 수 있습니다. 패키지와 작업 매니페스트 관계에 대한 자세한 내용은 플러그 인 및 선언적 에이전트 작업을 참조하세요.

API 플러그 인은 적응형 카드 응답 템플릿을 사용하여 API에서 받은 응답을 기반으로 Microsoft 365 Copilot이 생성하는 응답을 향상시킬 수 있습니다. 적응형 카드는 생성된 응답 내에서 인용을 렌더링합니다.

API 플러그 인은 적응형 카드 응답 템플릿을 플러그인 매니페스트에 정의된 정적 템플릿 또는 API 응답의 일부로 반환된 동적 템플릿의 두 가지 방법으로 정의할 수 있습니다. 플러그인 개발자는 적응형 카드 스키마 를 적응형 카드 템플릿 언어와 함께 사용하여 템플릿을 정의합니다.

정적 응답 템플릿

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
                }
              ]
            }
          ]
        }
      }
    }
  },
]
  • 속성을 static_template로 설정합니다 response_semantics.data_path . . 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 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'는 이미 루트로 설정되어 있습니다.
  • 첫 번째 TextBlock 속성은 text 적응형 카드 템플릿 구문${if(name, name, 'N/A')}을 사용합니다. 이는 API 응답의 속성을 참조 name 합니다. 이 if 함수는 값이 있으면 해당 값을 사용하고 name , 그렇지 않으면 를 사용하도록 N/A지정합니다.
  • 두 번째 TextBlock 속성은 text 적응형 카드 템플릿 구문${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}을 사용합니다. 이는 API 응답의 속성을 참조 availableFunds 합니다. 이 formatNumber 함수는 소수점 이하 두 자리의 문자열에 숫자를 렌더링합니다.

이 정적 템플릿과 다음 API 응답을 고려하세요.

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

이 조합은 다음과 같은 적응형 카드를 생성합니다.

Microsoft 365 Copilot에서 인용을 렌더링하는 적응형 카드

동적 응답 템플릿

API가 여러 유형을 반환하는 경우 동적 응답 템플릿을 선택하는 것이 좋습니다. 동적 템플릿을 사용하면 반환되는 각 항목에 응답 템플릿을 할당할 수 있습니다. 하나 이상의 동적 템플릿이 API 응답의 일부로 반환되며 응답의 데이터 항목은 사용할 템플릿을 나타냅니다.

동적 템플리트를 사용하려면 이 예제와 같이 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 on 각 개체는 displayTemplate 또는 로 설정 $.templates.debit$.templates.credit됩니다.

이 플러그인 매니페스트와 API 응답을 조합하면 다음과 같은 적응형 카드가 생성됩니다.

직불 거래를 렌더링하는 적응형 카드입니다.

신용 거래를 렌더링하는 적응형 카드입니다.

API 응답의 배열이 비어 있는 경우 빈 적응형 카드 방지

API 응답의 배열 속성이 비어 있고 템플릿에 해당 시나리오를 처리하기 위한 조건부 논리가 포함되어 있지 않으면 적응형 카드가 공백으로 렌더링될 수 있습니다.

다음 예제에서는 배열에 recommendations 항목이 없는 API 응답을 보여 줍니다.

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

이 경우:

  1. 권장 사항 배열에 항목이 없습니다.
  2. 적응형 카드 템플릿은 데이터를 사용할 수 있는지 여부를 확인하지 않고 배열을 반복하려고 시도합니다.

빈 카드가 렌더링되지 않도록 하려면 템플릿을 올바른 배열 속성에 바인딩하고 렌더링 제어를 위한 조건부 논리를 추가합니다.

다음을 사용하여 data_path배열에 바인딩합니다.

"data_path": "$.recommendations"

데이터가 있는 경우에만 개체를 반복합니다.

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

원하는 경우 배열이 비어 있는 경우 대체 텍스트를 제공합니다.

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

팁

빈 적응형 카드가 표시되지 않도록 빈 배열에 대한 조건을 항상 유효성 검사 data_path 하고 포함 $when 합니다.

정적 템플릿과 동적 템플릿을 함께 사용

플러그 인은 정적 템플릿과 동적 템플릿을 모두 사용할 수 있습니다. 이 시나리오에서 정적 템플릿은 항목에 속성이 없 template_selector 거나 해당 값이 API 응답의 템플릿으로 확인되지 않는 경우 사용되는 기본 템플릿 역할을 합니다.

앱 매니페스트에 도메인 추가

적응형 카드에서 사용하는 도메인을 앱 매니페스트의 validDomains 섹션에 추가합니다.

  • 를 사용하는 Action.OpenUrl경우 속성에 validDomains 대상 URL의 도메인을 포함해야 합니다. 도메인이 목록에 없으면 Teams에 URL이 신뢰할 수 없는 콘텐츠로 연결될 수 있다는 메시지가 표시됩니다.
  • API 플러그 인 또는 선언적 에이전트가 적응형 카드 응답에서 반환하는 이미지 URL에는 해당 도메인이 속성에 validDomains 나열되어 있어야 합니다. 도메인이 목록에 없으면 Microsoft 365 Copilot이 이미지를 렌더링하지 않습니다.

Microsoft 365 Copilot 허브에서 적응형 카드 반응형 확인

적응형 카드는 다양한 표면 크기에 걸쳐 반응하도록 디자인되어야 합니다. 이 디자인은 사용 중인 장치나 플랫폼에 관계없이 원활한 사용자 경험을 보장합니다. 이 목표를 달성하려면 Teams, Word, PowerPoint를 비롯한 다른 Microsoft 365 Copilot 허브에서 적응형 카드의 유효성을 검사합니다. 또한 Copilot UI를 축소하고 확장하여 다양한 뷰포트 너비의 유효성을 검사합니다. 이 프로세스를 통해 적응형 카드가 최적으로 작동하고 모든 플랫폼에서 일관된 환경을 제공할 수 있습니다. 다음 모범 사례를 적용합니다.

  • 가능하면 여러 열 레이아웃을 사용하지 마세요. 단일 열 레이아웃은 가장 좁은 뷰포트 너비에서도 잘 렌더링되는 경향이 있습니다.
  • 이미지가 작은 아이콘이나 아바타가 아닌 한 텍스트와 이미지 요소를 같은 행에 배치하지 마세요.
  • 적응형 카드 내의 요소에 고정 너비를 할당하지 마세요. 대신 뷰포트 너비에 따라 크기를 조정할 수 있습니다. 그러나 아이콘 및 아바타와 같은 작은 이미지에는 고정 너비를 할당할 수 있습니다.