# 02 ENLYZE API abfragen

In diesem Tutorial lernst du, Produktionsdaten mit dynamischen Zeitbereichen abzufragen, OEE-Kennzahlen zu extrahieren und Daten aus mehreren Queries zu verknüpfen:

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-3b2ba9ea5161e1ee8fc0e188043d4c00c7658258%2Fgrafana-api-queries-hero-01.png?alt=media" alt=""><figcaption></figcaption></figure>

## Was du lernst

* Grafanas Zeitbereich in API-Abfragen verwenden
* Aufträge mit OEE-Kennzahlen abfragen
* Verschachtelte JSON-Werte mit JSONata extrahieren
* Daten mehrerer Maschinen zusammenführen
* Aufträge mit Produktdaten verknüpfen (Join)

## Voraussetzungen

* [Einführung in die ENLYZE API](https://docs.enlyze.com/integrations/grafana/advanced-api/01-introduction) abgeschlossen
* Verständnis von GET-Anfragen und Root Selector `$.data`

***

## Dynamische Zeitbereiche

In der [Einführung](https://docs.enlyze.com/integrations/grafana/advanced-api/01-introduction) hast du feste Endpunkte abgefragt. Für Produktionsdaten brauchst du einen dynamischen Zeitbereich, der sich mit Grafanas Zeitauswahl aktualisiert.

| Variable             | Beschreibung            |
| -------------------- | ----------------------- |
| `${__from:date:iso}` | Startzeit im ISO-Format |
| `${__to:date:iso}`   | Endzeit im ISO-Format   |

Diese Variablen werden automatisch durch den aktuellen Zeitbereich des Dashboards ersetzt.

***

## Aufträge abfragen

Der `production-runs`-Endpunkt liefert Produktionsaufträge inklusive OEE-Kennzahlen.

### Query konfigurieren

1. Erstelle ein neues Panel mit der Visualisierung **Table**
2. Wähle die Data Source **ENLYZE API**
3. Konfiguriere die Query:

| Einstellung | Wert              |
| ----------- | ----------------- |
| Type        | JSON              |
| Parser      | Backend           |
| Source      | URL               |
| Format      | Table             |
| Method      | GET               |
| URL         | `production-runs` |

4. Klappe **Headers, Request params** auf und füge unter **URL Query Params** hinzu:

| Key       | Value                                  |
| --------- | -------------------------------------- |
| `machine` | `141e0927-62b3-4e76-8398-ad82d20f397f` |
| `start`   | `${__from:date:iso}`                   |
| `end`     | `${__to:date:iso}`                     |

5. Setze den **Root selector** auf `$.data`

{% hint style="info" %}
Konfiguriere Query-Parameter immer über die Grafana-Oberfläche unter **Headers, Request params** statt sie direkt in die URL zu schreiben. Das ist übersichtlicher und vermeidet Encoding-Probleme.
{% endhint %}

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-9f9e85b07a51750c089d99c8063bd1268013916c%2Fgrafana-api-raw-response-01.png?alt=media" alt=""><figcaption></figcaption></figure>

Die Tabelle zeigt die rohe API-Antwort. OEE-Kennzahlen wie `productivity`, `availability` und `performance` sind verschachtelte Objekte. Im nächsten Schritt extrahierst du diese Werte.

***

## Verschachtelte Werte mit JSONata extrahieren

JSONata erlaubt es, verschachtelte Werte direkt im Root Selector zu extrahieren und umzustrukturieren. Ersetze `$.data` durch:

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

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-31927117223a90467fe611484008aa7f542c0aad%2Fgrafana-api-runs-jsonata-01.png?alt=media" alt=""><figcaption></figcaption></figure>

Jede Zeile enthält jetzt die extrahierten OEE-Scores und die produzierte Menge (Yield).

### JSONata-Grundlagen

| Ausdruck            | Beschreibung               |
| ------------------- | -------------------------- |
| `$.data`            | Zugriff auf das data-Array |
| `field.subfield`    | Verschachtelte Eigenschaft |
| `{ "name": value }` | Neues Objekt erstellen     |

***

## Spalten konfigurieren (Columns)

Statt JSONata kannst du auch die **Columns**-Funktion der Infinity-Query verwenden. Klappe **Parsing options & Result fields** auf und füge unter **Columns** 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    |

### OEE-Werte farblich hervorheben

Für die OEE-Spalten bieten sich farbige Zellen an. Füge einen **Field override** für Felder mit Regex `/OEE|Availability|Performance|Quality/` hinzu:

* **Unit**: Percent (0.0-1.0)
* **Min**: 0, **Max**: 1
* **Cell type**: Color background
* **Value mappings**: Farbabstufungen von Rot (< 60 %) über Orange und Gelb bis Grün (> 95 %) sowie `null` → "NO DATA" in Grau

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-a5b84a0e9dbd69286db76d7e8f777231174a8095%2Fgrafana-api-oee-table-01.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Bei Maschinen ohne Qualitätsdaten zeigt die Quality-Spalte "NO DATA" an. Der OEE (Productivity) wird in diesem Fall aus Availability und Performance berechnet. Mehr dazu in der [OEE-Dokumentation](https://docs.enlyze.com/konzepte/oee-verstehen/das-konzept-oee).
{% endhint %}

***

## OEE als Stat-Panel

Den OEE des letzten Auftrags kannst du auch als Stat-Panel darstellen:

1. Erstelle ein neues Panel mit **Stat**-Visualisierung
2. Konfiguriere die gleiche `production-runs`-Query mit den Query Params wie oben
3. Setze den Root Selector auf `$.data[0].productivity.score`
4. Unit auf **Percent (0.0-1.0)**, Color mode auf **Background**
5. Thresholds: Rot (Basis), Gelb (0.6), Grün (0.8)

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-4b25175009de2adae242dad4c9aa409ee44b1721%2Fgrafana-api-oee-stat-01.png?alt=media" alt=""><figcaption></figcaption></figure>

Erstelle nach dem gleichen Muster weitere Panels für Availability (`$.data[0].availability.score`), Performance (`$.data[0].performance.score`) und Quality (`$.data[0].quality.score`). Für Quality konfiguriere ein Value Mapping für `null` → "NO DATA", da nicht alle Maschinen Qualitätsdaten liefern.

***

## Aufträge mehrerer Maschinen zusammenführen

Um Aufträge mehrerer Maschinen in einer Tabelle anzuzeigen, konfiguriere zwei Queries mit jeweils einer eigenen Computed Column für den Maschinennamen.

**Query A (Kiefel):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `141e0927-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Unter **Computed columns**: Selector `"Kiefel"`, Title `Machine`

**Query B (Macchi):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `cc0d2dcb-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Unter **Computed columns**: Selector `"Macchi"`, Title `Machine`

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

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-555ac5dbbe983ef39407d0140f450a039253a326%2Fgrafana-api-multi-machine-runs-01.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Mit Produktdaten verknüpfen

Aufträge enthalten nur eine Produkt-UUID. Um den Produktnamen anzuzeigen, verknüpfe die Daten mit dem `products`-Endpunkt.

### Zwei Queries erstellen

**Query A (Aufträge):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `141e0927-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Columns: `production_order` → Order, `product` → product\_uuid, `start` → Start, `productivity.score` → OEE

**Query B (Produkte):**

| Einstellung   | Wert       |
| ------------- | ---------- |
| URL           | `products` |
| Root selector | `$.data`   |

Columns: `uuid` → product\_uuid, `external_id` → Product ID, `name` → Product Name

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

### Join-Transformation

1. Wechsle zum Tab **Transform**
2. Füge **Join by field** hinzu: Mode **INNER**, Field **product\_uuid**
3. Optional: **Organize fields** hinzufügen, um `product_uuid` auszublenden

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-35c3013e69eaa87d9d58ec74777b4a79277b4cea%2Fgrafana-api-join-transform-01.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-fe8df29b297b15e009152f76c59c42965fedb3dd%2Fgrafana-api-joined-table-01.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Stillstände

Maschinenstillstände lassen sich über den `downtimes`-Endpunkt abfragen:

| Einstellung   | Wert                                                                             |
| ------------- | -------------------------------------------------------------------------------- |
| URL           | `downtimes`                                                                      |
| Query Params  | `machine` = `{uuid}`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |
| Root selector | `$.data`                                                                         |

Die API liefert neben Start- und Endzeitpunkt auch den Stillstandsgrund und dessen Kategorie. Nutze **Columns**, um die relevanten Felder zu extrahieren:

| Selector          | Title       | Type      |
| ----------------- | ----------- | --------- |
| `uuid`            | Downtime ID | String    |
| `start`           | Start       | Timestamp |
| `end`             | End         | Timestamp |
| `reason.name`     | Reason      | String    |
| `reason.category` | Category    | String    |

***

## Tipps

* **Immer mit Table testen**: Rohdaten sind in Tabellen leichter zu lesen. Erst nach funktionierender Query zu anderen Visualisierungen wechseln.
* **Query Params nutzen**: Konfiguriere Parameter über die Grafana-Oberfläche statt sie direkt in die URL zu schreiben.
* **Root Selector schrittweise aufbauen**: Mit `$.data` beginnen, Datenstruktur überprüfen, dann JSONata ergänzen.
* **Leere Daten**: Zeitbereich erweitern oder prüfen, ob die Maschine im gewählten Zeitraum lief.

***

## Nächste Schritte

* [**Mit Variablen arbeiten**](https://docs.enlyze.com/integrations/grafana/advanced-api/03-variables) — Dropdowns für Standort- und Maschinenauswahl erstellen