Beschreiben eines Azure Logic Apps-Workflows mithilfe der Workflowdefinitionssprache

  • 12 Minuten

Die Struktur und der Workflow eines Azure Logic Apps-Workflows wird mithilfe eines JSON-Dokuments definiert. Dieses Dokument enthält eine JSON-Beschreibung der Elemente, aus denen der Logik-App-Workflow besteht, und das Schema der Definitionssprache für Workflows validiert es. Am einfachsten lässt sich das Schema erklären, indem Sie einen bestehenden Workflow untersuchen, der mit dem Workflow-Designer im Azure-Portal erstellt wurde, und dann die JSON-Beschreibung der Logik-App ansehen.

In dem Beispielszenario möchten Sie Ihren Berater*innen gängige Arbeitsabläufe bereitstellen, die sie an die spezifischen Bedürfnisse der Universitäten, mit denen sie arbeiten, anpassen können. Es soll so einfach wie möglich sein, jeden Workflow anzupassen und bereitzustellen, weshalb Sie sich dafür entscheiden, sich den Code für den Workflow anzusehen, d. h. den JSON-Code für die Workflowdefinition.

Workflow-Designer

Mit dem Workflow-Designer können Sie den Workflow für einen Logik-App-Workflow grafisch erstellen und debuggen. Er ermöglicht Entwickler*innen außerdem einen Blick unter die Haube eines Workflows, damit sie ermitteln können, wie er implementiert wurde. Die folgende Abbildung zeigt ein Beispiel für einen einfachen Workflow, der durch Senden einer HTTP GET-Anforderung an eine angegebene URL ausgelöst wird. Das Ergebnis wird in einer HTTP-Antwort zurückgegeben. In diesem Beispiel wird die einfache Nachricht Hello Logic Apps Template! vom Workflow zurückgesendet.

Übersicht über den Workflow-Designer

Sehen wir uns nun die Definitionssprache für Workflows an, die von der JSON-Vorlage verwendet wird.

Codeansicht

Im Codeansichtsfenster wird das JSON-Dokument gezeigt, das den Workflow beschreibt. Der JSON-Code der Beispiel-App sieht folgendermaßen aus:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Response": {
                "inputs": {
                    "body": "Hello Azure Logic Apps Template!",
                    "statusCode": 200
                },
                "kind": "Http",
                "runAfter": {},
                "type": "Response"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "manual": {
                "inputs": {
                    "method": "GET",
                    "schema": {}
                },
                "kind": "Http",
                "type": "Request"
            }
        }
    }
}

Beachten Sie die Abschnitte im Bereich definition, die sich auf die im Designer gezeigten Aktionen und Trigger beziehen. Sie können den JSON-Code in diesem Dokument bearbeiten, um alle erforderlichen Änderungen an der Funktionalität des Logik-App-Workflows vorzunehmen. Sie können auch weitere Aktionen hinzufügen und festlegen, wie die Logik im Workflow von einer Aktion zur nächsten verläuft.

Abschnitt „triggers“

Der Abschnitt triggers enthält die Beschreibung des Typs des Triggers und wie dieser aufgerufen wird. In diesem Beispiel wird ein einfacher HTTP-Trigger verwendet, der als Reaktion auf eine HTTP GET-Anforderung ausgeführt wird.

"triggers": {
    "manual": {
        "inputs": {
            "method": "GET",
            "schema": {}
        },
        "kind": "Http",
        "type": "Request"
    }
}

Ein Trigger muss die folgenden Elemente enthalten:

  • Ein eindeutiger Name innerhalb des Workflows. Im vorherigen Beispiel ist der Standardname des Triggers manual, Sie können jedoch den Standardnamen durch einen aussagekräftigeren Bezeichner ersetzen.

  • Den Triggertyp: Der Typ gibt das Ereignis an, das die Ausführung des Triggers auslöst. Ein Request-Trigger wird als Reaktion auf eine HTTP-Anforderung ausgeführt. Weitere verfügbare Triggertypen:

    • Recurrence zum Erstellen eines Triggers, der nach einem sich wiederholenden Zeitplan ausgeführt wird

    • HttpWebhook zum Lauschen auf Ereignisse an einem Endpunkt

    • ApiConnection für die Reaktion auf Ereignisse, die von anderen Azure-Diensten ausgelöst werden (z. B. wenn eine Nachricht in eine Nachrichtenwarteschlange eingeht, wenn eine E-Mail eingeht usw.). Der Triggertyp ApiConnection ist generalisiert, und Sie legen weitere Details fest, die den Typ des Diensts und weitere erforderliche Verbindungsinformationen angeben.

  • Den Abschnitt inputs In diesem Abschnitt werden die Daten angegeben, die das Verhalten des Triggers definieren. Bei Anforderungstriggern gibt method den Typ der HTTP-Anforderung an, die die Ausführung des Triggers auslöst. Bei ApiConnection-Triggern enthält der Abschnitt inputs Informationen zum Herstellen einer Verbindung mit der Ressource, die das Ereignis auslöst (z. B. eine Verbindungszeichenfolge für die Nachrichtenwarteschlange). Wenn es sich um einen Request-Trigger handelt, legt der Abschnitt schema der Eingabedefinition das Schema fest, dem der Inhalt des Anforderungstexts entsprechen soll. HTTP GET-Anforderungen enthalten keinen Anforderungstext, weshalb der Abschnitt schema wie im obigen Beispiel leer ist.

Im folgenden Beispiel wird die Definition eines anderen Request-Triggers veranschaulicht, der einen Workflow startet und die HTTP POST-Anforderungen empfängt. Eine POST-Anforderung enthält in der Regel einen Anforderungstext, der wiederum Daten enthält, die gepostet werden sollen. Der Anforderungstext in diesem Beispiel enthält einen Kundennamen und eine -adresse, bestehend aus der Straße und der Stadt.

"mypostrequest": {
   "type": "Request",
   "kind": "Http",
   "inputs": {
      "method": "POST",
      "schema": {
         "type": "object",
         "properties": {
            "customerName": {
               "type": "String"
            },
            "customerAddress": { 
               "type": "Object",
               "properties": {
                  "streetAddress": {
                     "type": "string"
                  },
                  "city": {
                     "type": "string"
                  }
               }
            }
         }
      }
   }
}

Ein Trigger kann auch Bedingungen festlegen. Der Trigger wird nur ausgelöst, wenn diese Bedingungen erfüllt werden. Die Bedingungen können Sie im optionalen Abschnitt conditions definieren. So können Sie beispielsweise den im obigen Beispiel gezeigten Trigger mypostrequest nur ausführen, wenn der Anforderungstext die Stadt New York angibt:

"mypostrequest": {
   "type": "Request",
   "kind": "Http",
   "inputs": {
      ...
   }
   "conditions": [
      {
        "expression": "@equals(triggerOutputs()['body']['customerAddress']['city'], 'New York')"
      }
   ]
}

Abschnitt „actions“

Der Abschnitt actions einer Logik-App definiert die Logik und Struktur des Workflows. Der Abschnitt enthält eine Reihe von Aktionen. Eine Aktion ist ein einfacher Baustein für die Erstellung von Workflows. Aktionen nehmen Eingaben an und erzeugen Ausgaben, die an die nächste Aktion im Workflow übergeben werden. In der folgenden Tabelle sind verschiedene verfügbare Aktionstypen aufgeführt:

Aktion Beschreibung
ApiConnection Sendet eine HTTP-Anforderung an einen angegebenen Dienst. Mit diesem Aktionstyp können Sie einen Logik-App-Workflow mit Azure-Features wie Azure Service Bus, Azure Event Grid und anderen integrieren. Die Aktion erfordert Eingaben, die eine Verbindungszeichenfolge für den Zugriff auf den Dienst sowie jegliche weitere zum Aufrufen des Diensts erforderlichen Informationen und Parameter enthalten.
Compose Kombiniert mehrere Eingaben und Ausdrücke zu einer einzigen Ausgabe.
Function Ermöglicht das Aufrufen einer Azure-Funktion.
HTTP Sendet eine HTTP-Anforderung an einen HTTP-Endpunkt (nicht an einen Azure-Dienst).
Join Verwendet ein Array von Datenelementen als Eingabe und generiert eine Zeichenfolge, die diese Elemente getrennt durch ein angegebenes Trennzeichen enthält.
Parse Analysiert ein JSON-Dokument mithilfe eines festgelegten Schemas in eine Reihe von Token.
Query Filtert die Elemente mithilfe einer festgelegten Bedingung in ein Eingabearray.
Response Erstellt eine Antwort auf eine HTTP-Anforderung.
Table Generiert eine HTML-Tabelle aus einem Array von JSON-Objekten.
Terminate Bricht einen Workflow sofort ab.
Wait Hält den Workflow für einen festgelegten Zeitraum oder bis zum Eintritt eines Timeouts an.
Workflow Führt einen weiteren Logik-App-Workflow aus.
Condition Eine Reihe von Aktionstypen (Foreach, If, Switch und Until), mit denen Sie programmgesteuerte Steuerungsabläufe in einem Workflow implementieren können. Sie können die Elemente in einer Sammlung durchlaufen, Entscheidungen basierend auf den Werten von Eingabeparametern treffen und den Vorgang wiederholen, bis eine Bedingung erfüllt ist.
InitializeVariable,
IncrementVariable,
DecrementVariable,
und SetVariable		 Mit diesen Aktionen können Sie Variablen definieren, initialisieren, zuweisen und ändern, die Sie zwischen Aktionselementen in einem Workflow übergeben können.

Jede Aktion muss so wie jeder Trigger über einen eindeutigen Namen im Workflow verfügen. Im folgenden Beispiel lautet der Standardaktionsname Response, Sie können jedoch einen gültigen aussagekräftigeren Bezeichner verwenden. Eine Aktion muss einen inputs-Abschnitt aufweisen, der die Daten festlegt, die die Aktion bearbeitet. Sie können in der Response-Aktion Daten für einen Ausdruck, der in der Antwortnachricht zurückgegeben werden soll, und einen HTTP-Statuscode angeben.

In dieser einfachen Workflowdefinition generiert die Aktion eine HTTP-Antwort, deren Text aus einer einfachen Nachricht besteht.

"actions": {
    "Response": {
        "inputs": {
            "body": "Hello Azure Logic Apps Template!",
            "statusCode": 200
        },
        "kind": "Http",
        "runAfter": {},
        "type": "Response"
    }
}

Der Abschnitt runAfter gibt an, an welcher Stelle die Aktion in der Workflowsequenz ausgeführt wird. Das vorherige Beispiel enthält nur eine Aktion, weshalb diese immer ausgeführt wird, wenn der Trigger ausgelöst wird. Wenn der Workflow mehrere Aktionen umfassen würde, könnten Sie in diesem Abschnitt den Namen einer Aktion und einen Status für diese Aktion festlegen. Die Aktion wird ausgeführt, wenn die Aktion runAfter mit dem angegebenen Status abgeschlossen wird. Der folgende Code enthält hierzu ein Beispiel. Die Aktion mySecondAction wird nach myFirstAction ausgeführt, aber nur dann, wenn myFirstAction sie mit einem Status von Succeeded abschließt.

"actions": {
    "mySecondAction": {
        "inputs": {
            ...
        },
        "runAfter": {
            "myFirstAction": [
                "Succeeded"
            ]
        },
        "type": ...
    },
    "myFirstAction": {
        "inputs": {
            ...
        },
        "runAfter": {},
        "type": ...
    }
}

Abschnitt „outputs“

Den Abschnitt outputs verwenden Sie zum Definieren der Daten, die Ihr Workflow zurückgeben kann, wenn die Ausführung abgeschlossen ist. Sie könnten für jede Ausführung des Workflows einen spezifischen Status und spezifische Daten nachverfolgen. Sie können die Ausgabe aller Ausführungen eines Workflows mithilfe des Ausführungsverlaufs in Azure Logic Apps überprüfen, den Sie über das Azure-Portal oder die Workflow-REST-API finden.

Das Format des Abschnitts outputs sieht wie folgt aus:

"outputs": {
  "<key-name>": {
    "type": "<key-type>",
    "value": "<key-value>"
  }
}

Workflowausdrücke

Sie können einen Workflowausdruck anstelle beliebiger fester Werte, Variablen oder Konstanten verwenden. Außerdem können Sie einen Ausdruck an einer beliebigen Stelle in einem JSON-Zeichenfolgenwert platzieren, indem Sie dem Ausdruck ein @-Zeichen voranstellen. Sie können beispielsweise die @parameters-Funktion in einem Ausdruck verwenden, um den Wert eines benannten Parameters abzurufen (Parameter werden im nächsten Abschnitt behandelt).

"customerFullName": "Bill Frost",
"accountName": "@parameters('customerName')"

Azure Logic Apps stellt eine Reihe integrierter Funktionen bereit, die Sie zum Erstellen komplexer Ausdrücke verwenden können:

  • Zeichenfolgenfunktionen: Für die Verkettung oder Aufteilung von Zeichenketten, die Konvertierung von Zeichen zwischen Groß- und Kleinschreibung und die Suche nach Teilzeichenfolgen.
  • Sammlungsfunktionen: Zum Erkennen, ob eine Sammlung Elemente enthält, die einem bestimmten Muster entsprechen, zum Abrufen von Elementen aus einer Sammlung und zum Kombinieren von Sammlungen.
  • Logische Vergleichsfunktionen: Zur Erkennung, ob Operanden gleich, verschieden, numerisch größer oder numerisch kleiner sind als andere.
  • Konvertierungsfunktionen: Zum Ändern des Typs oder Formats von Daten.
  • Mathematische Funktionen: Wie z. B. add, sub, div und mul, und mehrere weitere.
  • Datums- und Uhrzeitfunktionen: Zum Analysieren und Verarbeiten von Datum und Uhrzeit.
  • Workflowfunktionen: Zum Abrufen von Informationen über die an eine Workflow-Aktion übergebenen Daten. Die (zuvor gezeigte) parameter-Funktion ruft beispielsweise den Wert eines benannten Parameters ab, und die (zuvor gezeigte) body-Funktion gibt Daten zurück, die von einer Aktion generiert werden.
  • JSON- und XML-Manipulationsfunktionen: Zum Parsen und Verarbeiten von JSON- und XML-Dokumenten.

Sie können Variablen im Abschnitt inputs einer InitializeVariable-Aktion definieren und diese Variablen mithilfe von Ausdrücken bearbeiten. Lesen Sie den Wert einer Variablen mit der Funktion variables. Im folgenden Beispiel wird eine InitializeVariable-Aktion zum Erstellen einer ganzzahligen Variable namens myIntegerVariable verwendet, die mit 99 99 initialisiert wird. Dieses Beispiel enthält außerdem eine Condition-Aktion des Typs If. Die Bedingung verwendet einen Ausdruck, um den Wert der Variablen myIntegerVariable zu testen, und wenn dieser mit dem Wert 100 übereinstimmt, verwendet die Bedingung eine HTTP-Aktion, um eine GET-Anforderung durchzuführen.

"actions": {
    "Condition": {
        "actions": {
            "HTTP": {
                "inputs": {
                    "method": "GET",
                    "uri": "http://dummyurl.com"
                },
                "runAfter": {},
                "type": "Http"
            }
        },
        "expression": {
            "equals": [
                "@variables('myIntegerVariable')",
                100
            ]
        }        ,
        "runAfter": {
            "Initialize": [
                "Succeeded"
            ]
        },
        "type": "If"
    },
    "Initialize": {
        "inputs": {
            "variables": [
                {
                    "name": "myIntegerVariable",
                    "type": "Integer",
                    "value": 99
                }
            ]
        },
        "runAfter": {},
        "type": "InitializeVariable"
    }
}

Abschnitt "parameters"

Im Abschnitt parameters können Sie einen Workflow parametrisieren. Zur Laufzeit können Sie Werte für all diese Parameter angeben. Sie können die Parameter überall im Workflow referenzieren, wo Sie eine Konstante oder einen Ausdruck verwenden könnten.

Sie können eine Parameterdefinition mit einem Standardwert hinzufügen. Wenn Sie zur Laufzeit keinen Wert für den Parameter angeben, wird der Standardwert verwendet. Im folgenden Beispiel wird veranschaulicht, wie ein Parameter namens cityParam definiert wird. Der Parameter wird innerhalb der Bedingung für die Aktion mypostrequest verwendet. Er führt die Aktion nur aus, wenn das Anforderungsdokument einen Ort enthält, der dem Parameterwert entspricht. Der Standardparameterwert lautet New York:


    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            ...
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {
            "cityParam": {
                "defaultValue": "New York",
                "type": "String"
            }
        },
        "triggers": {
            "mypostrequest": {
                "conditions": [
                    {
                        "expression": "@equals(triggerOutputs()['body']['customerAddress']['city'], parameters('cityParam'))"
                    }
                ],
                "inputs": {
                    ...
                },
                "kind": "Http",
                "type": "Request"
            }
        }
    }
}