HTTP-Aufgabe

Während der Ausführung Ihres Plans können Sie eine Aufgabe erstellen, um HTTP-Anfragen an einen Anwendungsendpunkt eines Drittanbieters zu senden. Beispiel: Wenn eine vorherige Aufgabe erfolgreich ausgeführt wird, können Sie eine HTTP-Nachricht mit Informationen aus dieser Aufgabe an einen angegebenen Endpunkt senden.

In der Planansicht können Sie HTTP-Aufgaben erstellen, um eine Anfrage an Endpunkte vor oder nach der Ausführung anderer Aufgaben zu senden. Außerdem können Sie die HTTP-Aufgabe verwenden, um ein Dataset mit Antworten auf API-Aufrufe zu generieren, das in einem Designer Cloud-Workflow verwendet werden kann. Diese Aufgaben werden im rechten Kontextfenster angegeben.

Eine HTTP-Aufgabe ist eine Anfrage zwischen Alteryx One Platform und einer anderen Anwendung. Diese Anfragen werden über HTTP zugestellt und können von der empfangenden Anwendung interpretiert werden, um Maßnahmen zu ergreifen.
Anmerkung
Die empfangende Anwendung erfordert möglicherweise, dass Sie den Host und die Portnummer oder die IP-Adresse der Plattform auf die Whitelist setzen. Weitere Informationen finden Sie in der Dokumentation Ihrer Anwendung.
Eine HTTP-Aufgabe ist einer der in einem Plan verfügbaren Aufgabentypen. Weitere Informationen finden Sie auf der Seite „Planansicht“.

Beschränkungen

Für das Eingabedataset (Konfiguration aus Dataset laden):
- Zeilen: 10.000.
- Dateigröße: 1 GB.
- Zeilengröße: 100 MB.
HTTP-basierte Anfragen haben ein Timeout-Limit von 30 Sekunden.
Benutzerdefinierte Sicherheitszertifikate können nicht verwendet werden.

Voraussetzungen

Voraussetzungen der empfangenden Anwendung

Um eine HTTP-Anfrage an eine Zielanwendung zu senden, muss die Anwendung so konfiguriert sein, dass sie die Anfrage empfängt:

Anfragen von außerhalb der Anwendungsdomain müssen aktiviert sein.
Anmerkung
Die empfangende Anwendung erfordert möglicherweise, dass Sie den Host und die Portnummer oder die IP-Adresse der Plattform auf die Whitelist setzen. Weitere Informationen finden Sie in der Dokumentation Ihrer Anwendung.
Sie müssen die URL des Endpunkts anfordern, an den die HTTP-Anfrage gesendet werden soll.
Sie müssen HTTP-Header anfordern, die bei jeder HTTP-Anfrage eingefügt werden müssen.
Wenn die Anfrage signiert werden muss, ist eine zusätzliche Konfiguration erforderlich. Details finden Sie unten.

Aufgabe erstellen

Ziehen Sie die HTTP-Aufgabe per Drag & Drop aus dem linken Bereich zum Plan-Canvas.
Wählen Sie im rechten Fensterbereich HTTP-Aufgabe aus. Das HTTP-Aufgabenfenster wird angezeigt.

Abbildung: HTTP-Aufgabe

Feld	Beschreibung
Methode	Wählen Sie die HTTP-Methode für die Zustellung der Nachricht aus. Die geeignete Methode hängt von der empfangenden Anwendung ab. Bei den meisten Anwendungsfällen ist die `POST`-Methode erforderlich.
URL	URL, unter der die HTTP-Anfrage von der anderen Anwendung empfangen wird.
Header	Fügen Sie HTTP-Content-Header als Schlüssel-Wert-Paare ein. Wenn der Text beispielsweise im JSON-Format vorliegt, sollten Sie den folgenden Header einfügen: key: Content-Type value: application/json Anmerkung Möglicherweise müssen Sie ein Autorisierungstoken als Wert für den `Autorisierungsschlüssel` übermitteln.
Text	(Nur `POST`-, `PUT`- oder `PATCH`-Methoden) Der Text der Anfrage, die an die empfangende Anwendung gesendet wurde. Der Anforderungstext ist wie folgt aufgebaut: {"text":"My text message to the receiving application."} Tipp Als Teil des Anforderungstexts oder der Header-Felder können Sie Metadatenreferenzen für die Plandefinition, die aktuelle Ausführung, bereits ausgeführte Aufgaben und Spaltendaten und Datenquellen einfügen. Weitere Informationen zu den verfügbaren Metadaten finden Sie unter Referenzen zu Planmetadaten.
Geheimschlüssel	(Optional) Die Anforderungsnutzlast kann mit einem Geheimschlüssel überprüft werden. Dieser geheime Wert muss an dieser Stelle eingefügt werden und muss als Teil des Codes enthalten sein, der verwendet wird, um die Anforderungen in der empfangenden Anwendung zu verarbeiten. Der geheime Wert sollte hier als Zeichenfolge ohne Anführungszeichen eingegeben werden.
SSL-Zertifikat validieren	Wenn diese Option auf `True` gesetzt ist, wird vor der Übertragung überprüft, ob für die HTTPS (SSL)-Kommunikation ein gültiges Zertifikat verwendet wird. Anmerkung Wenn Sie eine Anforderung an einen Endpunkt senden müssen, dessen Zertifikat abgelaufen/ungültig ist, müssen Sie die SSL-Überprüfung deaktivieren.
Wiederholen	Wenn der zurückgegebene Statuscode außerhalb des Bereichs 200–299 liegt, gilt die HTTP-Aufgabe als nicht erfolgreich. Wenn diese Option aktiviert ist, wird die Anforderung wiederholt. Wenn die Anforderung fehlschlägt, definiert dieser Wert, wie oft die Anforderung wiederholt werden soll. Wenn diese Anzahl von Wiederholungsversuchen ohne Erfolg erreicht wird, schlägt die Aufgabe fehl.
Dataset aus Antwort erstellen	Wenn diese Option auf `True gesetzt ist`, können Sie das Dataset verwenden, um einen Workflow zu erstellen.

Aufgabe konfigurieren

Legen Sie die benötigten Parameter fest. Weitere Informationen zu Parametern finden Sie unter Planansicht für HTTP-Aufgaben.
Sie können Informationen zu Planmetadaten in den Header-Werten und im Anfragetext angeben. Weitere Informationen finden Sie unter Referenzen zu Planmetadaten.
Um die Verbindung zu testen, klicken Sie auf Test. Eine Erfolgsmeldung wird angezeigt.
Tipp
Der Statuscode 200 gibt an, dass der Test erfolgreich war.
Tipp
Sie können die GET-Methode für Testzwecke verwenden. Eine GET-Anfrage ändert keine Daten auf der Zielplattform, kann jedoch zulassen, dass Sie Elemente im Anfragetext angeben.
Um die Aufgabe hinzuzufügen, klicken Sie auf Speichern.

Aufgabe umbenennen

Um die Aufgabe umzubenennen, klicken Sie im Menü auf Mehr > Bearbeiten im rechten Fensterbereich.

Tipp

Eine gute Benennung kann den Endpunkt und die Methode der Zielplattform sowie die Zwecke der Aufgabe in Ihrem Plan umfassen.

Aufgabe löschen

Um die Aufgabe zu löschen, klicken Sie im Menü auf Mehr > Löschen. Bestätigen Sie, dass Sie die Aufgabe löschen möchten.

Warnung

Dieser Schritt kann nicht rückgängig gemacht werden.

Referenzen zu Planmetadaten

In der Nachricht Ihrer anderen Aufgaben können Sie sich auf Metadaten zum Plan, zu seinen Aufgaben und seiner Ausführung beziehen. Weitere Informationen finden Sie unter Referenzen zu Planmetadaten.

Beispiele

Nachricht an Slack-Kanal

Tipp

Slack-Aufgaben sind jetzt eine unterstützte Produktfunktion.

Sie können eine HTTP-Aufgabe erstellen, um eine Textnachricht an einen Slack-Kanal Ihrer Wahl zu senden.

Voraussetzungen

Richten Sie Ihre Slack-Installation so ein, dass HTTP-Nachrichten empfangen werden:

Erstellen Sie bei Bedarf einen Slack-Kanal, um Ihre Nachrichten zu empfangen.
Erstellen Sie eine App.
Aktivieren Sie eingehende HTTP-Nachrichten für Ihre App.
Geben Sie den Kanal für den Empfang der eingehenden Nachrichten an.
Kopieren Sie die URL für die eingehende HTTP-Anfrage aus der cURL-Anweisung.

HTTP-Aufgabe definieren

Parameter	Beschreibung
Name	Dieser Name erscheint nur in Alteryx One.
Methode	Wählen Sie die `POST-`Methode aus.
URL	Fügen Sie die URL ein, die Sie aus Slack kopiert haben.
Header	Kopieren Sie die Inhalts-Header aus dem Slack-cURL-Befehl: key: Content-Type value: application/json
Text	{"text":"Your job has completed."}

Konto

Klicken Sie auf Test, um zu überprüfen, dass diese Aufgabe funktioniert.
Führen Sie einen Auftrag aus und prüfen Sie den Slack-Kanal auf eine Nachricht.

Beispiele für Planmetadaten

Sie können auf Metadaten-Informationen aus der Plandefinition und der aktuellen Planausführung als Teil der Anfrage der HTTP-Aufgabe Bezug nehmen.

Anmerkungen:

Sie können nur Metadatenreferenzen für Aufgaben einfügen, die bereits in der Planausführung vor Beginn der HTTP-Aufgabe aufgetreten sind.
Jede Aufgabe in der aktuellen Ausführung wird mit einem zweistelligen Code referenziert. Beispiel:
```
{{$http_xx.name}}
```

Syntax

Eine Referenz zu Planmetadaten wird mit der folgenden Syntax erstellt. Geben Sie in das entsprechende Textfeld einen der folgenden Werte ein:

Tipp

Geben Sie zunächst $ ein, um Zugriff auf eine Menüstruktur mit Metadatenreferenzen für jeden Metadatenreferenztyp zu erhalten. Die endgültige Syntax ist oben notiert.

Pläne:

Metadateninformationen aus der Plandefinition oder der aktuellen Planausführung:

{{$plan

Planinformationen

Der folgende Anfragetext enthält Verweise auf den Plannamen, die Planausführungskennung und den soeben ausgeführten Flow:

{"text":"Plan: {{$plan.name}} 
RunId: {{$plan.runId}}
Flow: {{$flow_7p.name}}
Success."}

Informationen zur Planausführung

Der folgende Anfragetext enthält Informationen zur Planausführung mit Zeitstempeln:

{"text":"Plan: {{$plan.name}} 
RunId: {{$plan.runId}}
- plan start: {{$plan.startTime}}
Running time: {{$plan.duration}}

Times:
- last task start: {{$flow_7p.startTime}}
- last task end: {{$flow_7p.endTime}}
"}

HTTP-Aufgabeninformationen

Sie können auf Informationen aus einer HTTP-Aufgabe Bezug nehmen, die bereits ausgeführt wurde:

{"text":"{{$http_qg.name}} returned {{$http_qg.statusCode}}."}

Weitere Informationen finden Sie unter Referenzen zu Planmetadaten.

Metadateneingaben in Cloud-Funktion einspeisen

Dieses Beispiel zeigt, wie Sie eine HTTP-Aufgabe verwenden können, um Planmetadaten an AWS-Lambda-Funktionen zu übermitteln. Ein ähnlicher Ansatz könnte für Google Cloud-Funktionen verwendet werden.

In diesem Fall wird der rowCount-Wert aus der Ausführung der Flow-Aufgabe über eine HTTP-Aufgabe an eine AWS-Lambda-Funktion übermittelt.

Allgemeine Schritte:

Definieren Sie Ihren Plan.
Flow-Aufgabe: Führen Sie den Flow aus, um die für die Lambda-Funktion benötigten Ausgaben zu generieren.
HTTP-Aufgabe: Generiert eine HTTP-Anfrage, deren Text eine Referenz auf die rowCount -Metadatenvariable enthält. Anfragetext:
```
{
 "rowCount": "{{$flow_7p['My Flow Name'].output['My output name'].rowCount}}"
}
```

AWS-Lambda-Funktionen: Im Folgenden wird ein Pseudo-Code für Lambda angezeigt:

import json
def lambda_handler(event, context):
  httpTaskBody = json.loads(event["body"])
  rowCount = httpTaskBody["rowCount"]

  return {
    'statusCode': 200,
    'body': json.dumps(rowCount)
  }

Google Cloud-Funktionen: Im Folgenden wird ein Pseudo-Code für Google Cloud-Funktionen angezeigt:

def get_row_count(request):
  request_json = request.get_json()
  if request_json and 'rowCount' in request_json:
        rowCount = request_json['rowCount']
    return rowCount
  return 'No rowCount attribute provided'

Dataset mit API-Antwort für Designer Cloud-Workflow erstellen

Verwenden Sie die HTTP-Aufgabe in Plans, um Datasets mit Antworten auf API-Aufrufe zu lesen und zu erzeugen, die natürlich im Designer Cloud-Workflow verwendet werden können.

HTTP-Aufgabe definieren

Parameter	Beschreibung
Name	Dieser Name erscheint nur in Alteryx One.
Methode	Pflichtfeld. Wählen Sie die `POST`- oder die `GET`-Methode aus.
URL	Pflichtfeld. URL, unter der die HTTP-Anfrage von der anderen Anwendung empfangen wird. Beispiel: `https://example.com/${id}`
Header	HTTP-Content-Header als Schlüssel-Wert-Paare in einem JSON-Format. { "X-Custom-Header": "value", "X-Parametrized-Header": "${wf1.id}" }
Text	Der Text der Anforderung, die an die empfangende Anwendung gesendet wurde. Kann `${variables}` enthalten. {"text":"My text message to the receiving application."}

Allgemeine Schritte:

Erstellen Sie einen Workflow mit Ihren Eingaben.
Erstellen und führen Sie einen Plan mit einer HTTP-Aufgabe aus, um ein Dataset zu generieren.
Deaktivieren Sie unbedingt das Kontrollkästchen Dataset mit API-Aufrufantwort löschen und legen Sie dadurch fest, dass das Dataset in der Aufgabe beibehalten wird.
Verwenden Sie in Designer Cloud das Dataset, das im vorherigen Schritt generiert wurde, um einen Workflow zu erstellen, der mit der API-Antwort beginnt.
Wenn Sie das Kontrollkästchen Konfiguration aus Dataset laden aktivieren, können Sie eine Konfiguration (mit allen Parametern) aus dem Ausgabedataset der vorgelagerten Workflow-Aufgabe laden.
Achtung
Im Abschnitt Einschränkungen finden Sie Informationen zu den Grenzwerten für Eingabedatasets.
Fügen Sie im Plan den Workflow als nachgelagerte Aufgabe für eine bereits vorhandene HTTP-Aufgabe hinzu. Ändern Sie den Plan, um die HTTP-Aufgabenausgabe (in Schritt 1 angegeben) als Designer Cloud-Workflow-Eingabe zu verwenden.
Sie können den Plan jetzt einplanen. Bei dieser Konfiguration wird ein API-Aufruf durchgeführt. Die Antwort wird an den Designer Cloud-Workflow übergeben und ausgeführt. Die Endausgabe ist wie gewohnt verfügbar.

Signaturen überprüfen

Warnung

Je nach Zielanwendung erfordert die Implementierung der Signaturüberprüfung möglicherweise Kenntnisse von Entwickler:innen.

Optional können Sie die Plattform so konfigurieren, dass die HTTP-Anfragen signiert werden. Signierte Anfragen garantieren, dass die Anfragen von der Plattform und nicht von einer Drittpartei gesendet werden.

Im Folgenden können Sie prüfen, wie die Signatur erstellt wird, damit Sie die empfangende Anwendung so konfigurieren können, dass die Signatur und die zugehörige Anfrage ordnungsgemäß verarbeitet werden.

Signatur-Header

HTTP-Anfragen werden signiert, indem der X-Webhook-Signatur-Header in die Anfrage eingefügt wird. Diese Signaturen haben folgende Form:

X-Webhook-Signature: t=<timestamp>,sha256=<signature>

wobei:

<timestamp>: Zeitstempel des Sendens der Signatur. Der Wert ist in UNIX-Zeit angegeben.
<signature>: SHA256-Signatur. Die Plattform generiert diese Signatur mithilfe eines hashbasierten Message Authentication Code (HMAC) mit SHA-256.

Weitere Informationen zu diesen Werten finden Sie unten.

Beispiel:

X-Webhook-Signature: t=1568818215724,sha256=55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a

Anwendungs-Tools prüfen

Je nach Anwendung müssen Sie möglicherweise eine der folgenden Aufgaben ausführen, um die Aufgabensignaturen zu überprüfen:

Anmerkung

Möglicherweise müssen Sie die Plattform in Ihrer Anwendung auf die Whitelist setzen. Weitere Informationen finden Sie in der Dokumentation der Anwendung.

Möglicherweise müssen Sie eine benutzerdefinierte Codierung für Ihre Anwendung erstellen. Im Folgenden finden Sie Einzelheiten dazu, einschließlich eines JavaScript-Beispiels.

Signierte Anfragen verarbeiten

Zeitstempel

Der Zeitstempelwert (t=<timestamp>) wird am Anfang des Header-Werts angezeigt, um Replay-Angriffe zu verhindern, bei denen Angreifer:innen eine gültige Nutzlast und deren Signatur abfangen und erneut übertragen könnten.

Um solche Angriffe zu vermeiden, ist ein Zeitstempel im Signatur-Header enthalten und in die signierte Nutzlast eingebettet.
Da der Zeitstempel Teil der signierten Nutzlast ist, können Angreifer:innen den Zeitstempelwert nicht ändern, ohne die Signatur ungültig zu machen.
- Wenn die Signatur gültig ist, der Zeitstempel jedoch zu alt ist, können Sie die Anfrage ablehnen.
- Wenn Sie beispielsweise eine Anfrage mit einem Zeitstempel von vor einer Stunde erhalten, sollten Sie die Anfrage wahrscheinlich ablehnen.
Weitere Informationen zu Replay-Angriffen finden Sie unter https://de.wikipedia.org/wiki/Replay-Angriff.

Signatur

Die Aufgabensignatur enthält als Teil ihres gehashten Werts Folgendes:

Den geheimen Schlüssel (oben eingegeben)
Den Zeitstempelwert
Anfragedaten:
- (POST/PUT/PATCH): der Text der Anfrage
- (GET/DELETE): URL der Anfrage

Schritt 1: Den Zeitstempel und die Signaturen extrahieren

Teilen Sie den X-Webhook-Signatur-Header auf:

Teilen Sie Werte mit einem Komma (,) als Trennzeichen auf.
Teilen Sie jeden Teil mit dem Gleichheitszeichen (=) auf.
Extrahieren Sie die Werte für den Zeitstempel und die Signatur. Aus dem obigen Beispiel:
1. Zeitstempel: 1568818215724
2. Signatur: 55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a

Schritt 2: Die erwartete Signatur erstellen

In der empfangenden Anwendung können Sie die Signatur neu berechnen, um zu überprüfen, ob die Anfrage von der Plattform gesendet wurde.

Verketten Sie den Zeitstempel, den Punkt . und den Anforderungstext (POST/PUT/PATCH-Methoden) oder die URL (GET/DELETE-Methoden).
Nehmen wir an, das obige Beispiel ist die Signatur für eine POST-Anfrage und der Anfragetext ist Test. Dann lautet der verkettete Wert wie folgt:
```
1568818215724.test
```

Sie können jetzt den HMAC-Authentifizierungscode in Ihrer empfangenden Anwendung berechnen. Im folgenden JavaScript-Beispiel lautet der Wert des geheimen Schlüssels mySecret:

const crypto = require('crypto');

const message = '1568818215724.test'; // as defined above

const hmac = crypto.createHmac('sha256', 'mySecret');
hmac.update(message)
const expectedSignature = hmac.digest('hex');

Schritt 3: Die Signaturen vergleichen

Der von Ihrem Code zurückgegebene Wert und der als Signatur im X-Webhook-Signatur-Header enthaltene Wert müssen verglichen werden:

Wenn die Werte nicht übereinstimmen, lehnen Sie die Anfrage ab.
Wenn die Werte übereinstimmen, berechnen Sie die Differenz zwischen dem aktuellen Zeitstempel und dem Zeitstempel im Header. Wenn die Differenz außerhalb des zulässigen Limits liegt, lehnen Sie die Anfrage ab.
Andernfalls verarbeiten Sie die Anfrage normal in Ihrer Anwendung.

HTTP-Konfiguration aus dem Dataset laden

Falls Sie eine dynamische API-Anfrage oder mehrere Anfragen erstellen müssen, können Sie mit Designer Cloud eine Ausgabe mit der Konfiguration definieren und diese Ausgabe in Plans an die HTTP-Aufgabe übergeben.

Um eine Ausgabe mit der Konfiguration zu definieren und für die HTTP-Aufgabe zu verwenden, gehen Sie wie folgt vor:

Erstellen Sie einen Workflow in Designer Cloud. Weitere Informationen finden Sie hier: Workflows erstellen.
Legen Sie im Workflow das Ausgabedateiformat als CSV fest, das die folgenden Spalten enthält (keine Berücksichtigung der Groß-/Kleinschreibung bei Namen):
- Methode (Zeichenfolge, Werte: GET | POST | DELETE | PUT)
- URL (Zeichenfolge, die Anfrage-URL)
- Header (Zeichenfolge, die Liste der Header mit Werten im Format {„Name“:„Wert“, „Name“:„Wert“, ...})
- Text (Zeichenfolge)
Gehen Sie zu Plans und erstellen Sie einen Plan.
Fügen Sie eine Designer Cloud-Aufgabe hinzu, und wählen Sie den neu erstellten Workflow aus.
Fügen Sie nach der Designer Cloud-Aufgabe eine HTTP-Aufgabe hinzu und verbinden diese mit einer Konnektor-Linie.
Aktivieren Sie in der HTTP-Konfiguration das Kontrollkästchen Konfiguration aus Dataset laden und das Kontrollkästchen Konfiguration aus Dataset laden.
Klicken Sie auf die Schaltfläche Eingabedataset auswählen.
Wählen Sie die Designer Cloud-Aufgabe und ihre Ausgabedaten mit der HTTP-Konfiguration aus.
Wählen Sie Bestätigen aus.
Das Kontrollkästchen Dataset aus Antwort erstellen wird automatisch aktiviert. Sie können den Namen des Datasets anpassen und den Plan ausführen.

Anmerkung

Jede Zeile in der Ausgabedatei der Konfiguration führt zu einer separaten Anfrage. Die Antwort auf jede Anfrage wird als neue Zeile im Ausgabedataset hinzugefügt.

HTTP-Antwort als Eingabe für nachgelagerte Aufgaben verwenden

Nachdem Sie die HTTP-Aufgabe so festgelegt haben, dass ein Dataset aus einer Antwort erstellt wird, können Sie dieses Dataset als Eingabe für nachgelagerte Aufgaben verwenden.

Um das Dataset als Eingabe für eine nachgelagerte Aufgabe zu verwenden, gehen Sie wie folgt vor:

Aktivieren Sie in der HTTP-Konfiguration das Kontrollkästchen Dataset aus Antwort erstellen.
Fügen Sie eine Designer Cloud-Aufgabe nach der HTTP-Aufgabe hinzu und verbinden Sie sie mit einer Konnektor-Linie.
Wählen Sie in der Designer Cloud-Aufgaben den gewünschten Workflow aus.
Wählen Sie in der Liste der Workflow-Eingaben die Option Überschreiben bei der Eingabe aus, die Sie mit der HTTP-Antwort überschreiben möchten.
Wählen Sie die HTTP-Aufgabe und ihre Ausgabe aus.
Wählen Sie Bestätigen aus und führen Sie den Plan aus.

In diesem Abschnitt:

HTTP-Aufgabe

Beschränkungen

Voraussetzungen

Voraussetzungen der empfangenden Anwendung

Aufgabe erstellen

Aufgabe konfigurieren

Aufgabe umbenennen

Aufgabe löschen

Referenzen zu Planmetadaten

Beispiele

Nachricht an Slack-Kanal

Beispiele für Planmetadaten

Metadateneingaben in Cloud-Funktion einspeisen

Dataset mit API-Antwort für Designer Cloud-Workflow erstellen

Signaturen überprüfen

Signatur-Header

Anwendungs-Tools prüfen

Signierte Anfragen verarbeiten

HTTP-Konfiguration aus dem Dataset laden

HTTP-Antwort als Eingabe für nachgelagerte Aufgaben verwenden

Suchresultat