Module

Was sind Module?

Module können Aktionen bzw. Anfragen im Flow ausführen. Diese Module sind als Schritte im Bot Builder vorhanden und können dort verwendet werden.

Übersicht der App-Module

HTTP-Abfrage erstellen und Verbindung auswählen

Diese Abfrage wird beim Ausführen des Moduls/der Funktion an den gewünschten Endpunkt geschickt. Zusätzlich muss wie bereits in Verbindungenerwähnt wurde eine Verbindung für diese App-Modul ausgewählt werden.

HTTP-Abfrage und Auswahl der entsprechenden Verbindung

Erklärung Bestandteile HTTP-Abfrage

• url: Erweiterung der Basis-URL um den gewünschten Endpunkt
• headers:

  • Content-Type: Festlegung auf JSON-Format des Anforderungs-Headers und der Antwort

  • meist wird hier noch für die Autorisierung "authorization" ein Token oder API-Key mit dem Platzhalter {{parameters.apiKey}}

• method: Methode des Aufrufes (GET)

• qs: Sammlung von Parametern in Form eines Query-Strings (qs)

Vollständige URL der HTTP-Abfrage

Die zusammengesetzte vollständige URL diese HTTP-Aufrufes würde wie folgt lauten:

https://api.chucknorris.io/jokes/random?category={category}

Beispiel - HTTP-Abfrage mit Querystrings

In der HTTP-Abfrage wird zusätzlich eine Kategorie als Query-String übergeben.

{
  "url": "{{baseUrl}}/random",
  "method": "GET",
  "headers": {
    "Content-Type": "application/json"
  },
  "qs": {
    "category": "{{parameters.category}}"
  }
}

Dummy - POST-HTTP-Abfrage

Hierbei handelt es sich um ein Dummy POST-HTTP-Abfrage, die nicht in der "Chuck Norrs Jokes Api" erreichbar ist und nur für Veranschaulichungszwecke verwendet wird

{
  "url": "{{baseUrl}}/random/createJoke",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "category": "{{parameters.category}}",
    "value": "{{parameters.value}}"
  }
}

Es wird ein Witz mit der Kategorie ("category") und dem Witzetext ("value") aus dem Body erstellt. Es müssen dementsprechend im Teil Festlegen der Parameter diese Parameter angelegt werden.

Festlegen der Parameter

Die Parameter stellen notwendigen Informationen für die HTTP-Abfrage des Moduls dar. Diese Parameter müssen im Bot Builder beim Ausführen eines Moduls mitgeben werden.

Festlegen der Parameter

Erklärung Bestandteile Parameter

• name: Eindeutiger Namen des Parameters

• type: Datentyp (text, number oder boolean)

• label: Label, das im Bot Builder im entsprechenden App-Modul aufgeführt ist

  • das Feld im App-Modul für die Eingabe der Daten trägt diesen Namen

• required: Gibt an, ob der Parameter erforderlich ist (true oder false)

Beispiel - Parameter

[
  {
    "name": "category",
    "type": "text",
    "label": "Kategorie",
    "required": true
  }
]

Definition des Outputs

Hier werden Informationen zum Aufbau der erwarten Antwort des Endpunktes festgelegt. Der Aufbau der Antwort muss exakt definiert werden, da sonst Werte nicht weiter verarbeitet werden können. Die aufgelisteten Objekte sind Variablen der Konversation, die nach erfolgreichem Ausführen des App-Moduls entsprechend gesetzt werden. Mit diesen Variablen kann nun im Flow weitergearbeitet werden.

Definition des Outputs

Erklärung Bestandteile Output

• name: Eindeutiger Name des Ouput-Wertes

  • diese Name muss exakt dem Namen in der HTTP-Antwort entsprechen

• type: Datentyp (text, number oder boolean)

• label: Name der Variablen

  • unter diesem Namen ist die Variablen nach ausführen des App-Moduls verfügbar

  • Es besteht auch die Möglichkeit verschachtele JSON-Datenstrukturen bzw. Objekte mit dem obigen Aufbau darzustellen. Siehe Dummy - Beispiel Output-Definition (verschachtelte JSON-Datenstruktur)

Beispiel - Output-Definition (flache JSON-Datenstruktur)

[
  {
    "name": "id",
    "type": "text",
    "label": "ID"
  },
  {
    "name": "value",
    "type": "text",
    "label": "Witz"
  }
]

Dummy - Beispiel Output-Definition (verschachtelte JSON-Datenstruktur)

Folgend wird ein Beispiel für die Output-Definition einer Schnittstelle in einem verschachtelter JSON-Datenstruktur dargestellt. Hierbei handelt es sich um eine Dummy Output-Definition, die nicht zu einem Endpunkt der "Chuck Norrs Jokes Api" gehört und nur für Veranschaulichungszwecke verwendet wird. Diese Output-Definition entspricht dem Beispiel - verschachtelte JSON-Datenstruktur

[
  {
    "name": "id",
    "type": "number",
    "label": "Id"
  },
  {
    "name": "email",
    "type": "text",
    "label": "E-Mail"
  },
  {
    "name": "username",
    "type": "text",
    "label": "Username"
  },
  {
    "name": "address",
    "type": "object",
    "label": "Adresse",
    "spec": [
      {
        "name": "city",
        "type": "text",
        "label": "City"
      },
      {
        "name": "street",
        "type": "number",
        "label": "Strasse"
      },
      {
        "name": "number",
        "type": "number",
        "label": "Number"
      },
      {
        "name": "zipcode",
        "type": "number",
        "label": "Postleitzahl"
      }
    ]
  }
]