在對話框中存取物件的表示式

您可以使用「Spring 表示式語言 (SpEL)」語言，來撰寫存取物件及物件內容的表示式。有關更多信息，請參閱 Spring 表達式語言(SpEL)。

評估語法

若要在其他變數中擴展變數值或呼叫屬性和全域物件上的方法，請使用 <? expression ?>表達式語法。例如：

擴展內容

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

對廣域物件的內容呼叫方法

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

速記語法

學習如何使用 SpEL 速記語法來快速參照下列物件：

環境定義變數
Entities
目的

環境定義變數的速記語法

下表顯示可用來在條件表示式中撰寫環境定義變數的速記語法範例。

速記語法
速記語法	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'`

您可以在環境定義變數名稱中包含特殊字元（例如連字號或句點）。不過，在評估 SpEL 表示式時，這麼做可能會導致問題。例如，連字符可能被解釋為減號。若要避免這類問題，請使用完整表示式語法或速記語法 $(variable-name) 來參照變數，而且不要在名稱中使用下列特殊字元：

括弧 ()
多個撇號 ''
引號 "

當您參照文字回應或對話節點條件中的環境定義變數時，可以使用簡短語法。

例如，Hello, $name。如果 $name 環境定義變數包含 Sam，則回應會顯示為 Hello, Sam。

如果您想在文字回應中使用完整語法來引用上下文變量，請務必將上下文變數括在 <? ?>。例如，Hello, <? context['name'] ?>。

如果您想要參照具有多個欄位的環境定義變數，例如 $context.integrations.chat.browser_info.page_url。若要使用完整語法，請指定 <? context['integrations']['chat']['browser_info']['page_url'] ?>。

實體的速記語法

下表顯示了引用實體時可以使用的速記語法範例。

速記語法
速記語法	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')`

在 SpEL 中，問號 (?) 會防止在實體物件為空值時觸發空值指標異常狀況。

如果您要檢查的實體值包含 ) 字元，則無法使用 : 運算子進行比較。例如，如果您要檢查城市實體是否為 Dublin (Ohio)，則必須使用 @city == 'Dublin (Ohio)'，而非 @city:(Dublin (Ohio))。

目的的速記語法

下表顯示了引用意圖時可以使用的速記語法範例。

內建廣域變數

您可以使用表示式語言來擷取下列廣域變數的內容資訊：

廣域變數
廣域變數	定義
context	已處理交談訊息的 JSON 物件部分。
entities[ ]	支援預設存取1st元素的實體清單。
輸入	已處理交談訊息的 JSON 物件部分。
目的[ ]	支援預設存取第一個元素的意圖清單。
output	已處理交談訊息的 JSON 物件部分。

存取實體

entities 陣列包含使用者輸入中所辨識的一個以上實體。

在測試對話方塊時，您可以透過在對話方塊節點回應中指定此表達式來查看在使用者輸入中識別的實體的詳細資訊：

<? entities ?>

對於使用者輸入今天，助理會辨識 @sys-date 系統實體，因此回應包含此實體物件:

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

如果您想要在回應中包括文字，請在表示式中使用 toJson() 方法，將傳回的實體清單強制轉型為 JSON 物件。例如：

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

實體在輸入中的放置位置很重要時

當您使用簡寫表達式時 @city.contains('Boston') 在某個條件下，對話節點僅在以下情況下傳回 true Boston 是在使用者輸入中偵測到的第一個實體。僅當輸入中實體的放置對您很重要且您只想檢查第一個提及時才使用此語法。

如果您希望條件在使用者輸入中提及術語時傳回 true，請使用完整的 SpEL 表達式，無論提及實體的順序為何。條件 entities['city']?.contains('Boston') 當在所有 @city 實體中至少找到一個「波士頓」城市實體時，會傳回 true，無論位置為何。

例如，使用者提交 "I want to go from Toronto to Boston." 偵測到 @city:Toronto 及 @city:Boston 實體，並在傳回的陣列中呈現如下:

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

所傳回陣列中的實體順序符合其在使用者輸入中的提及順序。

實體內容

每個實體都有一組與其關聯的屬性。您可以透過實體內容來存取實體的相關資訊。

實體內容
內容	定義	用法提示
信賴度	十進位百分比，代表助理對於已辨識實體的信賴度。實體的置信度為 0 或 1，除非您啟動實體的模糊匹配。已啟用模糊比對時，預設信賴水準臨界值為 0.3。無論是否啟用模糊匹配，系統實體的置信度始終為 1.0。	如果信賴水準未高於指定的百分比，您可以在條件中使用此內容，使其傳回 false。
位置	以零為起始的字元偏移，指出偵測到的實體值在輸入文字中的開始及結束位置。	使用 `.literal`，以擷取 location 內容中所儲存之開始與結束索引值之間的文字段。
值	輸入中識別的實體值。	此內容會傳回訓練資料中定義的實體值，即使比對是針對其中一個相關聯的同義字進行也一樣。您可以使用 `.values` 來擷取可能在使用者輸入中多次出現的實體。

實體內容用法範例

在下列範例中，技能包含內含 JFK 值及同義字 'Kennedy Airport" 的機場實體。使用者輸入是 “我想去甘迺迪機場”。

若要在使用者輸入中識別出「JFK」實體時傳回特定回應，您可以將此表達式新增至回應條件： entities.airport[0].value == 'JFK' 或 @airport = "JFK"
若要傳回使用者在對話方塊回應中指定的實體名稱，請使用 .literal 財產： So you want to go to <?entities.airport[0].literal?>... 或 So you want to go to @airport.literal ...

兩種格式的計算結果為 So you want to go to Kennedy Airport... 在回應中。

表示式（如 @airport:(JFK) 或 @airport.contains('JFK')）一律會參照實體的 value（在此範例中為 JFK）。
若要更嚴格地限制在已啟用模糊比對時將哪些術語識別為機場，您可以在節點條件中指定此表示式，例如：@airport && @airport.confidence > 0.7。只有當您的助手有 70% 的信心輸入文字包含機場參考時，該節點才會執行。

在此範例中，使用者輸入是 Are there places to exchange currency at JFK, Logan, and O'Hare?

若要擷取使用者輸入中多次出現的實體類型，請使用下列這類語法：
```
"context":{
  "airports":"@airport.values"
}
```
若要稍後在對話回應中參照擷取的清單，請使用下列語法: You asked about these airports: <? $airports.join(', ') ?>. 它顯示如下： You asked about these airports: JFK, Logan, O'Hare.
若要擷取多個實體提及項目的文字值，請使用下列語法：
```
entities['myEntityName'].![literal]
```

存取目的

意圖數組包含在使用者輸入中識別的一個或多個意圖，按置信度降序排序。

每一個目的都只有一個內容：confidence 內容。 confidence 內容是一個十進位百分比，代表助理對於已辨識目的的信賴度。

在測試對話方塊時，您可以透過在對話方塊節點回應中指定此表達式來查看在使用者輸入中識別的意圖的詳細資訊：

<? intents ?>

針對使用者輸入 Hello now，助理會尋找含有 #greeting 目的的完全相符項。因此，它會先列出 #greeting 目的物件詳細資料。回應也會包含技能中所定義的前 10 個其他目的，而不論其信賴分數為何。（在此範例中，它對其他目的的信賴度設為 0，因為第一個目的是完全相符項。）會傳回前 10 個目的，因為「試用」窗格會傳送 alternate_intents:true 參數及其要求。如果您要直接使用 API，而且想要查看前 10 個結果，則請務必在呼叫中指定此參數。如果 alternate_intents 為 false，這是預設值，只有置信度高於 0.2 的意圖才會在數組中傳回。

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

如果您想要在回應中包括文字，請在表示式中使用 toJson() 方法，將傳回的目的清單強制轉型為 JSON 物件。例如：

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

下列範例顯示如何檢查目的值：

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

intent == 'help' 與 intents[0] == 'help' 不同，因為 intent == 'help' 在偵測不到目的時不會擲出異常狀況。只有在目的信賴度超出臨界值時，它才會評估為 true。如果需要，您可以為條件指定自訂置信度，例如，intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1。

存取輸入

輸入 JSON 物件只包含一個內容：text 內容。 text 內容代表使用者輸入的文字。

輸入內容用法範例

下列範例顯示如何存取輸入：

若要在使用者輸入為“是”時執行節點，請將此表達式新增至節點條件： input.text == 'Yes'

您可以使用任何字串方法來評估或操作使用者輸入中的文字。例如：

若要檢查使用者輸入是否包含 "Yes"，請使用：input.text.contains( 'Yes' )。
如果使用者輸入是數字，則會傳回 true：input.text.matches( '[0-9]+' )。
若要檢查輸入字串是否包含 10 個字元，請使用：input.text.length() == 10。