HTTP API

Die HTTP API ermöglicht es einem MES, einem SCADA-System oder Ihrer eigenen Software, direkt über das Netzwerk mit der Kamera zu arbeiten – mit oder ohne SPS. Über die API können Sie:

• Eine Prüfung triggern und deren Ergebnis im selben Aufruf erhalten
• Vergangene Ergebnisse abrufen oder diese live mit ihren Bildern, Heatmaps und Segmentierungsmasken verfolgen, sobald sie abgeschlossen sind
• Rezepte auflisten und das aktive Rezept wechseln
• Zwischen Einrichtungsmodus und Produktionsmodus wechseln
• Die OK/NG-Zähler lesen und zurücksetzen

Gehen Sie zu Integration → HTTP API:

Bereich	Was er bietet
Connection	Die Base URL, mit der jeder Aufruf beginnt, z. B. http://10.250.0.100/api/integration/v1, die API-Version und ob Aufrufe einen Benutzernamen und ein Passwort erfordern
Download OpenAPI spec	Eine maschinenlesbare Beschreibung jedes Endpunkts mit seinen Parametern und Antworten. Geben Sie sie Ihren Entwicklern oder laden Sie sie in Postman oder ein beliebiges OpenAPI-Tool
Ready to trigger?	Eine Live-Checkliste dessen, was zutreffen muss, bevor POST /trigger funktioniert
Endpoints und Examples	Jeder Endpunkt, gruppiert nach Funktion, sowie kopierfertige Beispielaufrufe

Vor dem ersten Trigger

Das Panel Ready to trigger? prüft drei Dinge. POST /trigger wird abgelehnt, bis alle drei erfüllt sind, und der Fehler nennt die fehlgeschlagene Prüfung.

1. Produktionsmodus. Schalten Sie die Kamera über die obere Leiste aus dem Einrichtungsmodus, oder rufen Sie POST /mode/run auf.
2. Aktives Rezept. Ein Rezept muss aktiv sein. Aktivieren Sie eines unter All Recipes oder rufen Sie POST /recipes/{id}/activate auf.
3. Akzeptiert HTTP-Trigger. Öffnen Sie im aktiven Rezept Schritt 2: Triggering, wählen Sie External und aktivieren Sie HTTP unter Enabled sources.

HTTP ist eine Quelle unter mehreren

Sie können mehr als eine Quelle aktivieren. Ein Rezept kann einen Hardware-Trigger an der Linie und gleichzeitig einen HTTP-Trigger von Ihrer Software akzeptieren. Eine nicht aktivierte Quelle wird ignoriert, auch wenn etwas Daten an sie sendet.

Eine Prüfung triggern

curl -X POST http://10.250.0.100/api/integration/v1/trigger \
  -H "Content-Type: application/json" \
  -d '{"wait_ms": 5000}'

Der Aufruf wartet bis zu wait_ms Millisekunden (standardmäßig 5000, bis zu 30000) darauf, dass die Prüfung abgeschlossen wird:

Antwort	Bedeutung	Was zu tun ist
200	Das fertige Ergebnis	Lesen Sie judgment: pass, fail oder not_inspected
202	Akzeptiert, aber nicht innerhalb von wait_ms abgeschlossen	Pollen Sie GET /results?trigger_id= mit der zurückgegebenen trigger_id
409	Die Kamera ist nicht bereit	Beheben Sie das, was code nennt: Produktionsmodus, aktives Rezept oder die HTTP-Quelle
503	Ein vorübergehender Zustand, z. B. eine noch laufende Prüfung	Erneut versuchen

Senden Sie jeweils nur einen Trigger

Die Kamera prüft jeweils einen Trigger. Ein Trigger, der gesendet wird, während der vorherige noch läuft, wird mit 503 abgelehnt, sofern der Image trigger buffer des Rezepts es nicht erlaubt, zu warten. Senden Sie den nächsten Trigger erst, nachdem die vorherige Antwort eingegangen ist.

Behandeln Sie not_inspected als NG

not_inspected bedeutet, dass jedes Prüfwerkzeug übersprungen wurde, meist weil die Ausrichtung das Teil nicht gefunden hat. Nichts wurde geprüft, behandeln Sie es daher als NG, niemals als OK.

Ergebnisse lesen

Aufruf	Rückgabe
GET /results/latest	Das aktuellste Ergebnis
GET /results	Ergebnisse, neueste zuerst, filterbar nach Rezept oder Trigger
GET /results/{id}	Ein Ergebnis mit der Beurteilung jedes Werkzeugs
GET /results/{id}/image	Das geprüfte Bild als JPEG
GET /results/{id}/tools/{tool_id}/heatmap	Die Heatmap einer Region als PNG
GET /results/{id}/tools/{tool_id}/mask	Die Segmentierungsmaske einer Region als PNG
GET /results/stream	Ein Live-Stream der Ergebnisse, sobald sie abgeschlossen sind, aus jeder Trigger-Quelle

GET /results/stream verwendet Server-Sent Events: Halten Sie eine Verbindung offen, und jede abgeschlossene Prüfung trifft ein, sobald sie geschieht – egal, ob sie über HTTP, von einer SPS oder von einem Sensor ausgelöst wurde. Das ist in der Regel einfacher als Polling.

Jedes Werkzeug meldet ok, ng, indeterminate oder not_applicable, und das Gesamtergebnis meldet pass, fail oder not_inspected.

Weitere Aufrufe

Gruppe	Aufrufe
Device	GET /health, GET /device, GET /status, GET /whoami, GET /openapi.yaml
Recipes	GET /recipes, GET /recipes/active, POST /recipes/{id}/activate
Statistics	GET /statistics, POST /statistics/reset, GET /statistics/stream
Control	POST /mode/run, POST /mode/setup
Fieldbus	GET /fieldbus, GET /fieldbus/descriptor (die EDS- oder GSDML-Datei für das aktive Protokoll)

Ein Rezept wird durch seine Nummer identifiziert – dieselbe PLC recipe ID, mit der eine SPS es auswählt, festgelegt in Schritt 5: Outputs.

Warten Sie, bis der Moduswechsel abgeschlossen ist

Pollen Sie nach POST /mode/run GET /status, bis mode den Wert run hat und mode_changing false ist, bevor Sie triggern. Der Moduswechsel dauert einen Moment, während das Rezept geladen wird.

Anmeldung und Sicherheit

Solange die Kamera keinen Admin-Benutzer hat, benötigt die API keine Anmeldedaten. Sobald ein Admin existiert, erfordert jeder Aufruf außer /health, /whoami und /openapi.yaml den Benutzernamen und das Passwort eines Kamerakontos, gesendet als HTTP Basic Authentication:

curl -u line3-mes:PASSWORD http://10.250.0.100/api/integration/v1/results/latest

Geben Sie jedem angebundenen System ein eigenes Konto

Erstellen Sie unter Users and Permissions ein Konto pro System, damit die Audit Logs zeigen, welches System was gemacht hat. Vergeben Sie die niedrigste Rolle, die die Aufgabe erfüllt; GET /whoami mit den Anmeldedaten dieses Kontos listet genau auf, welche Aufrufe erlaubt sind. Aktivieren Sie HTTPS in den System Settings, damit Passwörter nicht im Klartext über das Netzwerk übertragen werden.

Die API wächst nur innerhalb von /api/integration/v1: Neue Endpunkte und Felder können hinzukommen, aber bestehende ändern niemals ihre Bedeutung und verschwinden nicht. Code, der heute dagegen geschrieben wird, funktioniert auch nach einem Firmware-Update weiter.

Wie geht es weiter?

• Schritt 2: Triggering, um die HTTP-Quelle zu aktivieren
• Users and Permissions, um für jedes System ein Konto zu erstellen
• Industrial Ethernet, falls auch eine SPS beteiligt ist
• Remote-Speicher, um Bilder und Ergebnisse stattdessen an einen Dateiserver zu senden