Zum Hauptinhalt springen

MakeHttpRequest@1

Der Node MakeHttpRequest@1 dient dazu, HTTP-Anfragen an externe APIs oder Dienste zu senden und die Antwort in der Payload der Datenpipeline zu speichern. Dieser Node unterstützt verschiedene HTTP-Methoden, Path-Parameter, Header und Request-Bodies und eignet sich damit für die Integration mit REST-APIs und Web-Services.

  • Die Antwort der HTTP-Anfrage wird am angegebenen Zielpfad in der Payload gespeichert.
  • Unterstützt die dynamische Konstruktion von URLs über Path-Parameter.
  • Ermöglicht das Setzen benutzerdefinierter Header für Authentifizierungs- und Content-Type-Anforderungen.

Adapter-Voraussetzungen​

Node-Konfiguration​

Zu den Feldern path, targetPath, targetValueWriteMode und targetValueKind siehe Überblick.

transformations:
  - type: MakeHttpRequest@1
    targetPath: _httpResponse # Path where the HTTP response should be stored in the payload
    method: GET # HTTP method to use (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
    url: https://api.example.com/users/{userId} # The URL to make the request to
    urlPath: $.apiUrl # Alternative: path to URL in payload
    body: '{"name": "John", "email": "john@example.com"}' # Request body for non-GET requests
    bodyPath: $.requestBody # Alternative: path to body content in payload
    pathParameters: # Parameters to replace in URL placeholders
      - name: userId
        valuePath: $.user.id # Get user ID from payload
      - name: companyId
        value: "12345" # Static company ID value
    headerParameters: # HTTP headers to include in request
      - name: Authorization
        valuePath: $.authToken # Get auth token from payload
      - name: Content-Type
        value: "application/json" # Static content type header
      - name: User-Agent
        value: "OctoMesh-Adapter/1.0" # Static user agent

Konfigurationseigenschaften​

  • method (string): Die für die Anfrage zu verwendende HTTP-Methode. Gültige Werte sind: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Standard ist GET.

  • url (string?): Die URL, an die die HTTP-Anfrage gesendet wird. Kann Path-Parameter im Format {parameterName} enthalten, die durch Werte aus pathParameters ersetzt werden.

  • urlPath (string?): Der JSON-Pfad zur URL in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft url definiert werden.

  • body (string?): Der Inhalt des Request-Bodys als String. Wird nur für Nicht-GET-Anfragen (POST, PUT, PATCH, DELETE) verwendet.

  • bodyPath (string?): Der JSON-Pfad zum Inhalt des Request-Bodys in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft body definiert werden.

  • pathParameters (List<HttpPathParameter>): Eine Liste von Path-Parametern zum Ersetzen von URL-Platzhaltern. Jeder Parameter hat:

    • name (string): Der Name des Path-Parameters (entspricht {name} in der URL)
    • value (string?): Statischer Wert für den Parameter
    • valuePath (string?): JSON-Pfad, um den Parameterwert aus der Payload zu holen

  • headerParameters (List<HttpHeaderParameter>): Eine Liste von HTTP-Headern, die in die Anfrage aufgenommen werden. Jeder Header hat:

    • name (string): Der Name des HTTP-Headers (z. B. "Authorization", "Content-Type")
    • value (string?): Statischer Wert für den Header
    • valuePath (string?): JSON-Pfad, um den Header-Wert aus der Payload zu holen

Anwendungsbeispiel​

Hier ein Beispiel, wie Sie den Node MakeHttpRequest@1 in einer Transformations-Pipeline verwenden könnten:

transformations:
  - type: MakeHttpRequest@1
    targetPath: _apiResponse # Store the HTTP response in this path
    targetValueKind: String # Store response as string
    targetValueWriteMode: Replace # Replace any existing value
    method: POST # Use POST method
    url: https://api.weatherservice.com/v1/locations/{locationId}/readings
    pathParameters:
      - name: locationId
        valuePath: $.sensor.locationId # Get location ID from sensor data
    headerParameters:
      - name: Authorization
        valuePath: $.credentials.apiKey # Get API key from credentials
      - name: Content-Type
        value: "application/json" # Set content type to JSON
      - name: X-Client-Version
        value: "1.0.0" # Set client version header
    bodyPath: $.sensorReading # Get request body from sensor reading data

In diesem Beispiel:

  • Wir senden eine POST-Anfrage an eine Wetterdienst-API.
  • Die locationId in der URL wird dynamisch durch einen Wert aus der Payload ersetzt.
  • Die Authentifizierung erfolgt über einen API-Key-Header, der aus der Payload gelesen wird.
  • Der Request-Body enthält Sensormessdaten aus der Payload.
  • Die API-Antwort wird im Feld _apiResponse zur weiteren Verarbeitung gespeichert.

Fortgeschrittenes Anwendungsbeispiel​

Hier ein komplexeres Beispiel, das Authentifizierung und Fehlerbehandlung zeigt:

transformations:
  # First, prepare authentication token
  - type: MakeHttpRequest@1
    targetPath: _authToken
    targetValueKind: String
    targetValueWriteMode: Replace
    method: POST
    url: https://auth.example.com/token
    headerParameters:
      - name: Content-Type
        value: "application/x-www-form-urlencoded"
    body: "grant_type=client_credentials&client_id=your_client_id&client_secret=your_secret"

  # Then use the token to make the actual API call
  - type: MakeHttpRequest@1
    targetPath: _userData
    targetValueKind: String
    targetValueWriteMode: Replace
    method: GET
    url: https://api.example.com/users/{userId}
    pathParameters:
      - name: userId
        valuePath: $.user.id
    headerParameters:
      - name: Authorization
        valuePath: $._authToken # Use token from previous request
      - name: Accept
        value: "application/json"

Hinweise​

  • Werden für eine Eigenschaft sowohl der direkte Wert als auch der zugehörige Pfad angegeben (z. B. sowohl url als auch urlPath), hat der direkte Wert Vorrang.
  • Wird bei Nicht-GET-Anfragen kein Body angegeben (weder body noch bodyPath), wird die Anfrage ohne Inhalt gesendet.
  • Path-Parameter in der URL werden beim Ersetzen unabhängig von Groß- und Kleinschreibung behandelt.
  • Ist der Wert eines Path-Parameters null oder leer, wird eine Warnung protokolliert, die Anfrage wird jedoch trotzdem ausgeführt.
  • HTTP-Header, die nicht hinzugefügt werden können (aufgrund von Einschränkungen oder ungültigen Werten), protokollieren eine Warnung, stoppen die Anfrage aber nicht.
  • Der Antwortinhalt wird immer als String gespeichert, unabhängig vom tatsächlichen Content-Type, den der Server zurückgibt.
  • Schlägt die HTTP-Anfrage fehl (Statuscode ohne Erfolg), wird ein Fehler protokolliert und die Pipeline-Verarbeitung für dieses Element wird gestoppt.