구조적 응답 템플릿Structured response template

적용 대상: SDK v4APPLIES TO: SDK v4

구조적 응답 템플릿을 통해 개발자는 템플리팅, 컴퍼지션과 같은 LG(언어 생성)의 광범위한 기능을 지원하는 동시에 구조화된 응답의 해석을 LG 라이브러리 호출자에게 맡기는 복잡한 구조를 정의할 수 있습니다.Structured response templates let developers define a complex structure that supports the extensive functionality of Language generation (LG), like templating, composition, while leaving the interpretation of the structured response up to the caller of the LG library.

Bot 응용 프로그램의 경우 다음 지원이 제공 됩니다.For bot applications, the following support is provided:

Bot Framework 활동 템플릿에는 사용자 지정 가능한 여러 필드가 포함 되어 있습니다.The Bot Framework activity template includes several customizable fields. 다음 속성은 가장 일반적으로 사용 되며 활동 템플릿 정의를 통해 구성할 수 있습니다.The following properties are the most commonly used and are configurable via an activity template definition:

속성Property 사용 사례Use case
텍스트Text 시각적으로 렌더링하기 위해 채널에서 사용하는 텍스트 표시Display text used by the channel to render visually
SpeakSpeak 음성으로 렌더링하기 위해 채널에서 사용하는 음성 텍스트Spoken text used by the channel to render audibly
AttachmentsAttachments 해당 유형의 첨부 파일 목록입니다.List of attachments with their type. 채널에서 UI 카드 또는 기타 일반 파일 첨부 형식으로 렌더링하는 데 사용됩니다.Used by channels to render as UI cards or other generic file attachment types.
SuggestedActionsSuggestedActions 사용자에게 제안으로 렌더링된 작업 목록입니다.List of actions rendered as suggestions to user.
InputHintInputHint 음성 입력을 지원하는 디바이스에서 오디오 캡처 스트림 상태를 제어합니다.Controls audio capture stream state on devices that support spoken input. 가능한 값은 accepting, expecting 또는 ignoring입니다.Possible values include accepting, expecting, or ignoring.

템플릿 확인자에 의해 구현되는 기본 대체(fallback) 동작은 없습니다.There is no default fallback behavior implemented by the template resolver. 속성이 지정되지 않은 경우에는 지정되지 않은 상태로 유지됩니다.If a property is not specified, then it remains unspecified. 예를 들어 Text 속성만 지정된 경우 Speak 속성은 Text 속성으로 자동 할당되지 않습니다.For example, the Speak property isn't automatically assigned to be the Text property if only the Text property is specified.

정의Definition

구조적 템플릿의 정의는 다음과 같습니다.Here's the definition of a structured template:

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression>
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

기본 텍스트 템플릿의 예는 다음과 같습니다.Here's an example of a basic text template:

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

제안된 동작이 있는 텍스트의 예는 다음과 같습니다.Here's an example of text with a suggested action. | 를 사용하여 목록을 나타냅니다.Use | to denote a list.

> With '|' you are making attachments a list.
# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    SuggestedActions = 10 | 20 | 30
]

영웅 카드 정의의 예는 다음과 같습니다.Here's an example of a Hero card definition:

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

참고

LG는 SDK 카드 정의에 맞게 변환 되는 카드 정의의 가변성을 제공 합니다.LG provides some variability in card definition, which is converted to align with the SDK card definition. 예를 들어 image images SDK 카드 정의 에서만 지원 되더라도 및 필드는 모두 LG의 모든 카드 정의에서 지원 됩니다 images .For example, both image and images fields are supported in all the card definitions in LG even though only images are supported in the SDK card definition.

imageHeroCard 또는 미리 보기 카드의 모든 및 필드에 정의 된 값 images 이 결합 되어 생성 된 카드의 이미지 목록으로 변환 됩니다.The values defined in all of the image and images fields in a HeroCard or thumbnail card are combined and converted to an images list in the generated card. 다른 유형의 카드의 경우 템플릿에 마지막으로 정의 된 값이 필드에 할당 됩니다 image .For the other types of cards, the last defined value in the template will be assigned to the image field. 필드에 할당 하는 값은를 image/images 사용 하는 형식의 문자열, 적응 식또는 배열일 수 있습니다 | .The values you assign to the image/images field can be a string, adaptive expression, or array in the format using |.

다음은 이전 템플릿의 조합입니다.Below is the combination of the previous templates:

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
    Attachments = ${HeroCard()}
    SuggestedActions = 10 | 20 | 30
    InputHint = expecting
]

# GetAge
- how old are you?
- what is your age?

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

기본적으로 모든 템플릿 참조는 구조적 템플릿을 평가하는 동안 한 번만 평가됩니다.By default any template reference is evaluated once during evaluation of a structured template.

예를 들어 # AskForAge.promptSpeakText 속성 모두에 대해 동일한 해결 텍스트를 반환합니다.For example, # AskForAge.prompt returns the same resolution text for both the Speak and Text properties.

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

<TemplateName>!()를 사용하여 구조적 템플릿 내의 각 참조에 대한 새 평가를 요청할 수 있습니다.You can use <TemplateName>!() to request a new evaluation on each reference within a structured template.

아래 예제에서는 각 인스턴스에서 GetAge가 다시 평가되기 때문에 SpeakText에는 다른 해결 텍스트가 있을 수 있습니다.In the example below, Speak and Text may have different resolution text because GetAge is re-evaluated on each instance.

[Activity
    Text = ${GetAge()}
    Speak = ${GetAge!()}
]

# GetAge
- how old are you?
- what is your age?

회전식 카드를 표시하는 방법은 다음과 같습니다.Here's how to display a carousel of cards:

# AskForAge.prompt
[Activity
> Defaults to carousel layout in case of list of cards
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
]

# AskForAge.prompt_2
[Activity
> Explicitly specify an attachment layout
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
    AttachmentLayout = list
]

# HeroCard (title, subtitle, text)
[Herocard
    title = ${title}
    subtitle = ${subtitle}
    text = ${text}
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

\ 이스케이프 문자로 사용 합니다.Use \ as an escape character.

> You can use '\' as an escape character
> \${GetAge()} would not be evaluated as expression, would be parsed as '${getAge()}' string
# AskForAge.prompt
[Activity
        Text = \${GetAge()}
        SuggestedActions = 10 \| cards | 20 \| cards
]

구조적 템플릿 컴퍼지션Structured template composition

다음 컴퍼지션 동작은 구조적 템플릿에서 지원됩니다.The following composition behavior is supported with structured templates:

  • 컴퍼지션은 구조 컨텍스트를 인식합니다.Composition is structure context-aware. 참조되는 대상 템플릿이 구조적 템플릿인 경우 구조체 형식이 일치해야 합니다.If the target template being referred is also a structured template, then the structure type must match. 예를 들어 ActivityTemplate은 다른 ActivityTemplate에서 참조할 수 있습니다.For example, an ActivityTemplate can be referred to in another ActivityTemplate.
  • 단순 또는 조건부 응답 템플릿에 대한 참조는 구조적 템플릿 내의 어디에나 있을 수 있습니다.References to simple or conditional response template can exist anywhere inside a structured template.

다음 템플릿이 있다고 가정합니다.Suppose you have the following template:

# T1
[Activity
    Text = ${T2()}
    Speak = foo bar ${T3().speak}
]

# T2
- This is awesome

# T3
[Activity
    Speak = I can also speak!
]

evaluateTemplate('T1')을 호출하면 다음과 같은 내부 구조체가 생성됩니다.A call to evaluateTemplate('T1') would result in the following internal structure:

[Activity
    Text = This is awesome
    Speak = I can also speak!
]

다른 구조적 템플릿에 대한 전체 참조Full reference to another structured template

다른 구조적 템플릿에 대한 참조를 다른 구조적 템플릿의 속성 또는 다른 단순 또는 조건부 응답 템플릿에 참조로 포함될 수 있습니다.You can include a reference to a another structured template as a property in another structured template, or as a reference in another simple or conditional response template

다른 구조적 템플릿에 대한 전체 참조의 예는 다음과 같습니다.Here's an example of full reference to another structured template:

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
]

이 콘텐츠를 통해 evaluateTemplate('ST1')을 호출하면 다음과 같은 내부 구조체가 생성됩니다.With this content, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

호출 템플릿과 호출된 템플릿 모두에 동일한 속성이 있는 경우 호출자의 콘텐츠는 호출된 템플릿의 모든 콘텐츠를 덮어씁니다.When the same property exists in both the calling template as well as the called template, the content in the caller will overwrite any content in the called template.

예를 들면 다음과 같습니다.Here's an example:

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
    Text = zoo
]

이 컨텍스트를 통해 evaluateTemplate('ST1')을 호출하면 다음과 같은 내부 구조체가 생성됩니다.With this context, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

이 컴퍼지션 스타일은 루트 수준에서만 존재할 수 있습니다.Note that this style of composition can only exists at the root level. 속성 내에 다른 구조적 템플릿에 대한 참조가 있는 경우 해결은 해당 속성과 관련이 있습니다.If there is a reference to another structured template within a property, then the resolution is contextual to that property.

첨부 파일의 외부 파일 참조 구조화External file reference in attachment structured

파일을 외부에서 참조하는 데 사용되는 두 가지 미리 빌드된 함수가 있습니다.There are two prebuilt functions used to externally reference files

  1. fromFile(fileAbsoluteOrRelativePath)는 지정된 파일을 로드합니다.fromFile(fileAbsoluteOrRelativePath) loads a specified file. 이 함수에서 반환된 콘텐츠는 콘텐츠 평가를 지원합니다. 템플릿 참조 및 속성/식이 평가됩니다.Content returned by this function will support evaluation of content.Template references and properties/ expressions are evaluated.
  2. 콘텐츠에 아직 지정되지 않은 경우 ActivityAttachment(content, contentType)contentType을 설정합니다.ActivityAttachment(content, contentType) sets the contentType if it is not already specified in the content.

이러한 두 가지 미리 빌드된 함수를 사용하면 모든 카드 유형을 포함하여 외부에서 정의된 모든 콘텐츠를 끌어올 수 있습니다.With these two prebuilt functions, you can pull in any externally defined content, including all card types. 다음 구조적 LG을 사용하여 활동을 구성합니다.Use the following structured LG to compose an activity:

# AdaptiveCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'adaptiveCard')}
]

# HeroCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'heroCard')}
]

아래에 표시되는 첨부 파일을 사용할 수도 있습니다.You can also use attachments, seen below:

# AdaptiveCard
[Attachment
    contenttype = adaptivecard
    content = ${json(fromFile('../../card.json'))}
]

# HeroCard
[Attachment
    contenttype = herocard
    content = ${json(fromFile('../../card.json'))}
]

추가 정보Additional Information