使用 API 修改對話框

REST API 支援以程式化方式修改對話。您可以使用 /dialog_nodes API 來建立、刪除或修改對話節點。

對話是交互連接節點的樹狀結構，且必須符合某些規則才有效。您對對話節點所做的任何變更可能會對其他節點或對話結構產生重疊顯示效果。在使用 /dialog_nodes API 來修改對話之前，請確定您瞭解變更對對話其餘部分的影響。您可以建立現行對話框的備份副本如需相關資訊，請參閱備份及還原資料。

有效的對話一律會滿足下列準則：

每一個對話節點都有唯一的 ID（dialog_node 內容）。
子節點知道其母節點（parent 內容）。不過，母節點並不知道其子項。
節點知道其緊鄰的上一個同層級（如果有的話）（previous_sibling 內容）。所有共用母項的同層級都會形成鏈結清單，每一個節點都指向前一個節點。
母項只有一個子項可以是第一個同層級 (表示其 previous_sibling 是空值)。
節點無法指向作為不同母項之子項的上一個同層級。
兩個節點不得指向相同的上一個同層級。
節點可以指定下一個要執行的另一個節點 ( next_step 內容)。
節點不能是它自己的母項或它自己的同層級。
節點必須要有包含下列其中一個值的 type 內容。如果未指定 type 內容，則類型是 standard。
- event_handler：針對訊框節點或個別空位節點所定義的處理程式。
從工具中，您可以按一下含空位之節點中的管理處理程式鏈結，來定義訊框節點處理程式。（工具使用者介面不會公開空位層次事件處理程式，但您可以透過 API 定義一個空位層次事件處理程式。）
- frame：有一個以上 slot 類型之子節點的節點。必須先填入所有必要子空位節點，服務才能離開訊框節點。
在工具中，訊框節點類型會呈現為含空位的節點。包含空位的節點以類型 =frame 的節點表示。它是每一個空位的母節點，其表示為類型 slot 的子節點。
- response_condition：條件式回應。
在工具中，您可以將一個以上條件式回應新增至節點。在基礎 JSON 中，您定義的每一個條件式回應都會呈現為 type=response_condition 的個別節點。
- slot：frame 類型之節點的子節點。
此節點類型在工具中表示為新增至單一節點的多個空位之一。在 JSON 中，此單一節點會呈現為 frame 類型的母節點。
- standard：一般對話節點。這是預設類型。
對於類型為 slot 且具有相同母節點的節點，同層級順序 (由 previous_sibling 內容指定) 反映處理空位的順序。
slot 類型的節點必須具有 frame 類型的母節點。
frame 類型的節點必須至少要有一個 slot 類型的子節點。
response_condition 類型的節點必須具有 standard 或 frame 類型的母節點。
response_condition 及 event_handler 類型的節點不能有子項。
event_handler 類型的節點也必須具有 event_name 內容，此內容包含下列其中一個值以識別節點事件的類型：
- filled: 定義如果使用者提供的值符合空位之檢查欄位中指定的條件，且空位已填滿時要執行的動作。只有在已針對空位定義「找到」條件時，才會有具有此名稱的處理程式。
- focus: 定義問題以顯示提示使用者提供空位所需的資訊。只有在需要空位時，才會有具有此名稱的處理程式。
- generic：定義要監看的條件，以處理使用者在填入空位或含空位之節點時可能會詢問的無關問題。
- input：更新訊息環境定義，以包含環境定義變數，以及從使用者收集而用來填入空位的值。訊框節點中的每一個空位都必須要有具有此名稱的處理程式。
- nomatch：定義如果使用者對空位提示的回應未包含有效值時要執行的動作。只有在已針對空位定義「找不到」條件時，才會有具有此名稱的處理程式。
下圖說明您在工具使用者介面中定義針對每一個具名事件所觸發之程式碼的位置。

事件處理程式
event_handler 類型且 event_name 為 generic 的節點可以有 slot 或 frame 類型的母項。
event_handler 類型且 event_name 為 focus、input、filled 或 nomatch 類型的節點必須要有 slot 類型的母項。
如果多個具有相同 event_name 的 event_handler 與相同的母節點相關聯，則同層級的順序是事件處理程式的執行順序。
不論節點定義的位置為何，具有相同母項空位節點的 event_handler 節點，執行順序都會相同。會依 event_name 的下列順序觸發事件：
1. focus
2. input
3. filled
4. generic*
5. nomatch
- 如果針對此空位或母框架定義具有 event_name generic 的 event_handler，則會在填入及 nomatch event_handler 節點之間執行。

下列範例顯示各種修改如何導致可能的連鎖變更。

建立節點

請考量下列簡單對話樹狀結構：

我們可以藉由向 /dialog_nodes 提出具有下列內文的 POST 要求，來建立新的節點：

{
  "dialog_node": "node_8"
}

對話現在看起來像這樣：

因為已建立 node_8，但未指定 parent 或 previous_sibling 的值，所以它現在是對話中的第一個節點。除了建立 node_8 之外，服務也已修改 node_1，使其 previous_sibling 內容指向新節點。

您可以指定母項及上一個同層級，以在對話中的他處建立節點：

{
  "dialog_node": "node_9",
  "parent": "node_2",
  "previous_sibling": "node_5"
}

您為 parent 和 previous_node 指定的值必須有效:

兩個值都必須參照現有節點。
指定的母項必須與上一個同層級的母項相同（如果上一個同層級沒有母項，則為 null）。
母項不能是 response_condition 或 event_handler 類型的節點。

產生的對話看起來像這樣：

除了建立 node_9 之外，服務也會自動更新 previous_siblingnode_6* 的 * 內容，讓它指向新的節點。

將節點移至不同的母項

使用具有下列主體的 POST /dialog_nodes/node_5 方法，將 node_5 移至不同的母項:

{
  "parent": "node_1"
}

指定的 parent 值必須有效：

它必須參照現有節點。
它不得參照已修改的節點 (節點不能是其自己的母項)。
它不得參照所修改節點的後代。
它不得參照 response_condition 或 event_handler 類型的節點。

這會導致如下的已變更結構：

這裡發生了幾件事:

將 node_5 移至其新的母項之後，node_7 會隨著它一起移動（因為 parentnode_7** 的 ** 值未變更）。在移動節點時，該節點仍然會保留其所有後代。
因為我們未指定 previous_siblingnode_5** 的 ** 值，所以它現在是 node_1 下的第一個同層級。
previous_siblingnode_4** 的 ** 內容已更新為 node_5。
node_9 的 previous_sibling 內容已更新為 null，因為它現在是 node_2 下的第一個同層級。

重新排序同層級

現在，使用具有下列主體的 POST /dialog_nodes/node_5 方法，將 node_5 設為第二個同層級，而非第一個同層級:

{
  "previous_sibling": "node_4"
}

在修改 previous_sibling 時，新值必須有效：

它必須參照現有節點
它不能參照已修改的節點 (節點不能是它自己的同層級)
它必須參照相同母項的子項（所有同層級都必須具有相同的母項）

結構變更如下：

Node_7 會與其母項一起保留。此外，會修改 node_4，使其 previous_sibling 為 null，因為它現在是第一個同層級。

刪除節點

使用 DELETE /dialog_nodes/node_1 方法來刪除 node_1。

結果為:

Node_1、node_4、node_5 及 node_7 已全部刪除。在刪除節點時，也會刪除該節點的所有後代。因此，如果您刪除根節點，則會刪除對話樹狀結構的整個分支。對已刪除節點的任何其他參照（例如 next_step 參照）都會變更為 null。

此外，node_2 會更新為指向 node_8，以作為其新的上一個同層級。

重新命名節點

使用具有下列主體的 POST /dialog_nodes/node_2 方法，重新命名 node_2:

{
  "dialog_node": "node_X"
}

對話的結構未變更，但已修改多個節點以反映變更的名稱:

parentnode_9** 及 node_6 的 ** 內容
previous_siblingnode_3** 的 ** 內容

對已刪除節點的任何其他參照（例如 next_step 參照）也會變更。