ENLYZE API abfragen

API-Abfragen für die ENLYZE Datenquelle in Grafana.

Lernziele

• Grafanas Zeitbereich in API-Abfragen verwenden

• Aufträge mit OEE-Kennzahlen abfragen

• API-Antworten mit JSONata transformieren

• Stillstände zur Analyse abfragen

• API-Abfragen debuggen

Voraussetzungen

• Tutorial 4.1 (Einführung in Infinity) abgeschlossen

• Verständnis von GET-Anfragen und JSONPath

---

Überblick

Im vorherigen Tutorial hast du gelernt, einfache GET-Anfragen zu stellen. Jetzt geht es um:

1. Dynamische Zeitbereiche - Grafanas Zeitauswahl mit API-Abfragen verbinden

2. Aufträge - Aufträge mit integrierten OEE-Kennzahlen abfragen

3. Antwort-Transformation - Verschachtelte Daten mit JSONata extrahieren und umstrukturieren

4. Stillstände - Maschinenstillstände abfragen

---

Dynamische Zeitbereiche

Fest codierte Daten sind für echte Dashboards nicht praktikabel. Verbinde Queries mit Grafanas Zeitauswahl.

Grafana-Zeitvariablen

Grafana stellt eingebaute Variablen für den ausgewählten Zeitbereich bereit:

Variable	Beschreibung	Beispielwert
${__from}	Startzeit (Millisekunden)	1701388800000
${__to}	Endzeit (Millisekunden)	1701475199999
${__from:date:iso}	Startzeit (ISO-Format)	2024-12-01T00:00:00.000Z
${__to:date:iso}	Endzeit (ISO-Format)	2024-12-01T23:59:59.999Z

Diese Variablen aktualisieren sich automatisch, wenn die Zeitauswahl im Dashboard geändert wird.

---

Aufträge (Production Runs)

Der Production-Runs-Endpunkt liefert nicht nur Auftragsinformationen, sondern auch OEE-Kennzahlen pro Auftrag.

Inhalte eines Auftrags

Jeder Auftrag enthält:

Kategorie	Felder
Basisinformationen	uuid, machine, product, production_order
Zeitangaben	start, end
Mengen	quantity_total, quantity_yield, quantity_scrap
OEE-Kennzahlen	productivity, availability, performance, quality
Geschwindigkeit	average_throughput, maximum_run_speed

Endpunkt

Einstellung	Wert
Method	GET
URL	production-runs
Root selector	$.data

Query-Parameter

Parameter	Beschreibung
machine	Nach Maschinen-UUID filtern
start	Aufträge ab diesem Zeitpunkt (ISO-Format)
end	Aufträge bis zu diesem Zeitpunkt (ISO-Format)
product	Nach Produkt-UUID filtern
product-external-id	Nach externer Produkt-ID filtern

---

Erste zeitgefilterte Query

Erstelle ein Panel, das Aufträge für den ausgewählten Zeitbereich anzeigt.

Schritt 1: Panel erstellen

1. Erstelle ein neues Panel mit Table-Visualisierung

2. Wähle die Infinity Data Source

Schritt 2: Query konfigurieren

Einstellung	Wert
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET

Schritt 3: Zeitgefilterte URL einfügen

Verwende Grafanas Zeitvariablen in den URL-Query-Parametern:

production-runs?machine=141e0927-62b3-4e76-8398-ad82d20f397f&start=${__from:date:iso}&end=${__to:date:iso}

[SCREENSHOT: Infinity query with time variables in URL]

Schritt 4: Root Selector setzen

$.data

Schritt 5: Zeitfilter testen

1. Setze den Dashboard-Zeitbereich auf "Last 7 days"

2. Prüfe, ob das Panel Aufträge für diesen Zeitraum anzeigt

3. Wechsle auf "Last 30 days"

4. Überprüfe, ob mehr Aufträge erscheinen

[SCREENSHOT: Production runs table with time picker]

---

Antwortstruktur verstehen

Die Production-Runs-Antwort enthält verschachtelte OEE-Daten:

{
  "data": [
    {
      "uuid": "abc123...",
      "machine": "141e0927-62b3-4e76-8398-ad82d20f397f",
      "production_order": "PO-2024-001",
      "start": "2024-12-01T08:00:00.000Z",
      "end": "2024-12-01T16:00:00.000Z",
      "average_throughput": 125.5,
      "quantity_total": { "value": 1000, "unit": "kg" },
      "quantity_yield": { "value": 950, "unit": "kg" },
      "quantity_scrap": { "value": 50, "unit": "kg" },
      "productivity": { "score": 0.72, "time_loss": 3600 },
      "availability": { "score": 0.85, "time_loss": 1800 },
      "performance": { "score": 0.90, "time_loss": 1200 },
      "quality": { "score": 0.95, "time_loss": 600 }
    }
  ]
}

OEE-Kennzahlen und Mengen sind verschachtelte Objekte. Mit JSONata lassen sich diese Werte extrahieren.

---

Verschachtelte Werte mit JSONata extrahieren

JSONata ist eine leistungsfähige Abfragesprache zur Transformation von JSON-Daten. Sie bietet mehr Möglichkeiten als JSONPath und ermöglicht es, Daten umzustrukturieren.

Einfache Extraktion

Um OEE-Werte aus Aufträgen zu extrahieren, verwende diesen Root Selector:

$.data.{
  "production_order": production_order,
  "start": start,
  "end": end,
  "productivity": productivity.score,
  "availability": availability.score,
  "performance": performance.score,
  "quality": quality.score
}

Ergebnis:

production_order	start	end	productivity	availability	performance	quality
PO-2024-001	2024-12-01T08:00:00Z	2024-12-01T16:00:00Z	0.72	0.85	0.90	0.95

[SCREENSHOT: Clean production runs table with OEE scores]

JSONata-Grundlagen

Ausdruck	Beschreibung
$.data	Zugriff auf das data-Array
$.data[0]	Erstes Element
field.subfield	Zugriff auf verschachtelte Eigenschaft
{ "name": value }	Neues Objekt erstellen
$map(array, fn)	Jedes Element transformieren

Häufige Muster

Einzelnen Wert extrahieren:

$.data[0].productivity.score

Mengenwerte extrahieren:

$.data.{
  "total": quantity_total.value,
  "yield": quantity_yield.value,
  "scrap": quantity_scrap.value,
  "unit": quantity_total.unit
}

Fehlende Daten behandeln:

$.data.{
  "quality": $exists(quality) ? quality.score : null
}

Werte berechnen:

$.data.{
  "scrap_rate": quantity_scrap.value / quantity_total.value
}

---

Spalten für bessere Darstellung hinzufügen

Statt alles mit JSONata umzustrukturieren, kannst du auch Columns in der Infinity-Query verwenden, um bestimmte Felder auszuwählen.

Schritt 1: Spalten hinzufügen

Scrolle zum Abschnitt Columns und füge hinzu:

Selector	Title	Type
production_order	Order	String
start	Start	Timestamp
end	End	Timestamp
productivity.score	OEE	Number
availability.score	Availability	Number
performance.score	Performance	Number
quality.score	Quality	Number
quantity_yield.value	Yield	Number

[SCREENSHOT: Columns configuration]

Schritt 2: Darstellung formatieren

Unter Field overrides die Formatierung festlegen:

1. Override für Felder mit Muster /score$/ (Regex):

   • Unit: Percent (0.0-1.0)

   • Min: 0, Max: 1

2. Override für das Feld "Yield":

   • Unit: Entsprechend deiner Daten (z. B. kg, m)

---

OEE in Tabellen visualisieren

Gauge-Zellen

Für OEE-Werte bieten Gauge-Zellen eine gute Visualisierung:

1. Öffne Field overrides

2. Füge einen Override für Felder mit Muster /score$/ hinzu

3. Setze Cell type auf Gauge

4. Setze Min auf 0, Max auf 1

5. Füge Schwellenwerte hinzu:

   • Rot: 0

   • Gelb: 0.6

   • Grün: 0.8

[SCREENSHOT: Production runs table with gauge cells]

Farbiger Hintergrund

Alternativ lässt sich ein farbiger Hintergrund verwenden:

1. Setze Cell type auf Colored background

2. Füge dieselben Schwellenwerte hinzu

3. Setze Color mode auf Background (gradient)

---

Stat-Panels für Einzelwerte

Den OEE des letzten Auftrags als Stat-Panel anzeigen:

Schritt 1: Stat-Panel erstellen

1. Neues Panel mit Stat-Visualisierung hinzufügen

2. Infinity-Query für Production Runs konfigurieren

Schritt 2: Einzelwert extrahieren

Mit JSONata den Productivity-Score des letzten Auftrags abrufen:

Root Selector:

$.data[0].productivity.score

Schritt 3: Darstellung konfigurieren

Einstellung	Wert
Unit	Percent (0.0-1.0)
Color mode	Background
Thresholds	Rot < 0.6, Gelb < 0.8, Grün >= 0.8

[SCREENSHOT: OEE stat panel]

---

Stillstände

Maschinenstillstände zur Analyse abfragen.

Endpunkt

Einstellung	Wert
Method	GET
URL	downtimes?machine={uuid}&start=${__from:date:iso}&end=${__to:date:iso}
Root selector	$.data

Query-Parameter

Parameter	Beschreibung
machine	Nach Maschinen-UUID(s) filtern
start	Stillstände ab diesem Zeitpunkt
end	Stillstände bis zu diesem Zeitpunkt

Beispiel: Aktuelle Stillstände

downtimes?machine=141e0927-62b3-4e76-8398-ad82d20f397f&start=${__from:date:iso}&end=${__to:date:iso}

Stillstandsdauer berechnen

Mit JSONata die Dauer in Minuten berechnen:

$.data.{
  "start": start,
  "end": end,
  "duration_minutes": ($toMillis(end) - $toMillis(start)) / 60000
}

---

Aufträge mehrerer Maschinen zusammenführen

Computed Columns verwenden

Beim Abfragen mehrerer Maschinen eine Spalte mit dem Maschinennamen hinzufügen:

Query A (Kiefel):

• URL: production-runs?machine=141e0927-62b3-4e76-8398-ad82d20f397f&start=${__from:date:iso}&end=${__to:date:iso}

Unter Computed columns hinzufügen:

• Selector: "Kiefel" (literaler String in Anführungszeichen)

• Title: Machine

• Type: String

Query B (Macchi):

• URL: production-runs?machine=cc0d2dcb-564b-48cd-a342-71765a536058&start=${__from:date:iso}&end=${__to:date:iso}

Unter Computed columns hinzufügen:

• Selector: "Macchi"

• Title: Machine

Ergebnisse zusammenführen

Füge eine Merge-Transformation hinzu, um beide Queries in einer Tabelle zu vereinen.

[SCREENSHOT: Multi-machine production runs table]

---

Mit Produktdaten verknüpfen

Aufträge enthalten ein product-Feld mit einer UUID, aber nicht den Produktnamen oder die externe ID. Um die externe Produkt-ID (aus deinem ERP/MES) anzuzeigen, musst du die Daten mit dem Products-Endpunkt verknüpfen.

Das Problem

Die Production-Runs-Antwort enthält nur:

{
  "product": "4646d168-a98b-447e-834a-d36dd1f33eb4"
}

Du möchtest aber anzeigen:

Product ID: 6009400032

Lösung: Join-Transformation

Verwende mehrere Queries und Grafanas Join-Transformation.

Schritt 1: Zwei Queries erstellen

Query A (Aufträge):

Einstellung	Wert
URL	production-runs?machine=141e0927-62b3-4e76-8398-ad82d20f397f&start=${__from:date:iso}&end=${__to:date:iso}
Root selector	$.data

Spalten hinzufügen:

Selector	Title	Type
production_order	Order	String
product	product_uuid	String
start	Start	Timestamp
productivity.score	OEE	Number

Query B (Produkte):

Einstellung	Wert
URL	products
Root selector	$.data

Spalten hinzufügen:

Selector	Title	Type
uuid	product_uuid	String
external_id	Product ID	String
name	Product Name	String

Wichtig: Das Join-Feld muss in beiden Queries denselben Spaltennamen haben (product_uuid).

[SCREENSHOT: Two queries configured for join]

Schritt 2: Join-Transformation hinzufügen

1. Wechsle zum Tab Transform

2. Füge die Transformation Join by field hinzu

3. Konfiguriere:

Einstellung	Wert
Mode	OUTER
Field	product_uuid

[SCREENSHOT: Join transformation configuration]

Schritt 3: Mit Organize aufräumen

Füge die Transformation Organize fields hinzu, um:

• Die doppelte Spalte product_uuid auszublenden

• Spalten in der gewünschten Reihenfolge anzuordnen

Ergebnis

Order	Product ID	Product Name	Start	OEE
PO-2024-001	6009400032	Film 50um Clear	2024-12-01T08:00:00Z	72%
PO-2024-002	6009400045	Film 75um Blue	2024-12-01T16:00:00Z	85%

[SCREENSHOT: Final joined table with product information]

Join-Modi

Modus	Beschreibung
INNER	Nur Zeilen mit Übereinstimmungen in beiden Queries
OUTER	Alle Zeilen aus beiden Queries
LEFT	Alle Zeilen der ersten Query, Übereinstimmungen aus der zweiten
RIGHT	Alle Zeilen der zweiten Query, Übereinstimmungen aus der ersten

Für Aufträge + Produkte empfiehlt sich OUTER oder LEFT, damit alle Aufträge erhalten bleiben, auch wenn Produktdaten fehlen.

---

Fehlerbehandlung und Debugging

Häufige Fehler

Fehler	Ursache	Lösung
404 Not Found	Falsche URL oder UUID	Endpunkt und Maschinen-UUID überprüfen
422 Unprocessable	Ungültiges Datumsformat	ISO 8601-Format verwenden
Leere Daten	Keine Daten im Zeitbereich	Zeitbereich erweitern
Verschachtelte Objekte in Tabelle	Fehlende Spaltenextraktion	Columns hinzufügen oder JSONata verwenden

Debugging-Tipps

1. Network Tab prüfen

   • Browser-DevTools öffnen (F12)

   • Zum Tab Network wechseln

   • Die API-Anfrage suchen

   • Request-URL und Antwort prüfen

2. Zuerst mit Table testen

   • Immer mit Table-Visualisierung beginnen

   • Rohdatenstruktur ist leichter erkennbar

   • Erst nach funktionierender Datenabfrage zu anderen Visualisierungen wechseln

3. Root Selector vereinfachen

   • Mit $.data beginnen

   • Datenstruktur überprüfen

   • Dann JSONata-Transformationen hinzufügen

4. Debug-Transformation verwenden

   • Debug-Transformation hinzufügen

   • Zeigt genau, welche Daten Grafana erhält

---

Praktische Übung

Erstelle ein Produktionsübersichts-Dashboard:

1. Auftragstabelle

   • Aufträge der Kiefel-Maschine abfragen

   • Nach Dashboard-Zeitbereich filtern

   • Extrahieren: Auftrag, Start, Ende, OEE-Werte, Yield

   • OEE als Gauge-Zellen darstellen

2. Statistik des letzten Auftrags

   • Vier Stat-Panels: Productivity, Availability, Performance, Quality

   • Aus dem letzten Auftrag mit $.data[0] extrahieren

   • Schwellenwerte für Farbkodierung verwenden

3. Stillstandstabelle

   • Stillstände derselben Maschine und desselben Zeitbereichs abfragen

   • Start, Ende und berechnete Dauer anzeigen

---

Zusammenfassung

Du hast gelernt, Produktionsdaten mit dynamischen Zeitbereichen abzufragen:

• ${__from:date:iso} und ${__to:date:iso} in URL-Parametern verwenden

• Aufträge mit integrierten OEE-Kennzahlen abfragen

• Verschachtelte Werte mit JSONata extrahieren

• OEE mit Gauge-Zellen und Stat-Panels visualisieren

• Stillstände abfragen und analysieren

---

Nächste Schritte

Weiter mit:

• Mit Variablen arbeiten - Dropdowns für Standort- und Maschinenauswahl erstellen

---

Kurzreferenz

Zeitvariablen

Variable	Format	Anwendungsfall
${__from:date:iso}	ISO 8601	API-Zeitparameter
${__to:date:iso}	ISO 8601	API-Zeitparameter
${__from}	Millisekunden	Berechnungen

JSONata-Kurzübersicht

Ausdruck	Ergebnis
$.data	Data-Array
$.data[0]	Erstes Element
field.subfield	Verschachtelter Zugriff
{ "a": x, "b": y }	Neues Objekt
$exists(field)	Prüfen, ob Feld existiert
condition ? a : b	Bedingung
$toMillis(date)	Datum in Millisekunden

Wichtige Endpunkte

Endpunkt	Methode	Beschreibung
production-runs	GET	Aufträge mit OEE
downtimes	GET	Stillstandsaufzeichnungen
machines	GET	Maschinenliste
sites	GET	Standortliste