gRPC-Konnektor

Übersicht

Der gRPC-Konnektor ermöglicht es Meddle, gRPC-Dienste sowohl als Client-Reader (Polling von Unary-Aufrufen) als auch als Writer (Weiterleitung von Payloads als gRPC-Anfragen) aufzurufen. Er verwendet HTTP/2 im Hintergrund und unterstützt optionales TLS, wodurch er sich für die Integration mit modernen Microservices, Edge-Gateways und industriellen APIs eignet, die gRPC-Endpunkte bereitstellen.

Konnektor-Typen:

• GrpcReader - Ruft periodisch eine Unary-gRPC-Methode auf und gibt die Antwort als Meddle-Payload aus
• GrpcWriter - Sendet jede eingehende Payload als gRPC-Anfrage an den Zieldienst

Funktionen

• ✅ HTTP/2-Transport mit optionaler TLS-Verschlüsselung
• ✅ Polling-basierter Unary-Reader mit konfigurierbarer Rate
• ✅ Writer leitet Payloads als JSON-codierte gRPC-Anfragen weiter
• ✅ Statischer Request-Body für Lese-Polling
• ✅ Streaming-bewusster Konfigurations-Flag
• ✅ Automatisches Verbindungsmanagement und Wiederverwendung
• ✅ Pro-Aufruf-Timeout von 10 Sekunden zur Sicherheit

Grundkonfiguration

gRPC Reader

Plaintext

{
  "type": "GrpcReader",
  "config": {
    "address": "192.168.1.50:50051",
    "service": "iot.SensorService",
    "method": "GetReading",
    "pollingRate": 1000,
    "requestBody": "{\"sensorId\":\"sensor-1\"}"
  }
}

Mit TLS

{
  "type": "GrpcReader",
  "config": {
    "address": "edge.example.com:443",
    "service": "iot.SensorService",
    "method": "GetReading",
    "tls": true,
    "pollingRate": 5000,
    "requestBody": "{\"sensorId\":\"sensor-1\"}"
  }
}

Streaming

{
  "type": "GrpcReader",
  "config": {
    "address": "192.168.1.50:50051",
    "service": "iot.TelemetryService",
    "method": "Subscribe",
    "streaming": true,
    "pollingRate": 1000,
    "requestBody": "{\"deviceId\":\"plc-line-1\"}"
  }
}

gRPC Writer

{
  "type": "GrpcWriter",
  "config": {
    "address": "192.168.1.50:50051",
    "service": "iot.SensorService",
    "method": "PushReading",
    "tls": false
  }
}

Konfigurationsparameter

Address

Host und Port des gRPC-Servers.

{
  "address": "192.168.1.50:50051"
}

Format: host:port (kein Schema-Präfix). Für TLS-Endpunkte setzen Sie tls: true, anstatt es in der Adresse zu codieren.

Service

Der voll qualifizierte gRPC-Dienstname, wie er in Ihrer .proto-Datei definiert ist, einschließlich des Paket-Präfixes.

{
  "service": "iot.SensorService"
}

Format: package.ServiceName. Der Konnektor erstellt intern den vollständigen Methodenpfad als /{service}/{method}.

Method

Der Name der aufzurufenden Methode des Dienstes.

{
  "method": "GetReading"
}

Dieser muss exakt mit dem Methodennamen übereinstimmen, der in der Proto-Definition deklariert ist (Groß-/Kleinschreibung beachten).

TLS

Aktiviert TLS für die Verbindung. Bei Deaktivierung verwendet der Konnektor unsichere (Plaintext-)Anmeldedaten.

{
  "tls": true
}

Empfohlene Werte:

• false - In vertrauenswürdigen Netzwerkumgebungen (LAN/SPS)
• true - Öffentliche Endpunkte, Cloud-Dienste, alles was nicht vertrauenswürdige Netzwerke durchquert

Request Body

Statischer JSON-Body, der bei jedem Poll als Anfrage-Payload gesendet wird.

{
  "requestBody": "{\"sensorId\":\"sensor-1\",\"includeHistory\":false}"
}

Hinweise:

• Muss ein gültiger JSON-String sein. Innere Anführungszeichen wie gezeigt escapen
• Wenn weggelassen, wird ein leeres JSON-Objekt {} gesendet
• Der Request-Body wird als json.RawMessage behandelt und bei jedem Poll unverändert weitergeleitet

Polling Rate

Intervall in Millisekunden zwischen aufeinanderfolgenden gRPC-Aufrufen (nur Reader).

{
  "pollingRate": 1000
}

Empfohlene Werte:

• Schnell: 100-500ms
• Normal: 1000ms (1 Sekunde)
• Langsam: 5000ms+ (5 Sekunden oder mehr)

Streaming

Flag, das angibt, dass die Zielmethode Server-Streaming-Semantik verwendet.

{
  "streaming": true
}

Wenn gesetzt, gibt der Konnektor weiterhin Aufrufe gemäß der Polling-Kadenz aus, kennzeichnet jedoch die Konfiguration als streaming-bewusst, damit nachgelagerte Tools ihre Erwartungen anpassen können. Verwenden Sie dies für Methoden, die zunehmend größere Payloads zurückgeben oder einen längeren Verbindungslebenszyklus aufrechterhalten.

Datenfluss

Reader-Datenfluss

gRPC-Server → GrpcReader (Unary-Invoke) → JSON-Antwort → Meddle-Payload

Beispiel:

Reader-Konfiguration:

{
  "address": "192.168.1.50:50051",
  "service": "iot.SensorService",
  "method": "GetReading",
  "requestBody": "{\"sensorId\":\"sensor-1\"}",
  "pollingRate": 1000
}

Server-Antwort:

{
  "temperature": 24.7,
  "humidity": 58.3,
  "battery": 0.91,
  "timestamp": "2026-05-20T10:14:33Z"
}

Ausgegebene Meddle-Payload:

{
  "temperature": 24.7,
  "humidity": 58.3,
  "battery": 0.91,
  "timestamp": "2026-05-20T10:14:33Z"
}

Writer-Datenfluss

Meddle-Payload → GrpcWriter (JSON-Codierung) → gRPC-Server

Beispiel:

Eingehende Payload:

{
  "deviceId": "plc-line-1",
  "setpoint": 75.0,
  "mode": "auto"
}

Der Writer codiert die Payload als JSON und ruft /iot.SensorService/PushReading damit als Request-Body auf. Jede Antwort des Servers wird gelesen und verworfen.

Häufige Anwendungsfälle

1. Polling einer Microservice-Telemetrie-API

Sensordaten von einem internen Microservice über das LAN lesen:

{
  "type": "GrpcReader",
  "config": {
    "address": "telemetry.internal:50051",
    "service": "telemetry.DeviceService",
    "method": "GetMetrics",
    "pollingRate": 2000,
    "requestBody": "{\"deviceId\":\"compressor-3\"}"
  }
}

2. Aggregierte Daten an einen Cloud-gRPC-Endpunkt senden

Verarbeitete Payloads über TLS an einen Cloud-Dienst weiterleiten:

{
  "type": "GrpcWriter",
  "config": {
    "address": "api.example.cloud:443",
    "service": "ingest.MetricsService",
    "method": "Push",
    "tls": true
  }
}

3. Edge-zu-Edge-Kommunikation zwischen Meddle-Instanzen

Zwei Meddle-Bereitstellungen über gRPC als Transport verbinden:

{
  "type": "GrpcWriter",
  "config": {
    "address": "edge-aggregator.local:50052",
    "service": "meddle.BridgeService",
    "method": "Forward",
    "tls": false
  }
}

Fehlerbehebung

Verbindung abgelehnt

Problem: connection refused oder transport: error while dialing

Lösungen:

1. Adresse und Port überprüfen
2. Bestätigen, dass der gRPC-Server läuft und lauscht
3. Firewall-Regeln prüfen (telnet host port für einen schnellen Erreichbarkeitstest)
4. Wenn der Server TLS erfordert, tls: true setzen

Methode nicht gefunden

Problem: rpc error: code = Unimplemented oder unknown method

Lösungen:

1. Überprüfen, ob service der voll qualifizierte Name einschließlich des Pakets ist (z.B. iot.SensorService, nicht nur SensorService)
2. Bestätigen, dass method exakt mit der Proto-Deklaration übereinstimmt (Groß-/Kleinschreibung beachten)
3. Verwenden Sie ein Tool wie grpcurl, um Dienste am Endpunkt aufzulisten:

   grpcurl -plaintext 192.168.1.50:50051 list

Ungültiger Request-Body

Problem: Deserialisierungsfehler auf dem Server

Lösungen:

1. Validieren, dass requestBody wohlgeformtes JSON ist
2. Sicherstellen, dass die Feldnamen exakt mit den Proto-Feldnamen übereinstimmen (gRPC-JSON-Transcoding beachtet Groß-/Kleinschreibung)
3. Wenn Ihr Server binäre Protobufs erwartet, muss gRPC-JSON-Transcoding (oder grpc-gateway) serverseitig aktiviert sein

TLS-Handshake-Fehler

Problem: TLS-Handshake- oder Zertifikatsfehler

Lösungen:

1. Bestätigen, dass das Serverzertifikat gültig und vertrauenswürdig ist
2. Sicherstellen, dass der Adress-Hostname mit dem SAN des Zertifikats übereinstimmt
3. Bei selbstsignierten Zertifikaten die CA in den Truststore des Meddle-Hosts installieren

Timeouts

Problem: Wiederholte 10-Sekunden-Timeouts bei jedem Aufruf

Lösungen:

1. Server-seitige Latenz untersuchen
2. Wenn die Antwort durchgehend langsam ist, ist das Unary-10s-Timeout eine harte Obergrenze — erwägen Sie eine Streaming-Methode oder einen anderen Transport
3. pollingRate reduzieren, um zu vermeiden, dass sich Aufrufe hinter langsamen Antworten stauen

Best Practices

1. Außerhalb vertrauenswürdiger Netzwerke immer TLS verwenden

Lassen Sie tls: false niemals für Endpunkte, die das öffentliche Internet durchqueren:

{
  "tls": true
}

2. Polling-Raten ehrlich halten

Ein 100ms-Poll gegen einen entfernten gRPC-Server kann nachgelagerte Rate-Limits sättigen. Beginnen Sie bei 1000ms und straffen Sie nur bei berechtigtem Anlass.

3. Stabile, bekannte Dienste verwenden

Bevorzugen Sie Dienste mit expliziten .proto-Verträgen und versionierten Paketen (z.B. iot.v1.SensorService), damit Reader-Konfigurationen bei Server-Upgrades nicht brechen.

4. Request-Bodies bewusst codieren

Inline-requestBody eignet sich hervorragend für statische Parameter, aber schlecht für dynamische Werte. Für dynamische Request-Bodies kombinieren Sie einen vorgelagerten Reshape- oder Transform-Konnektor mit einem GrpcWriter anstelle eines Readers.

5. Mit Validation kombinieren

Leiten Sie gRPC-Antworten immer durch einen Validation-Konnektor, bevor sie an nachgelagerte Writer gehen, da sich Server-Schemas schneller entwickeln können als Ihre Meddle-Pipeline.

Beispiel-Workflows

Reader → Speicher-Pipeline

GrpcReader → Validation → Reshape → InfluxDb2Writer

1. GrpcReader: Pollt /iot.SensorService/GetReading jede Sekunde
2. Validation: Stellt sicher, dass erforderliche Schlüssel vorhanden und numerisch sind
3. Reshape: Fügt Tags wie location, device_type hinzu
4. InfluxDb2Writer: Speichert in einer Zeitreihendatenbank

SPS → Cloud-Bridge

ModbusReader → Filter → GrpcWriter (Cloud-Ingest)

1. ModbusReader: Holt Registerwerte von einer SPS im 1s-Takt
2. Filter: Behält nur die weiterzuleitenden Schlüssel
3. GrpcWriter: Sendet die gefilterte Payload über TLS an eine Cloud-ingest.MetricsService.Push-Methode

Verwandte Konnektoren

• HTTP Client - Alternative für REST/HTTP-Dienste
• MQTTv5 - Asynchrone broker-basierte Integration
• Kafka - Streaming-Alternative mit hohem Durchsatz
• Validation - gRPC-Antwort-Payloads validieren
• Reshape - Felder aus gRPC-Antworten umbenennen und anreichern

Zusätzliche Ressourcen

• Offizielle gRPC-Seite
• gRPC-Protokoll-Dokumentation
• Protocol Buffers-Referenz
• grpcurl - Kommandozeilen-gRPC-Client zum Testen von Endpunkten
• gRPC-Statuscodes