범용 작업 모델
Context
적응형 카드는 앱과 서비스에서 공유할 수 있는 간단한 JSON 형식을 사용하여 작성된 플랫폼 기반이 아닌 UI 조각입니다. 적응형 카드는 호스트의 모양과 느낌에 맞게 조정될 뿐만 아니라 풍부한 상호 작용 기능도 제공합니다. 적응형 카드에 대한 자세한 내용은 adaptivecards.io를 방문하세요.
적응형 카드가 널리 사용됨에 따라 여러 호스트에서 다양한 작업 모델을 지원하기 시작했고 이로 인해 조각화가 발생되었습니다. 이 문제를 해결하기 위해 Teams, Outlook 및 적응형 카드 팀에서 호스트 간에 호환되는 새 범용 봇 작업 모델을 만드는 작업을 수행했습니다. 이러한 노력의 결과는 다음과 같습니다.
- 봇 및 Bot Framework의 일반화 - Teams(봇) 및 Outlook(실행 가능 메시지) 모두에 대해 적응형 카드 기반 시나리오를 구현하는 방법
Action.Submit(현재 봇에서 사용) 및Action.Http(현재 실행 가능 메시지에서 사용)를 모두 대체하는Action.Execute- 봇에서 사용할 수 있는 실행 가능 메시지에서만 지원되는 인기 있는 기능:
- 카드를 표시할 때 새로 고치는 기능
- 클라이언트에 즉시 표시되도록 업데이트된 카드를 반환하는
Action.Execute작업의 기능
Outlook의 실행 가능 메시지에 대한 자세한 내용은 실행 가능 메시지 설명서를 참조하세요.
Teams의 범용 작업으로 가능한 다양한 시나리오에 대한 자세한 내용은 Teams 카드 참조를 참조하세요.
Action.Execute 이전 |
Action.Execute 사용 |
|---|---|
 |
 |
 |
 |
출처: 적응형 카드 @ Microsoft Build 2020
이 문서의 나머지 부분에서는 Teams 및 Outlook의 컨텍스트에서 범용 봇 작업 모델을 문서화하는 데 중점을 둡니다. 봇을 사용하는 Teams에서 이미 적응형 카드를 사용하고 있는 경우 몇 가지 항목을 변경하여 동일한 봇을 통해 Action.Execute를 지원할 수 있습니다. Outlook에서 실행 가능 메시지를 사용하는 경우 Action.Execute를 지원하는 봇을 개발해야 합니다. 현재 Outlook 클라이언트에서 범용 봇 작업 모델을 지원하는 기능을 활발하게 개발하고 있습니다.
스키마
중요
범용 봇 작업 모델은 적응형 카드 스키마 버전 1.4에서 도입되었습니다. 이러한 새 기능을 사용하려면 아래 예제와 같이 적응형 카드의
version속성을 1.4 이상으로 설정해야 합니다. 이렇게 하면 적응형 카드가 범용 봇 작업 모델을 지원하지 않는 이전 클라이언트(Outlook 또는 Teams)와 호환되지 않습니다.
refresh속성 및/또는Action.Execute를 사용하고 < 1.4의 카드 버전을 지정하는 경우 다음과 같은 동작이 발생합니다.
클라이언트 동작 Outlook 카드가 작동하지 않습니다. refresh가 적용되지 않으며,Action.Execute가 렌더링되지 않습니다. 카드가 완전히 거부될 수도 있습니다.Teams Teams 클라이언트 버전에 따라 카드가 작동하지 않을 수 있습니다( refresh가 적용되지 않을 수 있으며Action.Execute작업이 렌더링되지 않을 수 있음).
Teams에서 최대한의 호환성을 보장하려면fallback속성에서Action.Submit작업을 사용하여Action.Execute작업을 정의하는 것이 좋습니다.자세한 내용은 아래의 이전 버전과의 호환성 섹션을 참조하세요.
Action.Execute
적응형 카드를 작성할 때 Action.Submit 및 Action.Http 대신 Action.Execute를 사용합니다. Action.Execute의 스키마는 Action.Submit의 스키마와 매우 비슷합니다.
JSON 예제
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "Present a form and submit it back to the originator"
},
{
"type": "Input.Text",
"id": "firstName",
"placeholder": "What is your first name?"
},
{
"type": "Input.Text",
"id": "lastName",
"placeholder": "What is your last name?"
},
{
"type": "ActionSet",
"actions": [
{
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsFormSubmit",
"fallback": "Action.Submit"
}
]
}
]
}
속성
| 속성 | 형식 | 필수 | 설명 |
|---|---|---|---|
| type | "Action.Execute" |
예 | "Action.Execute"이어야 합니다. |
| 동사 | string | 아니요 | 개발자가 작업을 식별하는 데 사용할 수 있는 편리한 문자열입니다. |
| data | string, object |
아니요 | 입력 필드가 결합되는 초기 데이터입니다. 이러한 속성은 기본적으로 '숨겨진' 속성입니다. |
| title | string |
아니요 | 이 작업을 나타내는 단추 또는 링크에 대한 레이블입니다. |
| iconUrl | uri |
아니요 | 제목과 함께 작업에 표시되는 선택적 아이콘입니다. 데이터 URI는 적응형 카드 버전 1.2 이상에서 지원합니다. |
| style | ActionStyle |
아니요 | 작업을 표시하고 말하는 등의 방식의 영향을 주는 Action의 스타일을 제어합니다. |
| fallback | <action object>, "drop" |
아니요 | 카드를 표시하는 클라이언트에서 Action.Execute가 지원되지 않는 경우 수행할 작업을 설명합니다. |
| requires | Dictionary<string> |
아니요 | 해당 최소 버전과 함께 항목에 필요한 기능을 나타내는 일련의 키/값 쌍입니다. 기능이 없거나 버전이 낮으면 fallback(대체)이 트리거됩니다. |
새로 고침 메커니즘
이제 Action.Execute와 함께 새 새로 고침 메커니즘이 지원되므로 표시될 때 자동으로 업데이트되는 적응형 카드를 만들 수 있습니다. 이렇게 하면 사용자는 항상 최신 데이터를 볼 수 있습니다. 일반적인 새로 고침 사용 사례는 승인 요청입니다. 승인되면 이미 완료되었을 때 승인을 요청하는 카드를 사용자에게 제공하지 않고 요청이 승인된 시간과 승인한 주체에 대한 정보를 대신 제공하는 것이 가장 좋습니다.
적응형 카드가 자동으로 새로 고치도록 허용하려면 Action.Execute 형식의 action 및 userIds 배열을 포함하는 refresh 속성을 정의합니다.
| 속성 | 형식 | 필수 | 설명 |
|---|---|---|---|
| 작업 | "Action.Execute" |
예 | "Action.Execute" 형식의 작업 인스턴스여야 합니다. |
| userIds | Array<string> |
예 | 자동 새로 고침을 사용하도록 설정해야 하는 사용자에 대한 MRI의 배열입니다.중요: userIds 목록 속성이 카드의 refresh 섹션에 포함되어 있지 않으면 카드는 자동으로 새로 고쳐지지 않습니다. 대신 사용자에게 수동으로 새로 고칠 수 있는 단추가 표시됩니다. 이는 많은 수의 멤버가 Teams의 채팅/채널에 포함될 수 있기 때문입니다. 많은 멤버가 동시에 채널을 보고 있는 경우 무조건 자동 새로 고침으로 인해 봇에 대한 동시 호출이 많이 발생하여 크기가 조정되지 않습니다. 잠재적인 크기 조정 문제를 완화하려면 자동 새로 고침을 받아야 하는 사용자를 식별하기 위해 현재 최대 60개의 사용자 ID가 허용되는 userIds 속성을 항상 포함해야 합니다. 자세한 내용은 새로 고침의 userIds를 참조하세요.userIds 속성은 Outlook에서 무시되며, refresh 속성은 항상 자동으로 적용됩니다. 사용자가 일반적으로 다른 시간에 카드를 볼 수 있으므로 Outlook에는 크기 조정 문제가 없습니다. |
JSON 샘플
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
"version": "1.4",
"refresh": {
"action": {
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsCardRefresh"
},
"userIds": []
},
"body": [
{
"type": "TextBlock",
"text": "Present a form and submit it back to the originator"
},
{
"type": "Input.Text",
"id": "firstName",
"placeholder": "What is your first name?"
},
{
"type": "Input.Text",
"id": "lastName",
"placeholder": "What is your last name?"
},
{
"type": "ActionSet",
"actions": [
{
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsFormSubmit",
"fallback": "Action.Submit"
}
]
}
]
}
Outlook 실행 가능 메시지 개발자를 위한 중요 참고 사항
Outlook 실행 가능 메시지 시나리오를 개발하는 경우 적응형 카드의 originator 속성을 지정해야 합니다. originator는 봇에서 Outlook 채널을 구독할 때 생성되는 GUID(Globally Unique Identifier)입니다. 이는 Outlook에서 적응형 카드가 권한 있는 봇을 통해 보내졌는지 확인하는 데 사용됩니다. originator가 없는 경우 적응형 카드는 Outlook에서 렌더링되지 않습니다. originator는 Teams에서 무시됩니다.
adaptiveCard/action Invoke(호출) 작업
클라이언트에서 Action.Execute가 실행되면(새로 고침 작업인지, 아니면 사용자가 단추를 클릭하여 명시적으로 수행되는 작업인지에 관계없이) 봇에 새 형식의 Invoke 작업(adaptiveCard/action)이 수행됩니다. 일반적인 adaptiveCard/action Invoke 작업 요청은 다음과 같습니다.
요청 형식
{
"type": "invoke",
"name": "adaptiveCard/action",
// ... other properties omitted for brevity
"value": {
"action": {
"type": "Action.Execute",
"id": "abc",
"verb": "def",
"data": { ... }
},
"trigger": "automatic | manual"
}
}
| 필드 | 설명 |
|---|---|
| value.action | 적응형 카드에 정의된 작업의 복사본입니다. Action.Submit과 마찬가지로 작업의 data 속성에는 카드의 다양한 입력 값이 포함됩니다(있는 경우). |
| value.trigger | 작업이 명시적으로 트리거되었는지(사용자의 단추 클릭을 통해), 아니면 암시적으로 트리거되었는지(자동 새로 고침을 통해)를 나타냅니다. |
응답 형식
봇에서 들어오는 adaptiveCard/action Invoke 작업을 처리하는 경우(즉, 봇의 코드가 요청을 처리하는 데 모두 관련되는 경우) 봇에서 반환하는 HTTP 응답의 상태 코드는 200이어야 하며 HTTP 응답 본문은 다음과 같은 형식이어야 합니다.
{
"statusCode": <number (200 – 599)>,
"type": "<string>",
"value": "<object>"
}
| 필드 | 설명 |
|---|---|
| 상태코드 | HTTP 응답 상태 코드 200이 반드시 봇에서 요청을 성공적으로 처리할 수 있었음을 의미하는 것은 아닙니다. 클라이언트 애플리케이션은 항상 응답 본문의 statucCode 속성을 확인하여 봇에서 요청을 처리한 방법을 인식해야 합니다. statusCode는 HTTP 상태 코드 값을 미러링하는 200~599 범위의 숫자이며, Invoke를 처리하는 봇의 결과에 대한 하위 상태를 나타냅니다. statusCode에 대해 누락되었거나, null이거나, 정의되지 않은 값은 200(성공)을 의미합니다. |
| type | value 속성의 예상 셰이프를 설명하는 잘 알려진 문자열 상수 세트입니다. |
| value | 응답 본문의 형식과 관련된 개체입니다. |
지원되는 상태 코드
다음 표에는 봇의 응답 본문에서 허용되는 statusCode, type 및 value 값이 나와 있습니다.
| 상태 코드 | Type | 값 스키마 | 주의 |
|---|---|---|---|
| 200 | application/vnd.microsoft.card.adaptive |
Adaptive Card |
요청이 성공적으로 처리되었으며, 응답에는 클라이언트에서 현재 카드 대신 표시해야 하는 적응형 카드가 포함됩니다. |
| 200 | application/vnd.microsoft.activity.message |
string |
요청이 성공적으로 처리되었으며, 응답에는 클라이언트에서 표시해야 하는 메시지가 포함됩니다. |
| 400 | application/vnd.microsoft.error |
오류 개체(할 일: 링크 필요) | 들어오는 요청이 잘못되었습니다. |
| 401 | application/vnd.microsoft.activity.loginRequest |
OAuthCard(할 일: 링크 필요) | 클라이언트에서 사용자에게 인증하라는 메시지를 표시해야 합니다. |
| 401 | application/vnd.microsoft.error.inccorectAuthCode |
null | 클라이언트에서 전달한 인증 상태가 잘못되어 인증에 실패했습니다. |
| 412 | application/vnd.microsoft.error.preconditionFailed |
오류 개체(할 일: 링크 필요) | SSO 인증 흐름이 실패했습니다. |
| 500 | application/vnd.microsoft.error |
오류 개체(할 일: 링크 필요) | 예기치 않은 오류가 발생했습니다. |
요약: 범용 봇 작업 모델을 활용하는 방법
Action.Execute대신Action.Submit를 사용합니다. Teams에서 기존 시나리오를 업데이트하려면Action.Submit의 모든 인스턴스를Action.Execute로 바꿉니다. Outlook에서 기존 시나리오를 업데이트하려면 아래의 '이전 버전과의 호환성' 섹션을 참조하세요.- 카드가 Outlook에 표시되도록 하려면
originator필드를 추가합니다. 위의 JSON 샘플을 참조하세요. - 자동 새로 고침 메커니즘을 활용하려거나 시나리오에 사용자별 보기가 필요한 경우
refresh절을 적응형 카드에 추가합니다. 자동 업데이트를 받을 사용자(최대 60명)를 식별하려면userIds속성을 지정해야 합니다. - 봇에서
adaptiveCard/actionInvoke 요청을 처리합니다. Action.Execute를 처리한 결과로 봇에서 새 카드를 반환해야 할 때마다 Invoke 요청의 컨텍스트를 사용하여 특정 사용자에 대해 특별히 작성된 카드를 생성할 수 있습니다. 응답이 위에서 정의된 응답 스키마를 따르는지 확인합니다.
이전 버전과의 호환성
Outlook
새 Action.Execute 범용 작업 모델은 Outlook 실행 가능 메시지에서 현재 사용되는 Action.Http 작업 모델에서 출발합니다. 여기서 작업은 적응형 카드에서 명시적 HTTP 호출로 인코딩됩니다. 개발자는 Action.Execute 모델을 사용하여 Outlook 및 Teams 모두에서 "바로 작동"하는 시나리오를 구현할 수 있습니다. 실행 가능 메시지 시나리오에서는 Action.Http 모델 또는 새 Action.Execute 모델 중 하나를 사용할 수 있으며, 둘 다 사용할 수는 없습니다. 범용 Action.Execute 모델을 사용하는 시나리오를 봇으로 구현하고 Outlook Actionable Messages 채널을 구독해야 합니다.
중요한 참고 사항
- 범용
Action.Execute모델을 사용하여 구현된 시나리오는 이전 버전의 Outlook과 호환되지 않습니다.- 현재 기존의 실행 가능 메시지 시나리오를 범용
Action.Execute모델로 원활하게 마이그레이션하기 위한 작업이 진행되고 있습니다.
Teams
카드가 이전 버전과 호환되고 이전 버전의 Teams 사용자를 위해 작동하려면 Action.Execute 작업에 Action.Submit으로 정의된 fallback 속성이 포함되어야 합니다. Action.Execute 및 Action.Submit을 모두 처리할 수 있는 방식으로 봇을 코딩해야 합니다. Action.Submit을 처리할 때 봇에서 새 카드를 반환할 수 없으므로 Action.Submit을 통한 대체 동작은 최종 사용자에게 성능이 저하된 환경을 제공합니다.
중요 정보
일부 이전 Teams 클라이언트는
ActionSet에 래핑되지 않은 경우 fallback(대체) 속성을 지원하지 않습니다. 이러한 클라이언트에서 중단하지 않으려면ActionSet에서 모든Action.Execute를 래핑하는 것이 가장 좋습니다.ActionSet에서Action.Execute를 래핑하는 방법은 아래 예제를 참조하세요.
아래 예제에서 카드의 version 속성은 1.2로 설정되고, Action.Execute는 해당 fallback으로 Action.Submit을 사용하여 정의됩니다. 적응형 카드 1.4를 지원하는 Teams 클라이언트에서 렌더링되는 경우 Action.Execute가 예상대로 렌더링되고 작동합니다. 적응형 카드 1.4를 지원하지 않는 Teams 클라이언트에서는 Action.Execute 대신 Action.Submit이 렌더링됩니다.
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"body": [
{
"type": "TextBlock",
"text": "Present a form and submit it back to the originator"
},
{
"type": "Input.Text",
"id": "firstName",
"placeholder": "What is your first name?"
},
{
"type": "Input.Text",
"id": "lastName",
"placeholder": "What is your last name?"
},
{
"type": "ActionSet",
"actions": [
{
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsFormSubmit",
"fallback": {
"type": "Action.Submit",
"title": "Submit"
}
}
]
}
]
}