Ausdrücke für den Zugriff auf Objekte im Dialog

Zum Schreiben von Ausdrücken für den Zugriff auf Objekte und Objekteigenschaften können Sie die Ausdruckssprache SpEL (Spring Expression Language) verwenden. Weitere Informationen finden Sie unter Spring Expression Language(SpEL).

Auswertungssyntax

Verwenden Sie die <? expression ?>-Ausdruckssyntax, um Variablenwerte in anderen Variablen zu erweitern oder Methoden für Eigenschaften und globale Objekte aufzurufen. Beispiel:

  • Eigenschaft erweitern

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

  • Methoden für Eigenschaften globaler Objekte aufrufen

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

Kurzformsyntax

Erfahren Sie, wie mit der Kurzformsyntax SpEL schnell auf die folgenden Objekte verwiesen werden kann:

Kurzformsyntax für Kontextvariablen

In der folgenden Tabelle sind Beispiele für die Kurzformsyntax aufgeführt, die Sie zum Schreiben von Kontextvariablen in Bedingungsausdrücken verwenden können.

Kurzformsyntax
Kurzformsyntax Vollständige Syntax in 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'

In den Namen von Kontextvariablen können Sie Sonderzeichen wie Bindestriche oder Punkte verwenden. Dies kann allerdings zu Problemen bei der Auswertung des SpEL-Ausdrucks führen. Der Bindestrich kann z. B. als Minuszeichen interpretiert werden. Referenzieren Sie die Variable zur Vermeidung solcher Probleme entweder mit der vollständigen Ausdruckssyntax oder der Kurzformsyntax $(variable-name) und verwenden Sie im Namen keines der folgenden Sonderzeichen:

  • Klammern ()
  • Mehr als ein Hochkomma ''
  • Anführungszeichen "

Wenn Sie eine Kontextvariable in einer Textantwort oder in einer Dialogmodulknotenbedingung referenzieren, können Sie die Kurzsyntax verwenden.

Beispiel: Hello, $name. Wenn die Kontextvariable $name den Namen Sam enthält, wird die Antwort wie folgt angezeigt: Hello, Sam.

Wenn Sie auf eine Kontextvariable verweisen möchten, indem Sie die vollständige Syntax in einer Textantwort verwenden, müssen Sie die Kontextvariable in <? ?> einschließen. Beispiel: Hello, <? context['name'] ?>.

Wenn Sie eine Kontextvariable referenzieren wollen, die mehrere Felder hat, wie zum Beispiel $context.integrations.chat.browser_info.page_url, Um die vollständige Syntax zu verwenden, geben Sie <? context['integrations']['chat']['browser_info']['page_url'] ?> an.

Kurzformsyntax für Entitäten

Die folgende Tabelle zeigt Beispiele für die Kurzsyntax, die Sie verwenden können, wenn Sie sich auf Entitäten beziehen.

Kurzformsyntax
Kurzformsyntax Vollständige Syntax in 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')

In SpEL verhindert das Fragezeichen (?), dass eine Null-Verweisausnahme ausgelöst wird, wenn ein Entitätsobjekt null ist.

Falls der Entitätswert, den Sie überprüfen wollen, ein Zeichen ) enthält, können Sie nicht den Operator : für Vergleiche verwenden. Falls Sie beispielsweise prüfen wollen, ob die Entität 'city' den Wert Dublin (Ohio) besitzt, müssen Sie @city == 'Dublin (Ohio)' anstelle von @city:(Dublin (Ohio)) verwenden.

Kurzformsyntax für Absichten

Die folgende Tabelle enthält Beispiele für die Kurzsyntax, die Sie verwenden können, wenn Sie sich auf Intents beziehen.

| Kurzsyntax | Vollständige Syntax in SpEL | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help oder #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

Integrierte globale Variablen

Mit der Ausdruckssprache können Sie Eigenschaftsinformationen für die folgenden globalen Variablen extrahieren:

Globale Variablen
Globale Variable Definition
Kontext Der Teil der verarbeiteten Dialognachricht mit dem JSON-Objekt.
entities[ ] Liste der Entitäten, die den Standardzugriff auf das 1st Element unterstützen.
Eingabe Der Teil der verarbeiteten Dialognachricht mit dem JSON-Objekt.
Absichten[ ] Liste von Intents, die den Standardzugriff auf das erste Element unterstützt.
Ausgabe Der Teil der verarbeiteten Dialognachricht mit dem JSON-Objekt.

Auf Entitäten zugreifen

Das Entitätsarray enthält eine oder mehrere Entitäten, die in der Benutzereingabe erkannt wurden.

Während Sie Ihren Dialog testen, können Sie Details zu den Entitäten sehen, die in den Benutzereingaben erkannt werden, indem Sie diesen Ausdruck in einer Dialogknotenantwort angeben:

<? entities ?>

Für die Benutzereingabe heute erkennt Ihr Assistent die Systementität @sys-date, sodass die Antwort das folgende Entitätsobjekt enthält:

 [
   {
     "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"
      }
    }
  ]

Wenn Sie Text in die Antwort einschließen wollen, verwenden Sie die Methode toJson() im Ausdruck, um die Liste der zurückgegebenen Entitäten in ein JSON-Objekt umzusetzen. Beispiel:

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

Relevanz der Position von Entitäten in der Eingabe

Wenn Sie den Kurzausdruck @city.contains('Boston') in einer Bedingung verwenden, gibt der Dialogknoten true zurück nur wenn Boston ist die erste Entität, die in der Benutzereingabe erkannt wird. Verwenden Sie diese Syntax nur, wenn Ihnen die Platzierung der Entitäten in der Eingabe wichtig ist und Sie nur die erste Erwähnung prüfen wollen.

Verwenden Sie den vollständigen SpEL, wenn Sie möchten, dass die Bedingung immer dann wahr ist, wenn der Begriff in der Benutzereingabe erwähnt wird, unabhängig von der Reihenfolge, in der die Entitäten erwähnt werden. Die Bedingung entities['city']?.contains('Boston') gibt true zurück, wenn mindestens eine "Boston"-Stadt-Entität in allen @city-Entitäten gefunden wird, unabhängig von der Platzierung.

Beispiel: Ein Benutzer schickt "I want to go from Toronto to Boston." ab. Die Entitäten @city:Toronto und @city:Boston werden erkannt und in dem Array dargestellt, das wie folgt zurückgegeben wird:

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

Die Reihenfolge der Entitäten in dem zurückgegebenen Array entspricht der Reihenfolge ihrer Erwähnung in der Benutzereingabe.

Entitätseigenschaften

Jede Entität hat eine Reihe von Eigenschaften, die mit ihr verbunden sind. Über die Eigenschaften können Sie auf Informationen zu einer Entität zugreifen.

Entitätseigenschaften
Eigenschaft Definition Tipps zur Verwendung
confidence Ein als Dezimalzahl ausgedrückter Prozentsatz, der die Konfidenz des Assistenten in der erkannten Entität darstellt. Das Vertrauen in eine Entität ist entweder 0 oder 1, es sei denn, Sie aktivieren die unscharfe Zuordnung von Entitäten. Falls die unscharfe Suche aktiviert ist, liegt der Standardschwellenwert für das Konfidenzniveau bei 0,3. Unabhängig davon, ob der unscharfe Abgleich aktiviert ist, haben Systementitäten immer ein Konfidenzniveau von 1.0. Sie können diese Eigenschaft in einer Bedingung verwendet, damit 'false' zurückgegeben wird, wenn das Konfidenzniveau nicht höher als ein von Ihnen angegebener Prozentsatz ist.
Standort Eine relative Zeichenposition mit der Basis null, die angibt, wo der erkannte Entitätswert im Eingabetext beginnt und endet. Mit .literal können Sie den Bereich des Textes zwischen den Start- und Endindexwerten extrahieren, die in der Eigenschaft 'location' gespeichert sind.
wert Der in der Eingabe ermittelte Entitätswert. Diese Eigenschaft gibt den Entitätswert so zurück, wie er in den Trainingsdaten definiert ist, und zwar auch dann, wenn die Übereinstimmung mit einem der zugehörigen Synonyme vorlag. Mit .values können Sie mehrere Vorkommen einer Entität erfassen, die möglicherweise in der Benutzereingabe enthalten sind.

Verwendungsbeispiele für Entitätseigenschaften

In den folgenden Beispielen enthält der Skill eine Entität 'airport', die den Wert 'JFK' und das Synonym 'Kennedy Airport' enthält. Die Benutzereingabe lautet: Ich möchte zum Kennedy-Flughafen fahren.

  • Um eine bestimmte Antwort zurückzugeben, wenn die Entität "JFK" in der Benutzereingabe erkannt wird, können Sie diesen Ausdruck zur Antwortbedingung hinzufügen: entities.airport[0].value == 'JFK' oder @airport = "JFK"

  • Um den Entitätsnamen so zurückzugeben, wie er vom Benutzer in der Dialogantwort angegeben wurde, verwenden Sie die Eigenschaft .literal : So you want to go to <?entities.airport[0].literal?>... oder So you want to go to @airport.literal ...

Beide Formate werden in der Antwort auf So you want to go to Kennedy Airport... ausgewertet.

  • Ausdrücke wie @airport:(JFK) oder @airport.contains('JFK') referenzieren immer den Wert der Entität (im Beispiel JFK).

  • Um die Erkennung von Begriffen als Flughäfen in der Eingabe strenger einzugrenzen, wenn die unscharfe Suche aktiviert ist, können Sie diesen Ausdruck in einer Knotenbedingung wie beispielsweise @airport && @airport.confidence > 0.7 angeben. Der Knoten wird nur ausgeführt, wenn Ihr Assistent zu 70 % sicher ist, dass der Eingabetext einen Flughafenbezug enthält.

Im Beispiel lautet die Benutzereingabe Are there places to exchange currency at JFK, Logan, and O'Hare?

  • Um mehrere Vorkommen eines Entitätstyps in einer Benutzereingabe zu erfassen, verwenden Sie eine Syntax wie die Folgende:

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

    Verwenden Sie die folgende Syntax, um später in einer Dialogantwort auf die erfasste Liste zu verweisen: You asked about these airports: <? $airports.join(', ') ?>. Die Darstellung sieht jetzt so aus: You asked about these airports: JFK, Logan, O'Hare.

  • Verwenden Sie die folgende Syntax, um die Literalwerte für mehrere Entitätserwähnungen zu erfassen:

    entities['myEntityName'].![literal]

Auf Absichten zugreifen

Das Array intents enthält eine oder mehrere Intents, die in der Benutzereingabe erkannt wurden, sortiert in absteigender Reihenfolge des Vertrauens.

Jede Absicht besitzt nur eine einzige Eigenschaft, nämlich die Eigenschaft confidence. Die Eigenschaft 'confidence' gibt einen als Dezimalzahl ausgedrückten Prozentsatz an, der die Konfidenz des Assistenten bezüglich der erkannten Absicht darstellt.

Während Sie Ihren Dialog testen, können Sie Details zu den Absichten, die in den Benutzereingaben erkannt werden, sehen, indem Sie diesen Ausdruck in einer Antwort auf einen Dialogknoten angeben:

<? intents ?>

Für die Benutzereingabe Hello now findet der Assistent eine exakte Übereinstimmung mit der Absicht '#greeting'. Darum werden die Details des Absichtsobjekts '#greeting' zuerst aufgelistet. Die Antwort enthält außerdem die 10 häufigsten anderen Absichten, die im Know-how definiert sind, unabhängig von der zugehörigen Konfidenzbewertung. (Im vorliegenden Beispiel wird der Konfidenzwert für die anderen Absichten auf 0 gesetzt, da die erste Absicht eine exakte Übereinstimmung ist.) Die 10 Absichten mit den höchsten Werten werden zurückgegeben, da in der Anforderung der Anzeige 'Ausprobieren' der Parameter alternate_intents:true übergeben wird. Wenn Sie unmittelbar mit der API arbeiten und die 10 höchsten Ergebnisse sehen möchten, geben Sie in Ihrem Aufruf unbedingt diesen Parameter an. Wenn alternate_intents false ist, was der Standardwert ist, werden nur Intents mit einer Konfidenz von mehr als 0.2 in das Array zurückgegeben.

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

Wenn Sie Text in die Antwort einschließen wollen, verwenden Sie die Methode toJson() im Ausdruck, um die zurückgegebene Liste der Absichten in ein JSON-Objekt umzusetzen. Beispiel:

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

Die folgenden Beispiele zeigen, wie Sie die Eingabe auf einen Absichtswert überprüfen können.

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

intent == 'help' unterscheidet sich von intents[0] == 'help', weil intent == 'help' keine Ausnahmebedingung auslöst, wenn keine Absicht erkannt wird. Eine Auswertung mit 'true' findet nur dann statt, wenn die Konfidenz der Absicht einen Schwellenwert überschreitet. Wenn Sie möchten, können Sie ein benutzerdefiniertes Konfidenzniveau für eine Bedingung angeben, z. B. intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Auf Eingabe zugreifen

Das JSON-Eingabeobjekt enthält eine einzige Eigenschaft, nämlich die Eigenschaft 'text'. Die Eigenschaft 'text' stellt den Text der Benutzereingabe dar.

Verwendungsbeispiele für Eingabeeigenschaften

Das folgende Beispiel zeigt, wie auf die Eingabe zugegriffen wird:

  • Fügen Sie den folgenden Ausdruck zur Knotenbedingung hinzu, um einen Knoten auszuführen, wenn die Benutzereingabe "Ja" lautet: input.text == 'Yes'

Zur Auswertung oder Bearbeitung von Text aus der Benutzereingabe können Sie jede der Methoden für Zeichenfolgen verwenden. Beispiel:

  • Um zu überprüfen, ob die Benutzereingabe 'Yes' enthält, verwenden Sie input.text.contains( 'Yes' ).
  • Um 'true' zurückzugeben, wenn die Benutzereingabe eine Zahl ist, verwenden Sie input.text.matches( '[0-9]+' ).
  • Um zu überprüfen, ob die Eingabezeichenfolge zehn Zeichen enthält, verwenden Sie input.text.length() == 10.