Einführung in die ENLYZE API Data Source

Einführung in die ENLYZE API Data Source für Grafana.

Lernziele

• Verstehen, wann und warum die ENLYZE API Data Source zum Einsatz kommt

• Erste API-Anfrage an die ENLYZE Platform API stellen

• JSON-Antworten mit JSONPath parsen

• API-Daten in Grafana-Panels anzeigen

Voraussetzungen

• Teil 1-3 der Tutorials abgeschlossen (Grafana-Grundkenntnisse)

• Zugang zu Grafana mit beiden konfigurierten ENLYZE Data Sources

---

Überblick

Bisher hast du die ENLYZE Data Source verwendet, um Dashboards zu erstellen. Sie ist einfach und für die meisten Anwendungsfälle ausreichend. Für fortgeschrittene Szenarien brauchst du jedoch die ENLYZE API Data Source (basierend auf dem Infinity Plugin).

ENLYZE Data Source vs. ENLYZE API Data Source

Merkmal	ENLYZE	ENLYZE API
Bedienbarkeit	Point-and-Click	Query-Konfiguration
Zeitreihendaten	Sehr gut	Möglich (mehr Konfiguration nötig)
API-Abfragen	Nicht unterstützt	Volle Kontrolle
Variablen/Dropdowns	Eingeschränkt	Volle Unterstützung
Alerting	Nicht unterstützt	Voraussetzung für Alerts
Benutzerdefinierte Transformationen	Einfach	Fortgeschritten (JSONPath/JSONata)
Lernkurve	Niedrig	Mittel

Wann die ENLYZE API Data Source verwenden

Verwende die ENLYZE API Data Source, wenn du Folgendes brauchst:

1. Dashboard-Variablen - Dynamische Dropdowns für Standort-, Maschinen- und Produktauswahl

2. Alerting - Grafana-Alerts funktionieren ausschließlich mit der ENLYZE API Data Source

3. OEE-/Produktivitätskennzahlen - Der Productivity-Metrics-API-Endpunkt

4. Aufträge und Stillstände - Historische Produktionsdaten

5. Individuelle Datenkombinationen - Daten aus mehreren Endpunkten zusammenführen

---

Die ENLYZE Platform API verstehen

Die ENLYZE API Data Source verbindet sich direkt mit der ENLYZE Platform API. So funktioniert sie.

Base URL

Alle API-Anfragen gehen an:

https://app.enlyze.com/api/v2/

Diese URL ist in deiner Grafana-Instanz bereits vorkonfiguriert.

Authentifizierung

Deine Grafana-Instanz hat die API-Authentifizierung bereits vorkonfiguriert. Du musst keine Tokens oder Zugangsdaten hinzufügen.

Antwortformat

Alle ENLYZE API-Endpunkte liefern paginierte JSON-Antworten:

{
  "data": [
    { "uuid": "...", "name": "Machine 1", ... },
    { "uuid": "...", "name": "Machine 2", ... }
  ],
  "next_cursor": null
}

Wichtige Punkte:

• data - Array mit den eigentlichen Ergebnissen

• next_cursor - Paginierungs-Token (null, wenn keine weiteren Seiten vorhanden)

---

Erste ENLYZE API Query

Erstelle ein Panel, das alle Maschinen über die API auflistet.

Schritt 1: Neues Panel erstellen

1. Erstelle ein neues Dashboard oder öffne ein vorhandenes

2. Klicke auf Add > Visualization

3. Wähle Table als Visualisierungstyp

Schritt 2: ENLYZE API Data Source auswählen

1. Klicke im Query-Editor auf das Data-Source-Dropdown

2. Wähle ENLYZE API (nicht ENLYZE)

   [SCREENSHOT: Data source dropdown showing ENLYZE API selection]

Schritt 3: Query konfigurieren

Konfiguriere folgende Einstellungen:

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

[SCREENSHOT: ENLYZE API query configuration for machines endpoint]

Hinweis: Du musst nur machines eingeben, nicht die vollständige URL. Die Base URL ist bereits konfiguriert.

Schritt 4: Root Selector hinzufügen

Die API liefert Daten innerhalb eines data-Arrays. Um diese zu extrahieren:

1. Suche das Feld Root selector

2. Gib ein: $.data

Dieser JSONPath-Ausdruck weist Grafana an, das data-Array als Quelle zu verwenden.

[SCREENSHOT: Root selector configuration]

Schritt 5: Ergebnisse anzeigen

Klicke auf Refresh oder warte, bis das Panel aktualisiert wird. Du solltest eine Tabelle sehen mit:

uuid	name	site	genesis_date
141e...	Kiefel	a5ea...	2020-08-26
cc0d...	Macchi	a5ea...	2021-03-15
...	...	...	...

[SCREENSHOT: Table showing machines list]

---

JSONPath-Grundlagen

Mit JSONPath navigierst du durch JSON-Daten. Hier die wichtigsten Ausdrücke:

Häufige Selektoren

JSONPath	Beschreibung	Beispielergebnis
$	Root-Element	Gesamte Antwort
$.data	Eigenschaft "data"	Das data-Array
$.data[0]	Erstes Element im Array	Erste Maschine
$.data[*].name	Alle name-Werte	["Kiefel", "Macchi", ...]

Warum $.data?

Die ENLYZE API verpackt Ergebnisse für die Paginierung in einem data-Array. Ohne Root Selector würde Grafana versuchen, die gesamte Antwort einschließlich next_cursor darzustellen.

Ohne Root Selector:

{
  "data": [...],
  "next_cursor": null
}

Mit $.data Root Selector:

[
  { "uuid": "...", "name": "Kiefel", ... },
  { "uuid": "...", "name": "Macchi", ... }
]

---

Standorte abfragen

Füge ein weiteres Panel hinzu, um alle Standorte aufzulisten.

Query-Konfiguration

Einstellung	Wert
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET
URL	sites
Root selector	$.data

Erwartetes Ergebnis

uuid	name
a5ea...	Koln
241a...	Stuttgart

---

Variablen einer Maschine abfragen

Du kannst API-Ergebnisse mit Query-Parametern filtern.

Variablen für eine bestimmte Maschine abrufen

Einstellung	Wert
URL	variables?machine=141e0927-62b3-4e76-8398-ad82d20f397f
Root selector	$.data

Diese Abfrage liefert nur Variablen (Sensoren, Metriken) der Kiefel-Maschine.

Erwartetes Ergebnis

uuid	machine	display_name	data_type	unit
50b8...	141e...	Extruder A Durchsatz	FLOAT	kg/h
1cfd...	141e...	Extruder B Durchsatz	FLOAT	kg/h
...	...	...	...	...

---

Query-Ergebnisse strukturieren

Spalten auswählen

Standardmäßig zeigt Infinity alle Felder an. Um bestimmte Spalten auszuwählen:

1. Scrolle zum Abschnitt Columns

2. Klicke auf Add column

3. Gib den Feld-Selektor (z. B. name) und einen Anzeigenamen ein

Selector	Title
name	Machine Name
uuid	ID

[SCREENSHOT: Column configuration]

Transformationen verwenden

Du kannst auch Grafanas Transformationen nutzen (wie in Teil 3 gelernt):

1. Wechsle zum Tab Transform

2. Füge Organize fields by name hinzu

3. Benenne Spalten um oder blende sie aus

---

POST-Anfragen

Einige API-Endpunkte erfordern POST-Anfragen mit einem Request Body. Das wird im nächsten Tutorial ausführlich behandelt, hier eine Vorschau:

Beispiel: Productivity Metrics

Einstellung	Wert
Method	POST
URL	machines/141e0927-62b3-4e76-8398-ad82d20f397f/productivity-metrics
Body	(siehe unten)

Request Body:

{
  "datetime_ranges": [
    {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-01T23:59:59.999Z"
    }
  ]
}

POST-Anfragen und dynamische Zeiträume werden in Tutorial 4.2 behandelt.

---

Praktische Übung

Erstelle ein Dashboard mit drei Panels:

1. Maschinentabelle - Alle Maschinen mit Name und Standort-UUID auflisten

2. Standorttabelle - Alle Standorte mit Name auflisten

3. Variablentabelle - Variablen der Kiefel-Maschine auflisten

Nutze das Gelernte:

• ENLYZE API Data Source

• JSON-Typ, Backend-Parser

• Root Selector $.data

• Table-Visualisierung

---

Häufige Fehler

"No data" oder leere Ergebnisse

Problem: Panel zeigt "No data"

Lösungen:

1. URL prüfen (nur machines, nicht die vollständige URL)

2. Root Selector $.data überprüfen

3. Sicherstellen, dass der Parser auf "Backend" steht

Rohes JSON statt Tabelle

Problem: Panel zeigt rohen JSON-Text

Lösungen:

1. Format auf "Table" setzen (nicht "Data frame")

2. Root Selector $.data hinzufügen

3. Sicherstellen, dass Type auf "JSON" steht

Authentifizierungsfehler

Problem: 401- oder 403-Fehler

Lösung: Wende dich an deinen ENLYZE-Administrator. Möglicherweise muss das API-Token erneuert werden.

---

Tipps und Best Practices

Backend-Parser verwenden

Setze den Parser für ENLYZE API Queries immer auf Backend. Dadurch werden die Daten auf dem Grafana-Server verarbeitet, was zuverlässiger und sicherer ist.

Einfach anfangen

Beim Erstellen komplexer Queries:

1. Zuerst die einfache Query mit $.data zum Laufen bringen

2. Dann Spaltenauswahl hinzufügen

3. Zuletzt Transformationen ergänzen

URLs im Browser testen

Du kannst API-URLs direkt testen (sofern du ein API-Token hast):

https://app.enlyze.com/api/v2/machines

Das hilft beim Debuggen, bevor du Grafana konfigurierst.

---

Zusammenfassung

Du hast die Grundlagen der ENLYZE API Data Source kennengelernt:

• Wann die ENLYZE API Data Source statt der ENLYZE Data Source verwenden

• GET-Anfragen an API-Endpunkte senden

• JSONPath-Root-Selektoren ($.data) verwenden

• API-Ergebnisse in Tabellen darstellen

---

Nächste Schritte

Weiter mit:

• ENLYZE API abfragen - POST-Anfragen, Produktivitätskennzahlen, fortgeschrittene Queries

---

Kurzreferenz

ENLYZE API Query-Einstellungen

Einstellung	Typischer Wert
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET (oder POST)
Root selector	$.data

Häufige Endpunkte

Endpunkt	Methode	Beschreibung
machines	GET	Alle Maschinen auflisten
sites	GET	Alle Standorte auflisten
variables	GET	Alle Variablen auflisten
variables?machine={uuid}	GET	Variablen einer Maschine
machines/{uuid}/productivity-metrics	POST	OEE-Kennzahlen
production-runs	GET	Aufträge
downtimes	GET	Stillstandsaufzeichnungen

JSONPath-Kurzübersicht

Ausdruck	Beschreibung
$	Root-Element
$.data	Eigenschaft "data"
$.data[0]	Erstes Array-Element
$.data[*].name	Alle "name"-Werte
$.data[?(@.site=="abc")]	Nach Bedingung filtern