使用環境定義個人化對話

若要個人化交談，您的助理可以從客戶收集資訊，然後稍後在交談中參照該資訊。

跨對話回合保留資訊

對話是無狀態的，表示它不會在與使用者的不同互動之間保留資訊。當您將對話新增至助理並部署它時，助理會從一個訊息呼叫中儲存環境定義，然後在整個現行階段作業的下一個要求中重新提交該環境定義。當使用者與助理互動時，現行階段作業會持續進行，加上指定的階段作業閒置時間範圍。階段作業閒置時間上限的容許範圍從 5 分鐘至 7 天，視您的計劃類型而定。如果您未將對話新增至助理，則身為自訂應用程式開發人員，您必須負責維護應用程式所需的任何持續資訊。

應用程式可以將資訊傳遞給對話，而對話可以更新此資訊，並將它傳回給應用程式或後續節點。對話會使用環境定義變數 來執行此動作。

環境定義變數

環境定義變數是您在節點中定義的變數。您可以為其指定預設值。然後，其他節點、應用程式邏輯或使用者輸入可以設定或變更環境定義變數的值。

環境定義變數值的條件設定方式是從對話節點條件中參照環境定義變數以判斷是否執行節點。您也可以從對話節點回應條件參照環境定義變數，以根據外部服務或使用者所提供的值來顯示不同的回應。

瞭解更多：

從應用程式傳遞環境定義
將環境定義從節點傳遞給節點
定義環境定義變數
一般環境定義變數作業
刪除環境定義變數
更新環境定義變數
如何處理環境定義變數
作業順序
將環境定義變數新增至含空位的節點

從應用程式傳遞環境定義

設定環境定義變數並將環境定義變數傳遞給對話，即可將資訊從應用程式傳遞給對話。

例如，您的應用程式可以設定 $time_of_day 環境定義變數，並將它傳遞至對話，該對話可使用資訊來修改對使用者顯示的問候語。

顯示「歡迎使用」節點，該節點使用回應條件來檢查從應用程式傳遞至對話的 $time_of_day 環境定義變數值。 — 日期時間環境定義

在此範例中，對話知道應用程式將變數設為下列其中一個值：morning、afternoon 或 evening。它可以檢查每一個值，並視呈現的值傳回適當的問候語。如果未傳遞變數，或變數的值不符合其中一個預期值，則會向使用者顯示更一般的問候語。

將環境定義從節點傳遞給節點

對話也可以新增環境定義變數以在不同的節點之間傳遞資訊，或是更新環境定義變數的值。當對話要求並從使用者取得資訊時，它可以追蹤資訊並稍後在交談中參照它。

例如，在某個節點中，您可能會詢問使用者的名稱，並在後面的節點中，依名稱來處理使用者。

顯示一個簡介節點，該節點向使用者詢問其名稱，並將其儲存為環境定義變數。下一個節點使用 $username 環境定義變數依名稱參照使用者。 — 將環境定義從一個節點傳遞至另一個節點

在此範例中，如果使用者提供使用者名稱，則會使用系統實體 @name 從輸入中擷取使用者名稱。在 JSON 編輯器中，使用者名稱環境定義變數已定義並設為 @name 值。在後續節點中，回應中會包含 $username 環境定義變數，以依名稱來處理使用者。

定義環境定義變數

若要定義環境定義變數，請在節點的編輯視圖中，將變數名稱新增至變數欄位，然後將其預設值新增至值欄位。

按一下以開啟您要新增環境定義變數的對話節點。
移至 助理回應 區段，然後按一下功能表圖示。
按一下開啟環境定義編輯器。
將變數名稱/值配對對新增至變數和值欄位。
- name 可以包含任何大寫及小寫英文字母字元、數值字元 (0-9) 及底線。
- value 可以是任何支援的 JSON 類型，例如簡字組串變數、數字、JSON 陣列或 JSON 物件。

下表顯示一些範例，說明如何為不同類型的值定義名稱/值配對：

定義名稱/值配對
可變	值	值類型
dessert	"cake"	字串
age	18	Number
toppings_array	`["onions","olives"]`	JSON 陣列
full_name	`{"first":"John","last":"Doe"}`	JSON 物件

然後，若要參照這些環境定義變數，請使用語法 $name，其中 name 是您定義的環境定義變數名稱。

例如，您可以指定下列表示式作為對話回應：

The customer, $age-year-old <? $full_name.first ?>, wants a pizza with <? $toppings_array.join(' and ') ?>, and then $dessert.

產生的輸出顯示如下：

The customer, 18-year-old John, wants a pizza with onions and olives, and then cake.

您也可以使用 JSON 編輯器來定義環境定義變數。如果您要新增複式表示式作為變數值，則最好是使用 JSON 編輯器。如需詳細資料，請參閱 JSON 編輯器中的環境定義變數。

一般環境定義變數作業

若要儲存使用者所提供的整個字串作為輸入，請使用 input.text：

擷取使用者輸入
可變	值
repeat	`<?input.text?>`

例如，使用者輸入可能是 I want to order a device. 如果節點回應是 You said: $repeat，則回應會顯示為 You said: I want to order a device.

若要將實體的值儲存在環境定義變數，請使用下列語法：

擷取實體提及項目
可變	值
place	`@place`

例如，使用者輸入可能是 I want to go to Paris. 如果 @place 實體可辨識 Paris，則助理會將 Paris 儲存在 $place 環境定義變數中。

若要儲存從使用者輸入中擷取的字串值，您可以包括 SpEL 表示式，其使用 extract 方法將正規表示式套用至使用者輸入。下列表示式會擷取使用者輸入中的數字，並將它儲存至 $number 環境定義變數。

使用字串方法
可變	值
數字	`<?input.text.extract('[\d]+',0)?>`

若要儲存型樣實體的值，請在實體名稱後面加上 .literal。使用此語法可確保使用者輸入中符合指定型樣的確切文字段儲存在變數中。

擷取型樣實體值
可變	值
電子郵件	`<? @email.literal ?>`

例如，使用者輸入是 Contact me at joe@example.com. 您的實體 (名為 @email ) 可辨識 name@domain.com 電子郵件格式。藉由配置環境定義變數來儲存 @email.literal，您可以指出要儲存輸入中符合型樣的那一部分。如果您省略值表示式中的 .literal 內容，則會傳回您指定給型樣的實體值名稱，而不是符合型樣的使用者輸入區段。

刪除環境定義變數

若要刪除環境定義變數，請將變數設為空值。

將環境定義變數設為空值
可變	值
order_form	`null`

更新環境定義變數值

若要更新環境定義變數的值，請使用與前一個環境定義變數相同的名稱來定義環境定義變數，但這次，請為它指定不同的值。

當多個節點設定相同環境定義變數的值時，環境定義變數的值會隨著使用者的交談過程而變更。所套用的值取決於使用者在交談過程中所觸發的節點。在處理的最後一個節點中，為環境定義變數指定的值，會改寫先前已處理之節點針對該變數所設定的任何值。

如需在值為 JSON 物件或 JSON 陣列資料類型時，如何更新環境定義變數值的相關資訊，請參閱更新格式為 JSON 的環境定義變數值。

如何處理環境定義變數

您定義環境定義變數的位置至關重要。在助理處理您在其中定義環境定義變數的對話節點部分之前，不會建立環境定義變數，也不會設為您為其指定的值。在大部分情況下，您將環境定義變數定義為節點回應的一部分。當您這麼做時，在助理傳回節點回應時，會建立環境定義變數並提供指定的值。

對於具有條件式回應的節點，會在符合特定回應的條件並處理該回應時，建立及設定環境定義變數。例如，如果您為條件式回應 #1 定義環境定義變數，且助理處理回應 #2，則不會設定您為條件式回應 #1 定義的變數。

如需在使用者與含空位的節點互動時新增您想要助理設定的環境定義變數的相關資訊，請參閱將環境定義變數新增至含空位的節點。

作業順序

當您定義多個要一起處理的變數時，您定義變數的順序並不會決定助理評估這些變數的順序。助理會依隨機順序來評估這些變數。請勿在第一個環境定義變數中設定值，並預期在第二個變數中使用該值，因為第一個環境定義變數可能不會在第二個環境定義變數之前執行。例如，請不要使用兩個環境定義變數來實作邏輯，其用來檢查使用者輸入是否包含 Yes 這個字。

使用兩個環境定義變數來檢查使用者輸入中的值
可變	值
user_input	`<? input.text ?>`
contains_yes	`<? $user_input.contains('Yes') ?>`

請改用略為複雜的表示式，避免一定要先評估清單中第一個變數 (user_input) 的值，然後才能評估第二個變數 (contains_yes)。

使用單一環境定義變數
可變	值
contains_yes	`<? input.text.contains('Yes') ?>`

將環境定義變數新增至含空位的節點

如需空位的相關資訊，請參閱使用空位收集資訊。

若要新增在符合空位的回應條件之後處理的環境定義變數，請執行下列動作:

在編輯視圖中開啟含空位的節點。
按一下 自訂空位 圖示。
按一下選項圖示，然後選取 啟用條件。
按一下您要與環境定義變數相關聯的回應旁的 自訂處理程式 圖示。
按一下「助理」回應區段中的選項圖示，然後按一下 開啟環境定義編輯器。
將變數名稱/值配對對新增至變數和值欄位。

若要新增在符合空位條件之後再進行設定或更新的環境定義變數，請執行下列步驟：

在編輯視圖中開啟含空位的節點。
按一下 自訂空位 圖示。
按一下選項圖示，然後選取 啟用條件。
新增 JSON 格式的變數名稱/值配對。

{
"time_of_day": "morning"
}

您無法使用環境定義編輯器來定義在此對話節點評估階段期間所設定的環境定義變數。您必須改用 JSON 編輯器。如需使用 JSON 編輯器的相關資訊，請參閱 JSON 編輯器中的環境定義變數。

JSON 編輯器中的環境定義變數

您也可以在 JSON 編輯器中定義環境定義變數。如果您要定義複式環境定義變數，且想要能夠在新增或變更時看到完整 SpEL 表示式，請使用 JSON 編輯器。

名稱/值配對必須符合以下需求：

name 可以包含任何大寫及小寫英文字母字元、數值字元 (0-9) 及底線。

您可以在名稱中包括其他字元，例如句點及連字號。不過，如果您這麼做，則每次參照變數時都必須指定速記語法 $(variable-name)。如需詳細資料，請參閱存取物件的表示式。
value 可以是任何支援的 JSON 類型，例如簡字組串變數、數字、JSON 陣列或 JSON 物件。

下列 JSON 範例定義 $dessert 字串、$toppings_array 陣列、$age 數字及 $full_name 物件環境定義變數的值：

{
  "context": {
    "dessert": "cake",
    "toppings_array": [
      "onions",
      "olives"
    ],
    "age": 18,
    "full_name": {
      "first": "Jane",
      "last": "Doe"
    }
  },
  "output":{}
}

若要定義 JSON 格式的環境定義變數，請完成下列步驟：

按一下以開啟您要新增環境定義變數的對話節點。

針對此節點所定義的全部現有環境定義變數值都會顯示在一組對應的變數及值欄位中。如果您不希望它們顯示在節點的編輯視圖中，則必須關閉環境定義編輯器。您可以從用來開啟 JSON 編輯器的相同功能表中關閉此編輯器；下列步驟說明如何存取功能表。
按一下助理回應的選項圖示，然後按一下 開啟 JSON 編輯器。

如果節點已啟用 多重條件式回應 設定，則您必須先針對要與環境定義變數相關聯的回應，按一下 自訂回應 圖示。
新增 "context":{} 區塊（如果不存在的話）。
```
{
  "context":{},
  "output":{}
}
```
在環境定義區塊中，針對您要定義的每個環境定義變數，新增 "name" 及 "value" 配對。
```
{
  "context":{
    "name": "value"
},
  "output": {}
}
```
在此範例中，名為 new_variable 的變數會新增至已包含變數的環境定義區塊。
```
{
  "context":{
    "existing_variable": "value",
    "new_variable":"value"
  }
}
```
若要參照環境定義變數，請使用語法 $name，其中 name 是您定義的環境定義變數名稱。例如，$new_variable。

瞭解更多：

刪除格式為 JSON 的環境定義變數
更新格式為 JSON 的環境定義變數值
將某個環境定義變數設為等於另一個

刪除格式為 JSON 的環境定義變數

若要刪除環境定義變數，請將變數設為空值。

{
  "context": {
    "order_form": null
  }
}

如果您要移除環境定義變數的全部追蹤，則可以使用 JSONObject.remove(string) 方法將它從環境定義物件刪除。不過，您必須使用變數來執行移除。在訊息輸出中定義新變數，使其不會儲存在現行呼叫之外。

{
  "output": {
    "text" : {},
    "deleted_variable" : "<? context.remove('order_form') ?>"
  }
}

或者，您可以在應用程式邏輯中刪除環境定義變數。

更新格式為 JSON 的環境定義變數值

一般而言，如果節點設定已設定的環境定義變數值，則新值會改寫先前的值。

更新複雜 JSON 物件

會改寫所有 JSON 類型的先前值，但 JSON 物件除外。如果 context 變數是複雜類型（例如 JSON 物件），則會使用 JSON 合併程序來更新變數。合併作業會新增任何新定義的內容，並改寫物件的任何現有內容。

在此範例中，會將名稱環境定義變數定義為複雜物件。

{
  "context": {
    "complex_object": {
      "user_firstname" : "Paul",
      "user_lastname" : "Pan",
      "has_card" : false
    }
  }
}

對話節點會將環境定義變數 JSON 物件更新為下列值：

{
  "complex_object": {
    "user_firstname": "Peter",
    "has_card": true
  }
}

結果是下列環境定義：

{
  "complex_object": {
    "user_firstname": "Peter",
    "user_lastname": "Pan",
    "has_card": true
  }
}

更新陣列

如果對話環境定義資料包含值的陣列，您可以藉由附加值、移除值或取代所有值來更新陣列。

選擇下列其中一個動作來更新陣列。在每一種情況下，我們會在動作之前看到陣列、動作，以及在套用動作之後看到陣列。

附加：若要將值新增至陣列尾端，請使用 append 方法。

針對此「對話」運行環境定義：

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

進行下列更新：

{
  "context": {
    "toppings_array": "<? $toppings_array.append('ketchup', 'tomatoes') ?>"
  }
}

結果：

{
  "context": {
    "toppings_array": ["onion", "olives", "ketchup", "tomatoes"]
  }
}

移除：若要移除元素，請使用 remove 方法，並在陣列中指定其值或位置。

依值移除：會依元素值從陣列中移除元素。

針對此「對話」運行環境定義：

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

進行下列更新：

{
  "context": {
    "toppings_array": "<? $toppings_array.removeValue('onion') ?>"
  }
}

結果：

{
  "context": {
    "toppings_array": ["olives"]
  }
}

依位置移除：會依元素的索引位置從陣列中移除元素。

針對此「對話」運行環境定義：

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

進行下列更新：

{
  "context": {
    "toppings_array": "<? $toppings_array.remove(0) ?>"
  }
}

結果：

{
  "context": {
    "toppings_array": ["olives"]
  }
}

改寫: 如果要改寫陣列中的值，請將陣列設為新值:

針對此「對話」運行環境定義：

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

進行下列更新：

{
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

結果：

{
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

將某個環境定義變數設為等於另一個

當您將某個環境定義變數設為等於另一個環境定義變數時，要定義一個指標，從某個環境定義變數指向另一個。稍後，如果其中一個變數的值變更，則另一個變數的值也會變更。

例如，如果您指定如下的環境定義變數，則當 $var1 或 $var2 稍後的值變更時，其他值也會變更。

將某個環境定義變數設為等於另一個
可變	值
var2	var1

請不要將某個變數設為等於另一個變數，以用來擷取復原點值。使用陣列，如果您想要擷取儲存在環境定義變數中的陣列值，並稍後使用它，請改為根據變數的現行值來建立新變數。

例如，若要在某個點建立陣列值的副本，請新增一個陣列，其中會移入現有陣列的值。若要這樣做，您可以使用下列語法：

{
"context": {
   "var2": "<? output.var2?:new JsonArray().append($var1) ?>"
 }
 }