Dialog mithilfe der API ändern

Die REST-API unterstützt die programmgesteuerte Änderung Ihres Dialogs. Sie können die /dialog_nodes-API verwenden, um Dialogmodulknoten zu erstellen, zu löschen oder zu ändern.

Ein Dialog ist eine Baumstruktur miteinander verbundener Knoten, die bestimmten Regeln entsprechen muss, um gültig zu sein. Jede Änderung, die Sie an einem Dialogmodulknoten vornehmen, kann kaskadierende Auswirkungen auf andere Knoten oder auf die Struktur Ihres Dialogmoduls haben. Bevor Sie die /dialog_nodes-API verwenden, um Ihren Dialog zu ändern, stellen Sie sicher, dass Sie verstehen, wie sich Ihre Änderungen auf den Rest des Dialogs auswirken. Sie können eine Sicherungskopie des aktuellen Dialogs erstellen. Weitere Informationen finden Sie unter Daten sichern und wiederherstellen.

Ein gültiges Dialogmodul erfüllt immer die folgenden Kriterien:

  • Jeder Dialogmodulknoten besitzt eine eindeutige ID (Eigenschaft dialog_node).

  • Jeder untergeordnete Knoten kennt seinen übergeordneten Knoten (Eigenschaft parent). Ein übergeordneter Knoten kennt jedoch nicht seine untergeordneten Knoten.

  • Ein Knoten kennt, sofern vorhanden, seinen unmittelbar vorhergehenden gleichgeordneten Knoten (Eigenschaft previous_sibling). Alle gleichgeordneten Elemente, die das übergeordnete Element gemeinsam nutzen, bilden eine verknüpfte Liste, wobei jeder Knoten auf den vorherigen Knoten verweist.

  • Nur ein untergeordnetes Element eines übergeordneten Elements kann das erste gleichgeordnete Element sein (d. h., seine previous_sibling ist null).

  • Ein Knoten kann nicht auf einen vorherigen gleichgeordneten Knoten verweisen, der ein untergeordneter Knoten eines anderen übergeordneten Knotens ist.

  • Zwei Knoten können nicht auf denselben vorherigen gleichgeordneten Knoten verweisen.

  • Ein Knoten kann einen anderen Knoten angeben, der als Nächstes ausgeführt werden soll (Eigenschaft next_step ).

  • Ein Knoten kann nicht sein eigener übergeordneter oder gleichgeordneter Knoten sein.

  • Ein Knoten muss eine Typeigenschaft haben, die einen der folgenden Werte enthält. Wenn keine Typeigenschaft angegeben ist, wird der Typ standard verwendet.

    • event_handler: Ein Handler, der für einen Frameknoten oder einen einzelnen Slotknoten definiert ist.

    Mit dem Tool können Sie einen Handler für Frameknoten definieren, indem Sie auf den Link Handler verwalten für einen Knoten mit Slots klicken. (Die Benutzerschnittstelle des Tools macht den Ereignishandler der Slotebene nicht zugänglich, aber Sie können über die API einen Ereignishandler definieren.)

    • frame: Ein Knoten mit mindestens einem untergeordneten Knoten des Typs slot. Alle untergeordneten Slotknoten, die erforderlich sind, müssen gefüllt werden, bevor der Service den Frameknoten beenden kann.

    Der Frameknotentyp wird im Tool als Knoten mit Slots dargestellt. Der Knoten, der die Slots enthält, wird als Knoten des Typsframe dargestellt. Dies ist der übergeordnete Knoten für jeden Slot, der als ein untergeordneter Knoten des Typs slot dargestellt wird.

    • response_condition: Eine bedingte Antwort.

    Im Tool können Sie eine oder mehrere bedingte Antwort(en) zu einem Knoten hinzufügen. Jede bedingte Antwort, die Sie definieren, wird im zugrunde liegenden JSON-Code als einzelner Knoten des Typs 'Antwortbedingung' (type=response_condition) dargestellt.

    • slot: Ein untergeordneter Knoten eines Knotens mit dem Typ frame.

    Dieser Knotentyp wird im Tool als einer von mehreren Slots dargestellt, die einem einzelnen Knoten hinzugefügt werden. Dieser einzelne Knoten wird im JSON-Code als übergeordneter Knoten des Typs frame dargestellt.

    • standard: Ein typischer Dialogmodulknoten. Dies ist der Standardtyp.

  • Bei Knoten des Typs slot, die denselben übergeordneten Knoten haben, gibt die gleichgeordnete Reihenfolge (durch die Eigenschaft previous_sibling angegeben) die Reihenfolge wieder, in der die Slots verarbeitet werden.

  • Ein Knoten des Typs slot muss über einen übergeordneten Knoten des Typs frame verfügen.

  • Ein Knoten des Typs frame muss über mindestens einen untergeordneten Knoten des Typs slot verfügen.

  • Ein Knoten des Typs response_condition muss über einen übergeordneten Knoten des Typs standard oder frame verfügen.

  • Knoten des Typs response_condition und event_handler können keine untergeordneten Knoten besitzen.

  • Ein Knoten des Typs event_handler muss zusätzlich über eine Eigenschaft event_name verfügen, die einen der folgenden Werte enthält, um den Typ des Knotenereignisses anzugeben:

    • filled: Definiert die Vorgehensweise, wenn der Benutzer einen Wert angibt, der die Bedingung erfüllt, die im Feld Überprüfen auf eines Slots angegeben ist, und der Slot gefüllt ist. Ein Handler mit diesem Namen ist nur vorhanden, wenn für den Slot eine Bedingung für 'Gefunden' definiert ist.
    • focus: Definiert die Frage, die angezeigt werden soll, wenn der Benutzer aufgefordert wird, die für den Slot erforderlichen Informationen anzugeben. Ein Handler mit diesem Namen ist nur vorhanden, wenn der Slot erforderlich ist.
    • generic: Definiert eine zu überwachende Bedingung, die abweichende Fragen verarbeiten kann, die Benutzer beim Füllen eines Slots oder eines Knotens mit Slots möglicherweise stellen könnten.
    • input: Aktualisiert den Nachrichtenkontext und fügt eine Kontextvariable mit dem beim Benutzer abgefragten Wert ein, um den Slot zu füllen. Ein Handler mit diesem Namen muss für jeden Slot im Frameknoten vorhanden sein.
    • nomatch: Definiert die nächsten Schritte, wenn die Benutzerantwort für die Abfrage des Slots keinen gültigen Wert enthält. Ein Handler mit diesem Namen ist nur vorhanden, wenn für den Slot eine Bedingung für 'Nicht gefunden' definiert ist.

    Das folgende Diagramm zeigt, wo Sie in der Benutzerschnittstelle des Tools den Code definieren, der für jedes benannte Ereignis ausgelöst wird.

    Position der Benutzerschnittstelle, an der der Code, der von benannten Ereignishandlern ausgelöst wird, erstellt wird
    Ereignishandler

  • Ein Knoten des Typs event_handler mit dem Ereignisnamen generic kann ein übergeordnetes Element des Typs slot oder frame aufweisen.

  • Ein Knoten des Typs event_handler mit dem Ereignisnamen focus, input, filled oder nomatch muss ein übergeordnetes Element des Typs slot aufweisen.

  • Wenn mehrere Ereignishandler mit demselben Ereignisnamen demselben übergeordneten Knoten zugeordnet sind, entspricht die Reihenfolge der gleichgeordneten Elemente der Reihenfolge, in der die Ereignishandler ausgeführt werden.

  • Bei Knoten des Typs event_handler, die demselben übergeordneten Knoten mit Slots zugeordnet sind, bleibt die Ausführungsreihenfolge gleich (unabhängig von der Platzierung der Knotendefinitionen). Die Ereignisse werden in der Reihenfolge der Ereignisnamen ausgelöst.

    1. focus
    2. input
    3. filled
    4. generic*
    5. nomatch

    *Wenn ein event_handler mit dem Ereignisnamen generic für diesen Slot oder für den übergeordneten Frame definiert ist, wird er zwischen dem gefüllten Knoten und dem Knoten 'nomatch event_handler' ausgeführt.

Die folgenden Beispiele zeigen, wie verschiedene Änderungen in der Folge zu nachgelagerten Änderungen führen können.

Knoten erstellen

Als Beispiel wird die folgende Baumstruktur eines einfachen Dialogmoduls zugrunde gelegt:

Beispieldialog
Beispieldialog

Ein neuer Knoten kann durch Absetzen einer Anforderung POST für '/dialog_nodes' mit dem folgenden Hauptteil erstellt werden:

{
  "dialog_node": "node_8"
}

Das Dialogmodul sieht danach wie folgt aus:

Beispieldialog 2
Beispieldialog 2

Da der Knoten node_8 ohne Angabe eines Wertes für parent oder previous_sibling erstellt wurde, ist er jetzt der erste Knoten im Dialogmodul. Neben der Erstellung von node_8 hat der Service auch node_1 so geändert, dass seine Eigenschaft previous_sibling auf den neuen Knoten verweist.

Durch die Angabe des übergeordneten und des vorherigen gleichgeordneten Knotens können Sie einen Knoten an einer beliebigen anderen Stelle im Dialogmodul erstellen:

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

Die Werte, die Sie für parent und previous_node angeben, müssen gültig sein:

  • Beide Werte müssen vorhandene Knoten referenzieren.
  • Der angegebene übergeordnete Knoten muss derselbe Knoten wie der übergeordnete Knoten des vorherigen gleichgeordneten Knoten sein (bzw. null, falls der vorherige gleichgeordnete Knoten keinen übergeordneten Knoten besitzt).
  • Das übergeordnete Element darf kein Knoten des Typs response_condition oder event_handler sein.

Anschließend sieht das Dialogmodul so aus:

Beispieldialog 3
Beispieldialog 3

Der Service hat nicht nur den Knoten node_9 erstellt, sondern auch die Eigenschaft previous_sibling des Knotens node_6 so aktualisiert, dass sie auf den neuen Knoten verweist.

Knoten zu einem anderen übergeordneten Knoten verschieben

Verschieben Sie node_5 mit der POST-Methode /dialog_nodes/node_5 mit dem folgenden Hauptteil in ein anderes übergeordnetes Element:

{
  "parent": "node_1"
}

Der angegebene Wert für parent muss gültig sein:

  • Er muss einen vorhandenen Knoten referenzieren.
  • Sie darf nicht auf den geänderten Knoten verweisen (ein Knoten darf nicht sein eigenes übergeordnetes Element sein).
  • Sie darf nicht auf ein untergeordnetes Element des geänderten Knotens verweisen.
  • Er darf keinen Knoten des Typs response_condition oder event_handler referenzieren.

Dies hat die folgende geänderte Struktur zum Ergebnis:

Beispieldialog 4
Beispieldialog 4

Hier sind mehrere Dinge passiert:

  • Als der Knoten node_5 zu seinem neuen übergeordneten Knoten verschoben wurde, wurde gleichzeitig auch der Knoten node_7 verschoben (weil sich der Wert der Eigenschaft parent des Knotens node_7 nicht geändert hat). Wenn Sie einen Knoten verschieben, bleiben alle untergeordneten Elemente dieses Knotens ihm weiterhin zugeordnet.
  • Da für die Eigenschaft previous_sibling des Knotens node_5 kein Wert angegeben wurde, ist dieser Knoten jetzt der erste gleichgeordnete Knoten unter dem Knoten node_1.
  • Die Eigenschaft previous_sibling des Knotens node_4 wurde mit dem Wert node_5 aktualisiert.
  • Die Eigenschaft previous_sibling von node_9 wurde auf null aktualisiert, da sie jetzt das erste gleichgeordnete Element unter node_2 ist.

Reihenfolge von gleichgeordneten Knoten ändern

Legen Sie jetzt node_5 als zweites gleichgeordnetes Element anstelle des ersten fest, indem Sie die Methode POST /dialog_nodes/node_5 mit dem folgenden Hauptteil verwenden:

{
  "previous_sibling": "node_4"
}

Wenn Sie die Eigenschaft previous_sibling ändern, muss der neue Wert gültig sein:

  • Er muss einen vorhandenen Knoten referenzieren.
  • Sie darf nicht auf den geänderten Knoten verweisen (ein Knoten darf nicht sein eigenes gleichgeordnetes Element sein).
  • Er muss ein übergeordnetes Element desselben übergeordneten Knotens referenzieren (alle gleichgeordneten Elemente müssen dasselbe übergeordnete Element besitzen).

Die Struktur ändert sich folgendermaßen:

Beispieldialog 5
Beispieldialog 5

Node_7 bleibt bei seinem übergeordneten Element. Außerdem wird node_4 so geändert, dass previous_sibling auf null gesetzt ist, da es nun das erste gleichgeordnete Element ist.

Knoten löschen

Löschen Sie node_1 mit der Methode DELETE /dialog_nodes/node_1.

Das Ergebnis lautet:

Beispieldialog 6
Beispieldialog 6

Node_1, node_4, node_5 und node_7 wurden gelöscht. Wenn Sie einen Knoten löschen, werden auch alle ihm untergeordneten Knoten gelöscht. Wenn Sie also einen Stammknoten löschen, löschen Sie eine gesamte Verzweigung der Baumstruktur des Dialogmoduls. Alle anderen Referenzen auf den gelöschten Knoten (z. B. Referenzen in next_step) werden in null geändert.

Darüber hinaus wurde durch diese Aktion der Knoten node_2 aktualisiert und verweist nun auf den Knoten node_8 als seinen neuen vorherigen gleichgeordneten Knoten.

Knoten umbenennen

Benennen Sie node_2 mit der Methode POST /dialog_nodes/node_2 mit dem folgenden Hauptteil um:

{
  "dialog_node": "node_X"
}

Beispieldialog 7
Beispieldialog 7

Die Struktur des Dialogmoduls wurde nicht geändert, aber mehrere Knoten wurden geändert, um den geänderten Namen widerzuspiegeln:

  • Die Eigenschaften parent der Knoten node_9 und node_6 wurden geändert.
  • Die Eigenschaft previous_sibling des Knotens node_3 wurde geändert.

Alle anderen Referenzen auf den gelöschten Knoten (z. B. Referenzen in next_step) wurden ebenfalls geändert.