Expressões para acessar objetos no diálogo

É possível escrever expressões que acessam objetos e propriedades de objetos usando a linguagem Spring Expression (SpEL). Para obter mais informações, consulte Spring Expression Language(SpEL).

Sintaxe de avaliação

Para expandir valores variáveis dentro de outras variáveis ou chamar métodos em propriedades e objetos globais, use a sintaxe de expressão <? expression ?>. Por exemplo:

  • Expandindo uma propriedade

    "output":{"text":"Your name is <? context.userName ?>"}

  • Chamando métodos em propriedades de objetos globais

    "context":{"email": "<? @email.literal ?>"}

Sintaxe de abreviação

Saiba como referenciar rapidamente os objetos a seguir usando a sintaxe abreviada de SpEL:

Sintaxe abreviada para variáveis de contexto

A tabela a seguir mostra exemplos da sintaxe abreviada que você pode utilizar para gravar variáveis de contexto em expressões de condição.

Sintaxe de abreviação
Sintaxe de abreviação Sintaxe completa em SpEL
$card_type context['card_type']
$(card-type) context['card-type']
$card_type:VISA context['card_type'] == 'VISA'
$card_type:(MASTER CARD) context['card_type'] == 'MASTER CARD'

É possível incluir caracteres especiais como hifens ou pontos em nomes de variável de contexto. No entanto, fazer isso pode levar a problemas quando a expressão SpEL é avaliada. O hífen pode ser interpretado como um sinal de menos, por exemplo. Para evitar tais problemas, referencie a variável usando a sintaxe de expressão completa ou a sintaxe abreviada $(variable-name) e não use os caracteres especiais a seguir no nome:

  • Parênteses()
  • Mais de um apóstrofo ''
  • Aspas"

Ao referir-se a uma variável de contexto em uma resposta de texto ou condição de nó de diálogo, será possível usar a sintaxe curta.

Por exemplo, Hello, $name. Se a variável de contexto $name contiver Sam, a resposta será mostrada como Hello, Sam.

Se quiser referenciar uma variável de contexto usando a sintaxe completa em uma resposta de texto, certifique-se de cercar a variável de contexto em <? ?>. Por exemplo, Hello, <? context['name'] ?>.

Se quiser referenciar uma variável de contexto que tenha vários campos, como $context.integrations.chat.browser_info.page_url. Para usar a sintaxe completa, especifique <? context['integrations']['chat']['browser_info']['page_url'] ?>.

Sintaxe abreviada para entidades

A tabela a seguir mostra exemplos da sintaxe abreviada que você pode usar ao se referir a entidades.

Sintaxe de abreviação
Sintaxe de abreviação Sintaxe completa em SpEL
@year entities['year']?.value
@year == 2016 entities['year']?.value == 2016
@year != 2016 entities['year']?.value != 2016
@city == 'Boston' entities['city']?.value == 'Boston'
@city:Boston entities['city']?.contains('Boston')
@city:(New York) entities['city']?.contains('New York')

No SpEL, o ponto de interrogação (?) impede que uma exceção de ponteiro nulo seja acionada quando um objeto da entidade for nulo.

Se o valor da entidade que você deseja verificar contiver um caractere ), não será possível usar o operador : para comparação. Por exemplo, se desejar verificar se a entidade city é Dublin (Ohio), você deverá usar @city == 'Dublin (Ohio)' em vez de @city:(Dublin (Ohio)).

Sintaxe abreviada para intenções

A tabela a seguir mostra exemplos da sintaxe abreviada que você pode usar ao se referir a intents.

| Sintaxe de abreviação | Sintaxe completa em SpEL | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help ou #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

Variáveis globais integradas

É possível usar a linguagem de expressão para extrair informações de propriedade para as variáveis globais a seguir:

Variáveis globais
Variável global Definição
*Contexto * Parte de objeto JSON da mensagem de conversa processada.
entities[ ] Lista de entidades que suportam o acesso padrão ao 1st elemento.
entrada Parte de objeto JSON da mensagem de conversa processada.
intenções[ ] Lista de intents que suporta o acesso padrão ao primeiro elemento.
saída Parte de objeto JSON da mensagem de conversa processada.

Acessando entidades

A matriz de entidades contém uma ou mais entidades que foram reconhecidas na entrada do usuário.

Enquanto testa a caixa de diálogo, você pode ver os detalhes das entidades que são reconhecidas na entrada do usuário especificando essa expressão em uma resposta de nó de diálogo:

<? entities ?>

Para a entrada do usuário, hoje, seu assistente reconhece a entidade do sistema @sys-date, portanto, a resposta contém esse objeto da entidade:

 [
   {
     "entity":"sys-date",
     "location":[0,5],
     "value":"2020-12-30",
     "confidence":1.0,
     "metadata":
     {
       "calendar_type":"GREGORIAN",
       "timezone":"America/New_York"
     },
     "interpretation":
     {
       "timezone":"America/New_York",
       "relative_day":0,
       "granularity":"day",
       "calendar_type":"GREGORIAN"
      }
    }
  ]

Se quiser incluir texto na resposta, use o método toJson() na expressão para lançar a lista de entidades retornadas em um objeto JSON. Por exemplo:

Recognized entities are: <? entities.toJson() ?>

Quando o posicionamento de entidades na entrada importa

Quando você usa a expressão abreviada @city.contains('Boston') em uma condição, o nó de diálogo retorna verdadeiro somente se Boston for a primeira entidade detectada na entrada do usuário. Use essa sintaxe somente se o posicionamento das entidades na entrada for importante para você e se quiser verificar somente a primeira menção.

Use a expressão SpEL completa se quiser que a condição retorne verdadeiro sempre que o termo for mencionado na entrada do usuário, independentemente da ordem em que as entidades forem mencionadas. A condição entities['city']?.contains('Boston') retorna verdadeiro quando pelo menos uma entidade de cidade "Boston" é encontrada em todas as entidades @city, independentemente do posicionamento.

Por exemplo, um usuário envia "I want to go from Toronto to Boston." As entidades @city:Toronto e @city:Boston são detectadas e estão representadas na matriz que é retornada da seguinte forma:

  • entities.city[0].value = 'Toronto'
  • entities.city[1].value = 'Boston'

A ordem das entidades na matriz que é retornada corresponde à ordem na qual elas são mencionadas na entrada do usuário.

Propriedades da entidade

Cada entidade tem um conjunto de propriedades associadas a ela. É possível acessar informações sobre uma entidade através de suas propriedades.

Propriedades da entidade
Propriedade Definição Dicas de uso
confidence Uma porcentagem decimal que representa a confiança de seu assistente na entidade reconhecida. A confiança de uma entidade é 0 ou 1, a menos que você ative a correspondência difusa de entidades. Quando a correspondência difusa está ativada, o limite de nível de confiança padrão é 0,3. Se a correspondência difusa estiver ativada, as entidades do sistema sempre terão um nível de confiança de 1.0. Será possível usar essa propriedade em uma condição para que ela retorne falso se o nível de confiança não for maior que um percentual especificado.
local Um deslocamento de caractere baseado em zero que indica onde os valores de entidade detectados começam e terminam no texto de entrada. Use .literal para extrair o período de texto entre os valores de índice iniciais e finais que estão armazenados na propriedade localização.
valor O valor da entidade identificado na entrada. Essa propriedade retorna o valor da entidade conforme definido nos dados de treinamento, mesmo se a correspondência foi feita contra um de seus sinônimos associados. É possível usar .values para capturar várias ocorrências de uma entidade que podem estar presentes na entrada do usuário.

Exemplos de uso da propriedade da entidade

Nos exemplos a seguir, a qualificação contém uma entidade de aeroporto que inclui um valor de JFK e o sinônimo "Kennedy Airport". A entrada do usuário é I want to go to Kennedy Airport.

  • Para retornar uma resposta específica se a entidade "JFK" for reconhecida na entrada do usuário, você pode adicionar esta expressão à condição de resposta: entities.airport[0].value == 'JFK' ou @airport = "JFK"

  • Para retornar o nome da entidade como foi especificado pelo usuário na resposta da caixa de diálogo, use a propriedade .literal : So you want to go to <?entities.airport[0].literal?>... ou So you want to go to @airport.literal ...

Ambos os formatos são avaliados em So you want to go to Kennedy Airport... na resposta.

  • Expressões como @airport:(JFK) ou @airport.contains('JFK') sempre referem-se ao valor da entidade (JFK neste exemplo).

  • Para ser mais restritivo sobre quais termos são identificados como aeroportos na entrada quando a correspondência difusa estiver ativada, é possível especificar essa expressão em uma condição de nó, por exemplo: @airport && @airport.confidence > 0.7. O nó é executado somente se o assistente tiver 70% de certeza de que o texto de entrada contém uma referência de aeroporto.

Nesse exemplo, a entrada do usuário é Há lugares para troca de moeda no JFK, Logan e O'Hare?

  • Para capturar diversas ocorrências de um tipo de entidade na entrada do usuário, use uma sintaxe como esta:

    "context":{
  "airports":"@airport.values"
}

    Para referir-se posteriormente à lista capturada em uma resposta de diálogo, use esta sintaxe: You asked about these airports: <? $airports.join(', ') ?>. Ela é exibida como esta: You asked about these airports: JFK, Logan, O'Hare.

  • Para capturar os valores literais para várias menções de entidade, use a sintaxe a seguir:

    entities['myEntityName'].![literal]

Acessando intenções

A matriz intents contém uma ou mais intents que foram reconhecidas na entrada do usuário, que é classificada em ordem decrescente de confiança.

Cada intenção tem somente uma propriedade: a propriedade confidence. A propriedade de confiança é uma porcentagem decimal que representa a confiança de seu assistente na intenção reconhecida.

Ao testar a caixa de diálogo, você pode ver detalhes das intenções reconhecidas na entrada do usuário especificando essa expressão em uma resposta de nó de diálogo:

<? intents ?>

Para a entrada do usuário, Hello now, seu assistente localiza uma correspondência exata com a intenção #greeting. Portanto, ele lista os detalhes do objeto de intenção #greeting primeiro. A resposta também inclui as outras 10 principais intenções que estão definidas na qualificação, independentemente da sua pontuação de confiança. (Neste exemplo, sua confiança nas outras intenções é configurada para 0 porque a primeira intenção é uma correspondência exata.) As 10 principais intenções são retornadas porque a área de janela "Experimente" envia o parâmetro alternate_intents:true com sua solicitação. Se você está usando a API diretamente e deseja ver os 10 resultados principais, certifique-se de especificar esse parâmetro em sua chamada. Se alternate_intents for false, que é o valor padrão, somente as intenções com uma confiança maior que 0.2 serão retornadas na matriz.

[{"intent":"greeting","confidence":1},
{"intent":"yes","confidence":0},
{"intent":"pizza-order","confidence":0}]

Se quiser incluir texto na resposta, use o método toJson() na expressão para lançar as intenções retornadas em um objeto JSON. Por exemplo:

Recognized intents are: <? intents.toJson() ?>

Os exemplos a seguir mostram como verificar um valor de intenção:

  • intents[0] == 'Help'
  • intent == 'Help'

intent == 'help' difere de intents[0] == 'help' porque intent == 'help' não lança uma exceção se nenhuma intenção for detectada. Ela é avaliada como verdadeira somente se a confiança na intenção exceder um limite. Se desejar, você pode especificar um nível de confiança personalizado para uma condição, por exemplo, intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Acessando a entrada

O objeto JSON de entrada contém uma única propriedade: a propriedade de texto. A propriedade de texto representa o texto da entrada do usuário.

Exemplos de uso da propriedade de entrada

O exemplo a seguir mostra como acessar a entrada:

  • Para executar um nó se a entrada do usuário for "Sim", inclua esta expressão na condição de nó: input.text == 'Yes'

É possível usar qualquer Método de sequência para avaliar ou manipular texto da entrada do usuário. Por exemplo:

  • Para verificar se a entrada do usuário contém "Yes", use: input.text.contains( 'Yes' ).
  • Retorna verdadeiro se a entrada do usuário for um número: input.text.matches( '[0-9]+' ).
  • Para verificar se a cadeia de entrada contém dez caracteres, use: input.text.length() == 10.