API-Anfrage

Fragt während des Anrufs eine Drittsoftware über ihre Web-Schnittstelle ab, legt die Antwort in Variablen ab, und nimmt den Ausgang Fehler, sobald es zu lange dauert oder fehlschlägt.

Kurzübersicht

Der im Fenster angezeigte Hilfetext lautet: „Fragt eine HTTP-API ab und extrahiert JSON-Werte in Variablen. Schlägt die API fehl oder überschreitet sie den Timeout, wird der Ausgang ‚Fehler' genommen. Verwenden Sie {{variable}} in der URL, den Kopfzeilen und dem Body."

So funktioniert es

Was eine API ist

Eine API ist die Serviceschnittstelle einer Software: eine Web-Adresse, die ein anderes Programm abfragt, und die nicht mit einer zu lesenden Seite antwortet, sondern mit strukturierten Daten. Die meisten antworten in JSON, einem Format, das Informationen nach Namen ordnet, wie ein Formular: {"kunde": {"name": "Müller", "status": "premium"}}.

Das Modul sendet die Anfrage, liest die Antwort und extrahiert, was Sie interessiert.

Die Variablen in der Anfrage

Die URL, die Kopfzeilen und der Body akzeptieren {{variablen}}, die unmittelbar vor dem Versand ersetzt werden. So fragt man den Dienst zum laufenden Anrufer ab: https://api.beispiel.com/kunde/{{caller}}.

Die Extraktion

Die Antwort ist selten im Ganzen zu verwenden. Die untere Tabelle verknüpft einen JSON-Pfad mit einem Variablen-Namen. Der Pfad liest sich von außen nach innen, die Ebenen durch Punkte getrennt: kunde.name sucht name innerhalb von kunde. Eine Liste wird über ihren Rang durchlaufen, beginnend bei null: 0.name bezeichnet den Namen des ersten Elements.

Ein leer gelassener Pfad liefert die gesamte Antwort: das braucht man, wenn der Dienst direkt eine Zahl oder ein Wort ohne umgebende Struktur antwortet.

Ein Pfad, der zu nichts führt, ergibt eine leere Variable, ohne Fehler. Der Ausgang OK wird trotzdem genommen, da der Dienst tatsächlich geantwortet hat.

Wann der Ausgang Fehler genommen wird

• die URL ist leer;
• der Dienst antwortet nicht innerhalb der Frist;
• er antwortet mit einem Fehlercode, das heißt jedem Code außerhalb der Erfolgsfamilie;
• die Sicherung ist ausgelöst.

Die Sicherung

Ein ausgefallener Dienst darf nicht alle Ihre Anrufe verlangsamen. Nach 5 aufeinanderfolgenden Fehlschlägen an demselben Server ruft das Modul ihn 30 Sekunden lang nicht mehr auf: der Ausgang Fehler wird sofort genommen, ohne die Frist abzuwarten und ohne die Anfrage überhaupt zu senden. Ein erster Erfolg setzt den Zähler auf null zurück.

Das ist eine Schutzmaßnahme, und sie erklärt eine verwirrende Beobachtung: während dieser dreißig Sekunden geht der Anruf im Handumdrehen mit Fehler zurück, obwohl der Dienst vielleicht bereits wiederhergestellt ist.

Was einzugeben ist

Die Schaltfläche Extraktion hinzufügen erstellt eine Zeile, Löschen entfernt ihre eigene, Speichern schließt das Fenster.

Schritt für Schritt

1. Holen Sie sich von Ihrem Anbieter die abzufragende Adresse, die Art der Authentifizierung und ein Beispiel für die Antwort. Ohne Antwortbeispiel können Sie die Extraktionspfade nicht schreiben.
2. Setzen Sie das Modul API-Anfrage und verbinden Sie den vorherigen Knoten mit seinem Eingang.
3. Öffnen Sie es, wählen Sie die Methode und stellen Sie den Timeout so kurz wie möglich ein, wie Ihr Dienst es unterstützt.
4. Geben Sie die URL ein, indem Sie die Variablen aus dem Panel Verfügbare Variablen einfügen.
5. Füllen Sie die Kopfzeilen aus, eine pro Zeile, im Allgemeinen die vom Anbieter gelieferte Authentifizierungszeile.
6. Geben Sie für ein POST oder ein PUT den Body ein.
7. Klicken Sie auf Extraktion hinzufügen und verknüpfen Sie einen JSON-Pfad mit einem Variablen-Namen, so oft wie Werte abzurufen sind.
8. Klicken Sie auf Speichern, verbinden Sie dann OK mit dem normalen Verlauf und Fehler mit einem Rückfall, der den Anruf ohne die Daten behandelt.
9. Setzen Sie nach dem Ausgang OK ein Modul Debugging mit den extrahierten Variablen als Nachricht, um zu lesen, was tatsächlich empfangen wurde.
10. Klicken Sie auf Speichern, dann auf Änderungen übernehmen im oberen Banner.
11. Rufen Sie Ihre Nummer an, öffnen Sie dann das Debug-Protokoll des Plans und prüfen Sie die extrahierten Werte.

Wenn es nicht funktioniert

Alle Anrufe kommen als Fehler zurück, obwohl die URL in einem Browser funktioniert. Ein Browser sendet Ihre Sitzungs-Cookies, das Modul nicht. Prüfen Sie die Authentifizierungs-Kopfzeile. Prüfen Sie dann die URL nach dem Ersetzen der Variablen: ein falsch geschriebenes {{name}} wird zu Leere und erzeugt eine unvollständige Adresse. Schließlich zählt jede Antwort außerhalb der Erfolgsfamilie als Fehlschlag, einschließlich einer lesbaren Fehlerseite.

Der Ausgang Fehler wird sofort genommen, ohne dass der Dienst aufgerufen wird. Die Sicherung ist ausgelöst: fünf aufeinanderfolgende Fehlschläge an diesem Server haben sie für dreißig Sekunden umgeschaltet. Warten Sie eine halbe Minute, bevor Sie schließen, und rufen Sie erneut an.

Ich habe 10 Sekunden gewählt und der Anruf geht nach 8 weiter. Die Frist ist zur Laufzeit auf acht Sekunden begrenzt, unabhängig vom gewählten Wert. Das ist beabsichtigt: darüber hinaus hat der Anrufer bereits aufgelegt.

Die extrahierte Variable ist leer, obwohl die Antwort die Daten enthält. Der Pfad stimmt nicht. Die Ebenen werden durch Punkte getrennt, Listen werden ab null gezählt, und ein leerer Pfad liefert die gesamte Antwort. Extrahieren Sie zuerst die gesamte Antwort in eine Variable, lesen Sie sie im Debug-Protokoll, und schreiben Sie dann den genauen Pfad.

Der Anruf wird unterbrochen, wenn der Dienst nicht antwortet. Der Ausgang Fehler ist mit nichts verbunden. Verbinden Sie ihn, mindestens mit dem üblichen Empfang.