Plantilla de respuesta estructuradaStructured response template

se aplica a: SDK V4APPLIES TO: SDK v4

Las plantillas de respuesta estructurada permiten a los desarrolladores definir una estructura compleja que admite la funcionalidad ampliada de Language Generation, la cual incluye la creación de plantillas y la redacción, a la vez que se deja la interpretación de la respuesta estructurada a criterio del autor de la llamada de la biblioteca de Language Generation.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.

En el caso de las aplicaciones de bot, se proporciona la siguiente compatibilidad:For bot applications, the following support is provided:

La Bot Framework de actividad incluye varios campos personalizables.The Bot Framework activity template includes several customizable fields. Las siguientes propiedades son las más usadas y se pueden configurar a través de una definición de plantilla de actividad:The following properties are the most commonly used and are configurable via an activity template definition:

PropiedadProperty Caso de usoUse case
TextoText Mostrar el texto utilizado por el canal para representarlo visualmenteDisplay text used by the channel to render visually
SpeakSpeak Texto hablado que el canal usa para la representación de forma audibleSpoken text used by the channel to render audibly
Datos adjuntosAttachments Lista de datos adjuntos con su tipo.List of attachments with their type. Lo usan los canales para la representación como tarjetas de interfaz de usuario u otros tipos de datos adjuntos de archivo genéricos.Used by channels to render as UI cards or other generic file attachment types.
SuggestedActionsSuggestedActions Lista de las acciones representadas como sugerencias para el usuario.List of actions rendered as suggestions to user.
InputHintInputHint Controla el estado de la secuencia de captura de audio en los dispositivos que admiten entradas de voz.Controls audio capture stream state on devices that support spoken input. Los posibles valores incluyen accepting, expecting o ignoring.Possible values include accepting, expecting, or ignoring.

No hay ningún comportamiento de reserva predeterminado implementado por el solucionador de plantillas.There is no default fallback behavior implemented by the template resolver. Si no se especifica una propiedad, esta permanece sin especificar.If a property is not specified, then it remains unspecified. Por ejemplo, la propiedad Speak no se asigna automáticamente para ser la propiedad Text si solo se especifica la propiedad Text.For example, the Speak property isn't automatically assigned to be the Text property if only the Text property is specified.

DefiniciónDefinition

A continuación se muestra la definición de una plantilla estructurada: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
]

Este es un ejemplo de una plantilla de texto básica: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?

Este es un ejemplo de texto con una acción sugerida.Here's an example of text with a suggested action. Use | para indicar una lista.Use | to denote a list.

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

A continuación se muestra un ejemplo de definición de una tarjeta Hero: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
]

Nota

LG proporciona cierta variabilidad en la definición de tarjeta, que se convierte para alinearse con la definición de tarjeta del SDK.LG provides some variability in card definition, which is converted to align with the SDK card definition. Por ejemplo, los campos y se admiten en todas las definiciones de tarjeta de LG, aunque solo se admiten image images en la images definición de tarjeta del SDK.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.

Los valores definidos en todos los campos y de una tarjeta HeroCard o thumbnail se combinan y se convierten en una lista de imágenes image images en la tarjeta generada.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. Para los otros tipos de tarjetas, el último valor definido en la plantilla se asignará al image campo .For the other types of cards, the last defined value in the template will be assigned to the image field. Los valores que asigne al campo pueden ser una cadena, una expresión adaptable o image/images una matriz con el formato | .The values you assign to the image/images field can be a string, adaptive expression, or array in the format using |.

A continuación se muestra la combinación de las plantillas anteriores: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
]

De forma predeterminada, cualquier referencia de plantilla se evalúa una vez durante la evaluación de una plantilla estructurada.By default any template reference is evaluated once during evaluation of a structured template.

Por ejemplo, # AskForAge.prompt devuelve el mismo texto de resolución para las propiedades Speak y Text.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?

Puede usar <TemplateName>!() para solicitar una nueva evaluación en cada referencia de una plantilla estructurada.You can use <TemplateName>!() to request a new evaluation on each reference within a structured template.

En el ejemplo siguiente, Speak y Text pueden tener texto de resolución diferente porque GetAge se vuelve a evaluar en cada instancia.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?

Aquí se indica cómo mostrar un carrusel de tarjetas: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 \ como carácter de escape.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
]

Composición de plantilla estructuradaStructured template composition

El siguiente comportamiento de composición es compatible con las plantillas estructuradas:The following composition behavior is supported with structured templates:

  • La composición depende del contexto de la estructura.Composition is structure context-aware. Si la plantilla de destino a la que se va a hacer referencia es también una plantilla estructurada, el tipo de estructura debe coincidir.If the target template being referred is also a structured template, then the structure type must match. Por ejemplo, se puede hacer referencia a una plantilla de ActivityTemplate en otra plantilla de ActivityTemplate.For example, an ActivityTemplate can be referred to in another ActivityTemplate.
  • Las referencias a una plantilla de respuesta simple o condicional pueden existir en cualquier parte de una plantilla estructurada.References to simple or conditional response template can exist anywhere inside a structured template.

Supongamos que tiene la siguiente plantilla: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!
]

Una llamada a evaluateTemplate('T1') daría lugar a la siguiente estructura interna:A call to evaluateTemplate('T1') would result in the following internal structure:

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

Referencia completa a otra plantilla estructuradaFull reference to another structured template

Puede incluir una referencia a otra plantilla estructurada como una propiedad de otra plantilla estructurada o como una referencia en otra plantilla de respuesta simple o condicional.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

Este es un ejemplo de referencia completa a otra plantilla estructurada:Here's an example of full reference to another structured template:

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

Con este contenido, una llamada a evaluateTemplate('ST1') dará como resultado la siguiente estructura interna:With this content, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

Cuando existe la misma propiedad en la plantilla que realiza la llamada como en la que la recibe, el contenido del autor de la llamada sobrescribirá cualquier contenido de la plantilla a la que se ha llamado.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.

Este es un ejemplo:Here's an example:

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

Con este contexto, una llamada a evaluateTemplate('ST1') dará como resultado la siguiente estructura interna:With this context, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

Tenga en cuenta que este estilo de composición solo puede existir en el nivel raíz.Note that this style of composition can only exists at the root level. Si hay una referencia a otra plantilla estructurada en una propiedad, la resolución depende del contexto para esa propiedad.If there is a reference to another structured template within a property, then the resolution is contextual to that property.

Referencia externa a archivos en datos adjuntos estructuradosExternal file reference in attachment structured

Hay dos funciones precompiladas que se usan para hacer referencia a archivos de forma externaThere are two prebuilt functions used to externally reference files

  1. fromFile(fileAbsoluteOrRelativePath) carga un archivo especificado.fromFile(fileAbsoluteOrRelativePath) loads a specified file. El contenido devuelto por esta función será compatible con la evaluación del contenido. Se evalúan las referencias de plantilla y las propiedades y expresiones.Content returned by this function will support evaluation of content.Template references and properties/ expressions are evaluated.
  2. ActivityAttachment(content, contentType) establece el contentType si aún no se ha especificado en el contenido.ActivityAttachment(content, contentType) sets the contentType if it is not already specified in the content.

Con estas dos funciones precompiladas, puede extraer cualquier contenido definido externamente, incluidos todos los tipos de tarjeta.With these two prebuilt functions, you can pull in any externally defined content, including all card types. Use la siguiente instancia de Language Generation para crear una actividad: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')}
]

También puede usar los datos adjuntos que se muestran a continuación: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'))}
]

Información adicionalAdditional Information