Dashboards mit der API erstellen

Alles, was Sie im Control Panel mit Dashboards tun, läuft über die REST-API. Deshalb können Sie es auch per Skript erledigen: ein Dashboard erstellen, es mit Widgets füllen, diese im Raster platzieren und es in andere Konten kopieren. Diese Seite zeigt, wie das geht, und endet mit einer Referenz für jeden Widget-Typ.

Wie jedes Widget aussieht und wie man es verwendet, steht im Benutzerhandbuch zu Dashboards. Alle Felder und Statuscodes finden Sie im Abschnitt Dashboards in Swagger.

Bevor Sie beginnen

Holen Sie sich ein Token wie unter Zugriff auf die API beschrieben und senden Sie es bei jedem Aufruf mit. Die Beispiele unten verwenden diese Variablen:

export YGGIO_URL="staging.yggio.net"
export YGGIO_TOKEN=$(curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"USER","password":"PASS"}' | jq -r .token)

Endpunkte

Alle Pfade beginnen mit https://staging.yggio.net/api.

Operation	Anfrage	Erfolg
Ihre Dashboards auflisten	GET /dashboards	200, Array mit vollständigen Widgets
Ein Dashboard	GET /dashboards/{dashboardId}	200, mit vollständigen Widgets
Ein Dashboard erstellen (oder importieren)	POST /dashboards	201
Name, Kopfzeile oder Layout ändern	PATCH /dashboards/{dashboardId}	200
Ein Dashboard duplizieren	POST /dashboards/{dashboardId}/duplicate	201
Ein Dashboard mit seinen Widgets löschen	DELETE /dashboards/{dashboardId}	204
Ein Widget hinzufügen	POST /dashboards/{dashboardId}/widgets	201, das neue Widget
Die Einstellungen eines Widgets ändern	PUT /dashboards/{dashboardId}/widgets/{widgetId}	201, kein Body
Ein Widget duplizieren	POST /dashboards/{dashboardId}/widgets/{widgetId}/duplicate	201
Ein Widget löschen	DELETE /dashboards/{dashboardId}/widgets/{widgetId}	204

Es gibt keinen Endpunkt, der ein einzelnes Widget für sich liest oder schreibt. Ein Widget gehört immer zu genau einem Dashboard, und Sie erreichen es über dieses Dashboard.

Rollen und Zugriffsrechte

Bei jedem Aufruf laufen zwei Prüfungen.

Ihre Rolle legt fest, welche HTTP-Methoden Sie auf der Ressource dashboard verwenden dürfen. Siehe Rollen.

Rolle	Was sie bei Dashboards erlaubt
Admin	Alles
Editor	GET, PATCH, PUT. Also lesen, Widgets verschieben und in der Größe ändern, Einstellungen und Kopfzeile bearbeiten. Nicht erstellen, duplizieren oder löschen, denn dafür werden POST und DELETE verwendet
Installer, Viewer Basic, Viewer Standard, Viewer Full	Nur GET
Eigene Rolle	Die Methoden, die die Rolle für Dashboard auflistet

Eine Methode, die Ihre Rolle nicht erlaubt, ergibt 403 mit dem Body Forbidden.

Ihre Zugriffsrechte legen fest, welche Dashboards Sie erreichen. Sie brauchen Lesezugriff, um ein Dashboard zu sehen, und Schreibzugriff, um es zu ändern, Widgets hinzuzufügen oder zu entfernen, es zu duplizieren oder zu löschen. Ein Dashboard, das Sie nicht sehen können, ergibt 404. Eines, das Sie sehen, aber nicht schreiben können, ergibt 403. Wenn Sie ein Dashboard erstellen, erhalten Sie vollen Zugriff darauf. Teilen Sie es wie jede andere Ressource, siehe Zugriffsrechte.

Wenn Sie ein Dashboard teilen, teilen Sie nicht die Geräte darauf. Ein Widget zeigt nichts für ein Gerät, auf das der Betrachter keinen Zugriff hat.

Das Dashboard-Objekt

{
  "_id": "66f1c0ffee0000000000d001",
  "name": "Building A",
  "title": "Building A, floor 2",
  "description": "Indoor climate and occupancy",
  "headerSettings": {"titleFontSize": 32, "align": "left"},
  "widgets": [
    {
      "_id": "66f1c0ffee0000000000a001",
      "x": 0, "y": 0, "width": 3, "height": 4,
      "template": "deviceValue",
      "settings": {"deviceId": "...", "field": "temperature", "...": "..."}
    }
  ]
}

Feld	Regeln
name	Erforderlich, höchstens 50 Zeichen. Wird in der Dashboard-Auswahl angezeigt
title	Optional, höchstens 100 Zeichen. Der Text der Kopfzeile auf dem Dashboard
description	Optional, höchstens 200 Zeichen. Der Text der Unterzeile
headerSettings	Optional, siehe unten
widgets	Die Widgets mit ihrem Platz im Raster

headerSettings enthält den Stil der Kopfzeile. Alle Felder sind optional:

Feld	Typ
titleFontSize	Zahl, 10 bis 72
titleFontWeight	String
titleColor	String, höchstens 50 Zeichen
descriptionFontSize	Zahl, 8 bis 36
descriptionColor	String, höchstens 50 Zeichen
fontFamily	String, höchstens 100 Zeichen
align	left, center oder right

Widgets und das Raster

Ein Widget besteht aus zwei Teilen:

• Wo es ist. x, y, width und height werden im Dashboard gespeichert.
• Was es ist. template (der Widget-Typ) und settings werden im Widget selbst gespeichert.

GET führt beides zusammen, sodass jedes Widget in der Antwort alle sechs Felder und seine _id hat. Antworten auf POST und PATCH am Dashboard enthalten nur den Platz im Raster (_id, x, y, width, height).

Das Control Panel zeichnet das Raster 24 Spalten breit, mit 25 px hohen Zeilen und 10 px Abstand zwischen Widgets. x und width zählen Spalten, y und height zählen Zeilen, und x: 0, y: 0 ist oben links. Halten Sie x + width bei 24 oder weniger. Das Raster schiebt Widgets nach oben zusammen, sodass eine Lücke über einem Widget verschwindet, wenn das Dashboard angezeigt wird.

Jeder Widget-Typ hat im Control Panel eine Mindestgröße. Eine kleinere Größe wird gespeichert, aber das Raster vergrößert das Widget auf sein Minimum, wenn Sie das Layout bearbeiten. Die Größen stehen in der Widget-Referenz.

Ein Dashboard erstellen

Nur name ist erforderlich.

curl -sS -X POST "https://$YGGIO_URL/api/dashboards" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Building A", "title": "Building A, floor 2"}'

Die Antwort ist das neue Dashboard mit seiner _id.

Ein Dashboard mit seinen Widgets erstellen (Import)

POST /dashboards nimmt auch ein Array widgets an. Jeder Eintrag hat x, y, width, height, template und settings, aber keine _id. Alle Widgets werden in einem Aufruf erstellt und platziert.

{
  "name": "Building A",
  "widgets": [
    {
      "x": 0, "y": 0, "width": 7, "height": 2,
      "template": "text",
      "settings": {"text": "Floor 2", "alignment": "left", "color": "#000000",
                   "fontSize": "xl", "decoration": "none"}
    },
    {
      "x": 0, "y": 2, "width": 3, "height": 4,
      "template": "resourceCount",
      "settings": {"resource": "devices"}
    }
  ]
}

So funktioniert Import dashboard im Control Panel. Der Export-String aus Export dashboard ist die GET-Antwort für dieses Dashboard, als JSON in Base64 kodiert. Dekodieren Sie ihn und senden Sie ihn an POST /dashboards, um ein Dashboard in ein anderes Konto zu kopieren. Die _id-Felder darin werden ignoriert.

Zwei Dinge sollten Sie vorher prüfen:

• Ids von Geräten, Bildern, Regeln und Dashboards in den Einstellungen werden unverändert kopiert. In einem anderen Konto zeigen sie meist ins Leere. Passen Sie sie also vor dem Import an oder korrigieren Sie die Widgets danach.
• Ein Widget, das als _broken markiert ist (siehe Defekte Widgets), besteht die Prüfung nicht und stoppt den gesamten Import. Entfernen Sie es oder korrigieren Sie vorher seine Einstellungen.

Ein Widget hinzufügen

Senden Sie width, height, template und settings. Die API setzt das Widget auf x: 0, y: 99, also unten auf das Dashboard, unter die anderen.

curl -sS -X POST "https://$YGGIO_URL/api/dashboards/$DASHBOARD_ID/widgets" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "width": 3, "height": 4,
    "template": "deviceValue",
    "settings": {
      "deviceId": "'"$DEVICE_ID"'", "field": "temperature",
      "display": "text", "color": "blue",
      "shouldShowHeading": true, "shouldShowSubheading": false
    }
  }'

Die Antwort ist das gespeicherte Widget, {"_id": ..., "template": ..., "settings": ...}, mit allen Standardwerten ausgefüllt. Um es woanders zu platzieren, verschieben Sie es.

Die Einstellungen eines Widgets ändern

PUT ersetzt das ganze Widget: Senden Sie template und das vollständige Objekt settings, nicht nur die Felder, die Sie ändern. Ein Feld, das Sie weglassen, fällt auf seinen Standardwert zurück, oder der Aufruf schlägt fehl, wenn es erforderlich ist. Am einfachsten nehmen Sie das Widget aus GET, ändern es und senden es zurück.

curl -sS -X PUT "https://$YGGIO_URL/api/dashboards/$DASHBOARD_ID/widgets/$WIDGET_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "resourceCount", "settings": {"resource": "locations"}}'

• template muss dasselbe sein wie vorher. Eine Änderung ergibt 403 Cannot change widget template. Um den Typ zu wechseln, löschen Sie das Widget und fügen Sie ein neues hinzu.
• x, y, width und height werden hier nicht gelesen. Verwenden Sie PATCH am Dashboard.
• Die Antwort ist 201 mit leerem Body. Lesen Sie das Dashboard erneut, um das Ergebnis zu sehen.

Widgets verschieben und skalieren

Das Layout liegt im Dashboard. Senden Sie PATCH /dashboards/{dashboardId} mit einem Array widgets, das jedes Widget auf dem Dashboard auflistet, jeweils mit _id, x, y, width und height. Genau das sendet das Control Panel, wenn Sie im Bearbeitungsmodus Save drücken.

curl -sS -X PATCH "https://$YGGIO_URL/api/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [
      {"_id": "66f1c0ffee0000000000a001", "x": 0, "y": 0, "width": 6, "height": 4},
      {"_id": "66f1c0ffee0000000000a002", "x": 6, "y": 0, "width": 18, "height": 14}
    ]
  }'

• Stimmt die Anzahl der Widgets nicht mit dem Dashboard überein, schlägt der Aufruf mit 422 All existing widgets must be provided fehl. Eine _id, die nicht auf dem Dashboard ist, ergibt 404.
• PATCH kann keine Widgets hinzufügen oder entfernen. Verwenden Sie dafür die Widget-Endpunkte.
• template und settings in diesem Array werden ignoriert.

Derselbe PATCH ändert name, title, description und headerSettings. Senden Sie nur die Felder, die Sie ändern. Jedes andere Feld auf oberster Ebene ergibt 422.

{"title": "Building A", "headerSettings": {"align": "center", "titleColor": "#1f2937"}}

Duplizieren

Was	Anfrage	Ergebnis
Ein Widget	POST /dashboards/{dashboardId}/widgets/{widgetId}/duplicate	Eine Kopie mit denselben Einstellungen sowie derselben Größe und Position, auf demselben Dashboard. Die Antwort enthält ihre _id
Ein Dashboard	POST /dashboards/{dashboardId}/duplicate	Ein neues Dashboard mit dem Namen <name> (copy), mit einer Kopie jedes Widgets im selben Layout

Beides erfordert Schreibzugriff auf das Quell-Dashboard. Ein dupliziertes Dashboard behält title, description und headerSettings nicht. Setzen Sie sie bei Bedarf mit PATCH neu.

Die Widget-Kopie erhält dieselbe Position wie das Original, deshalb zeigt das Raster eines unter dem anderen an. Verschieben Sie sie mit PATCH.

Löschen

• DELETE /dashboards/{dashboardId}/widgets/{widgetId} entfernt das Widget vom Dashboard und löscht es.
• DELETE /dashboards/{dashboardId} löscht das Dashboard, alle seine Widgets und seine Zugriffsrechte.

Beides lässt sich nicht rückgängig machen.

Standard-Dashboard

Set as default dashboard im Control Panel ist nicht Teil der REST-API. Das Control Panel speichert die Auswahl in seinem eigenen Backend unter /control-panel-v2-backend/default-dashboards, eine Auswahl je Benutzer. Dieser Dienst ist nicht in Swagger und kann sich ohne Ankündigung ändern, bauen Sie also nicht darauf auf. Jeder Benutzer wählt sein eigenes Standard-Dashboard im Control Panel.

Defekte Widgets

GET schlägt nicht fehl, wenn ein Widget nicht mehr den Regeln seiner Vorlage entspricht, zum Beispiel ein Widget, das von einer älteren Version gespeichert oder direkt in der Datenbank geändert wurde. Stattdessen kommt dieses Widget so zurück:

{
  "_id": "66f1c0ffee0000000000a003",
  "x": 0, "y": 6, "width": 8, "height": 8,
  "template": "floorPlan",
  "settings": {"...": "the stored settings, unchanged"},
  "_broken": true,
  "error": "settings.name: String must contain at least 1 character(s)"
}

• _broken: true markiert das Widget. error sagt, welche Einstellungen die Prüfung nicht bestanden haben und warum.
• Ein Widget, dessen gespeicherte Daten fehlen, kommt mit template: "unknown" und error: "Widget not found" zurück.
• Der Rest des Dashboards ist in Ordnung. Das Control Panel zeigt an der Stelle des Widgets einen Fehlerkasten.
• Zur Reparatur senden Sie per PUT gültige Einstellungen für dieselbe Vorlage, oder Sie löschen das Widget.
• Entfernen Sie defekte Widgets, bevor Sie ein Dashboard zurück an POST /dashboards senden.

Fehler

Status	Typische Ursache
401	Token fehlt, ist ungültig oder abgelaufen
403	Ihre Rolle erlaubt die Methode nicht (Body Forbidden), kein Schreibzugriff auf das Dashboard oder ein geändertes template
404	Das Dashboard existiert nicht oder Sie können es nicht sehen, oder das Widget ist nicht auf diesem Dashboard
422	Der Body besteht die Prüfung nicht. Die Meldung beginnt mit ERR - und nennt das erste Feld, das fehlgeschlagen ist, und den Grund

Widget-Referenz

Ein Abschnitt je Widget-Typ. Jeder listet die Einstellungen auf, die Sie senden müssen. Einstellungen mit Standardwert können Sie weglassen, dann wird der Standardwert gespeichert. Die vollständige Liste der optionalen Einstellungen steht in Swagger.

Für alle Typen gilt:

• Unbekannte Einstellungen schlagen fehl. Die meisten Typen lehnen eine Einstellung, die sie nicht kennen, mit 422 ab. image und floorPlan verwerfen unbekannte Einstellungen ohne Fehler.
• Ids werden nicht geprüft. Die API prüft nicht, ob eine deviceId, imageId, ruleV2Id oder targetDashboardId existiert oder ob Sie sie erreichen können. Eine falsche Id wird gespeichert, und das Widget zeigt nichts.
• Welche Ids. deviceId ist die _id des Geräts aus GET /api/iotnodes. field ist der Pfad zu einem Wert auf dem Gerät, zum Beispiel temperature oder contextMap.room. Für Diagramme listet GET /api/iotnodes/{_id}/stats/fields die Felder auf, die eine Historie haben. Bilder kommen aus POST /api/images (siehe Image).
• Farben sind Strings. Das Control Panel verwendet Farbnamen wie blue und Hex-Werte wie #2169a8.
• Schwellenwerte färben einen Wert nach Bereich: eine Liste von {"value": 25, "color": "red"}, mit einem optionalen operator (gt, gte, eq, lte, lt) bei den Typen, die ihn unterstützen.

Vorlage	Widget	Benötigt Ids von	Standardgröße (min)
deviceValue	Device Value	Einem Gerät	3 x 4 (3 x 4)
deviceChart	Device Chart	Einem Gerät	8 x 8 (4 x 5)
multiDeviceChart	Multi-Device Chart	Geräten	18 x 14 (6 x 6)
multiDeviceValue	Multi-Device Value	Geräten	8 x 8 (3 x 3)
dataTable	Data Table	Geräten	8 x 12 (6 x 6)
equalizer	Equalizer	Geräten	6 x 6 (2 x 3)
swimlane	Swimlane	Geräten	8 x 8 (3 x 3)
pieChart	Pie Chart	Geräten	6 x 8 (3 x 3)
geomap	Geomap	Geräten	8 x 8 (3 x 3)
floorPlan	Floor Plan	Einem Bild, Geräten	10 x 12 (6 x 4)
map	Map	Optional: einem Bild, einer Kartenansicht	16 x 14 (4 x 3)
commandButtons	Command Buttons	Regeln (Rule v2)	4 x 4 (2 x 2)
navigation	Navigation	Einem Dashboard	4 x 2 (3 x 2)
resourceCount	Resource Count	Keine	4 x 4 (3 x 4)
logs	Logs	Keine	14 x 14 (6 x 6)
text	Text	Keine	7 x 2 (3 x 2)
image	Image	Einem Bild	6 x 8 (2 x 2)

Größen sind Breite x Höhe in Rastereinheiten.

deviceValue

Ein aktueller Wert eines Geräts, als Text, Kreis, Balken oder Tacho. Benutzerhandbuch: Device Value.

Erforderlich	Werte
deviceId	_id des Geräts
field	Feldpfad, nicht leer
display	text, circle, bar oder gauge
color	Farbe
shouldShowHeading	Boolean
shouldShowSubheading	Boolean

Nützliche optionale Einstellungen: customHeading, customSubheading, unit, minValue, maxValue, thresholds, barDirection (horizontal oder vertical), showSparkline (Standard false).

{
  "width": 3, "height": 4,
  "template": "deviceValue",
  "settings": {
    "deviceId": "DEVICE_ID", "field": "temperature", "display": "gauge",
    "color": "blue", "minValue": 0, "maxValue": 40,
    "shouldShowHeading": true, "shouldShowSubheading": false
  }
}

deviceChart

Ein Feld eines Geräts über die Zeit, als Linie. Benutzerhandbuch: Device Chart.

Erforderlich	Werte
deviceId	_id des Geräts
field	Feldpfad, nicht leer
timePeriod	fiftenMinutes, thirtyMinutes, hour, threeHours, sixHours, twelveHours, day, week, month, threeMonths, sixMonths, year oder custom
resolution	full, oneMinute, fiveMinutes, fifteenMinutes, thirtyMinutes, hour, threeHours, sixHours, twelveHours, day, week, month oder custom
curveType	step, linear oder monotone
yAxisRange	auto oder fromZero
calculation	mean, timeWeightedMean, min, max, first, last, count, sum oder difference
shouldShowHeading	Boolean
shouldShowSubheading	Boolean

Beachten Sie die Schreibweise fiftenMinutes bei timePeriod. So lautet der gespeicherte Wert. Mit timePeriod: custom setzen Sie customFromTime und customToTime. Mit resolution: custom setzen Sie customResolution.

{
  "width": 8, "height": 8,
  "template": "deviceChart",
  "settings": {
    "deviceId": "DEVICE_ID", "field": "temperature",
    "timePeriod": "day", "resolution": "hour", "curveType": "monotone",
    "yAxisRange": "auto", "calculation": "mean",
    "shouldShowHeading": true, "shouldShowSubheading": false
  }
}

multiDeviceChart

Mehrere Geräte und Felder in einem Diagramm, als Linien, Balken oder gestapelte Balken. Benutzerhandbuch: Multi-Device Chart.

Erforderlich	Werte
deviceFieldPairs	Mindestens ein {"deviceId": ..., "field": ...}
timePeriod, resolution, curveType, yAxisRange, calculation	Wie bei deviceChart
shouldShowHeading	Boolean
shouldShowLegend	Boolean

chartType ist line (Standard, wenn weggelassen), area, bar oder stackedBar.

{
  "width": 18, "height": 14,
  "template": "multiDeviceChart",
  "settings": {
    "deviceFieldPairs": [
      {"deviceId": "DEVICE_ID_1", "field": "temperature"},
      {"deviceId": "DEVICE_ID_2", "field": "temperature"}
    ],
    "timePeriod": "week", "resolution": "day", "curveType": "linear",
    "yAxisRange": "auto", "calculation": "mean", "chartType": "bar",
    "shouldShowHeading": true, "shouldShowLegend": true
  }
}

multiDeviceValue

Aktuelle Werte mehrerer Geräte in einem Raster aus Kacheln. Benutzerhandbuch: Multi-Device Value.

Erforderlich	Werte
items	Mindestens ein {"deviceId": ..., "field": ...}. Jeder Eintrag kann außerdem label, unit, color und thresholds haben

Standardwerte: columns 3 (1 bis 6), colorMode value (oder background), shouldShowHeading true.

{
  "width": 8, "height": 8,
  "template": "multiDeviceValue",
  "settings": {
    "items": [
      {"deviceId": "DEVICE_ID_1", "field": "temperature", "unit": "°C"},
      {"deviceId": "DEVICE_ID_2", "field": "humidity", "unit": "%"}
    ],
    "columns": 2
  }
}

dataTable

Eine Tabelle mit einer Zeile je Gerät und einer Spalte je Feld. Benutzerhandbuch: Data Table.

Erforderlich	Werte
devices	Mindestens ein {"deviceId": ..., "fields": [...]}, jeweils mit mindestens einem Feld
shouldShowHeading	Boolean

columnConfigs gestaltet eine Spalte, mit dem Feld als Schlüssel: field (erforderlich, gleich dem Schlüssel), displayName, displayMode (text oder barGauge), thresholds, unit, min, max. showExportButton ist standardmäßig true.

{
  "width": 8, "height": 12,
  "template": "dataTable",
  "settings": {
    "devices": [
      {"deviceId": "DEVICE_ID_1", "fields": ["temperature", "humidity"]},
      {"deviceId": "DEVICE_ID_2", "fields": ["temperature", "humidity"]}
    ],
    "shouldShowHeading": true,
    "columnConfigs": {"temperature": {"field": "temperature", "displayName": "Temp", "unit": "°C"}}
  }
}

equalizer

Aktuelle Werte als senkrechte Balken auf einer gemeinsamen Skala. Benutzerhandbuch: Equalizer.

Erforderlich	Werte
items	Mindestens ein {"deviceId": ..., "field": ...}, in derselben Form wie bei multiDeviceValue

minValue und maxValue legen die Skala fest. Lassen Sie sie weg, um nach den aktuellen Werten zu skalieren.

{
  "width": 6, "height": 6,
  "template": "equalizer",
  "settings": {
    "items": [
      {"deviceId": "DEVICE_ID_1", "field": "passengers", "label": "Train 1"},
      {"deviceId": "DEVICE_ID_2", "field": "passengers", "label": "Train 2"}
    ],
    "minValue": 0, "maxValue": 300
  }
}

swimlane

Live-Werte, die je Signal in einer eigenen Spur laufen. Nach dem Schließen der Seite wird nichts behalten. Benutzerhandbuch: Swimlane.

Erforderlich	Werte
signals	Mindestens ein {"deviceId": ..., "field": ...}, jeweils mit optionalem label, unit, color

windowSeconds ist das sichtbare Zeitfenster, 10 bis 3600, Standard 60.

{
  "width": 8, "height": 8,
  "template": "swimlane",
  "settings": {
    "signals": [{"deviceId": "DEVICE_ID", "field": "power", "unit": "W"}],
    "windowSeconds": 120
  }
}

pieChart

Ein Feld über mehrere Geräte, jedes Segment der Anteil eines Geräts an der Summe. Benutzerhandbuch: Pie Chart.

Erforderlich	Werte
field	Feldpfad, nicht leer
devices	Mindestens ein {"deviceId": ...}, jeweils mit optionalem alias

{
  "width": 6, "height": 8,
  "template": "pieChart",
  "settings": {
    "field": "passengers",
    "devices": [{"deviceId": "DEVICE_ID_1", "alias": "Train 1"}, {"deviceId": "DEVICE_ID_2"}]
  }
}

geomap

Wo Geräte gewesen sind, jedes mit einer Spur auf der Karte. Benutzerhandbuch: Geomap.

Erforderlich	Werte
devices	Mindestens ein {"deviceId": ...}, jeweils mit optionalem alias

trailLength ist die Anzahl der Punkte, die je Gerät behalten werden, 0 bis 200, Standard 20. tileLayer ist standardmäßig street.

{
  "width": 8, "height": 8,
  "template": "geomap",
  "settings": {"devices": [{"deviceId": "DEVICE_ID"}], "trailLength": 50}
}

floorPlan

Gerätemarkierungen auf einem Hintergrundbild. Benutzerhandbuch: Floor Plan.

Erforderlich	Werte
imageId	_id des Bildes, siehe Image zum Hochladen
name	1 bis 30 Zeichen
devices	Liste von {"deviceId": ..., "x": ..., "y": ...}. x und y können null sein für ein Gerät, das noch nicht platziert ist. Darf leer sein
deviceValues	Liste von {"field": ..., "thresholds": [...], "isStarred": ...}, die Werte, die für jedes Gerät angezeigt werden. Darf leer sein
deviceMarkerType	circle, ring, dot, square oder seat
shouldSnapToGrid	Boolean
gridCellSize	Ganze Zahl, 1 oder mehr, oder null

x und y der Markierungen sind Positionen auf dem Bild. Markierungen lassen sich im Control Panel leichter platzieren: Erstellen Sie das Widget mit einer leeren Liste devices oder mit null-Positionen und ziehen Sie die Markierungen dort an ihren Platz.

{
  "width": 10, "height": 12,
  "template": "floorPlan",
  "settings": {
    "imageId": "IMAGE_ID", "name": "Floor 2",
    "devices": [{"deviceId": "DEVICE_ID", "x": null, "y": null}],
    "deviceValues": [{"field": "temperature", "thresholds": [], "isStarred": true}],
    "deviceMarkerType": "circle",
    "shouldSnapToGrid": false, "gridCellSize": null
  }
}

map

Geräte auf einer Karte, mit optionaler gespeicherter Kartenansicht, Overlay-Bild oder Geofences. Benutzerhandbuch: Map.

Nichts ist erforderlich. {} ergibt eine Karte Ihrer Geräte.

Optional	Werte
viewId	Id einer gespeicherten Kartenansicht. Kartenansichten werden vom Control Panel gespeichert, nicht von der REST-API, wählen Sie also dort eine aus
imageId	_id eines Overlay-Bildes
createGeofenceEnabled	Boolean

{"width": 16, "height": 14, "template": "map", "settings": {}}

commandButtons

Schaltflächen, die eine Regel auslösen. Benutzerhandbuch: Command Button.

Erforderlich	Werte
buttons	Mindestens eine Schaltfläche, jeweils mit ruleV2Id, triggerNodeId und label

• ruleV2Id ist die _id der Regel aus GET /api/rules-v2.
• triggerNodeId ist die id eines Knotens in definition.nodes dieser Regel mit type: "trigger" und config.resourceType: "button". Nur Regeln mit einem solchen Knoten können verwendet werden.
• Jede Schaltfläche kann außerdem icon, color (Standard blue), iconOnly und textAlign haben.

Ein Druck auf die Schaltfläche ruft POST /api/rules-v2/{ruleV2Id}/execute für diesen Trigger auf.

{
  "width": 4, "height": 4,
  "template": "commandButtons",
  "settings": {
    "buttons": [
      {"ruleV2Id": "RULE_ID", "triggerNodeId": "TRIGGER_NODE_ID", "label": "Lights on", "color": "green"}
    ]
  }
}

navigation

Eine Schaltfläche, die ein anderes Dashboard öffnet. Benutzerhandbuch: Navigation.

Erforderlich	Werte
targetDashboardId	_id des Dashboards, das geöffnet werden soll

Optional: largeText, smallText, icon, buttonStyle (filled, outline oder plain), alignment.

{
  "width": 4, "height": 2,
  "template": "navigation",
  "settings": {"targetDashboardId": "OTHER_DASHBOARD_ID", "largeText": "Floor 3"}
}

resourceCount

Wie viele Ressourcen einer Art Sie haben. Benutzerhandbuch: Resource Count.

Erforderlich	Werte
resource	devices, locations, organizations, apps oder rules

{"width": 4, "height": 4, "template": "resourceCount", "settings": {"resource": "devices"}}

logs

Die neuesten Logeinträge, gefiltert. Benutzerhandbuch: Logs.

Nichts ist erforderlich. {} zeigt Geräte-Logs.

Optional	Werte
resourceType	device (Standard), connector, userGroup, organization oder ruleV2
type	Liste aus error, warning, info, verbose, debug
priority	Liste aus severe, high, medium, low
category	update, command, status, access, analytics, rule oder system
timeRange	Zum Beispiel {"start": {"type": "relative", "amount": 24, "unit": "hours"}, "end": {"type": "now"}}
title	String

{
  "width": 14, "height": 14,
  "template": "logs",
  "settings": {"type": ["error", "warning"], "priority": ["severe", "high"]}
}

text

Freier Text. Benutzerhandbuch: Text.

Erforderlich	Werte
text	Nicht leer
alignment	left, center oder right
color	Farbe
fontSize	xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl oder 6xl
decoration	none, underline, overline oder line-through

Optional mit Standardwerten: bold, italic, fontFamily, backgroundColor, verticalAlignment, opacity (10 bis 100).

{
  "width": 7, "height": 2,
  "template": "text",
  "settings": {"text": "Floor 2", "alignment": "left", "color": "#000000",
               "fontSize": "2xl", "decoration": "none", "bold": true}
}

image

Ein Bild, etwa ein Logo oder ein Foto. Benutzerhandbuch: Image.

Erforderlich	Werte
imageId	_id des Bildes
imageSize	small, medium oder large
shape	none, rounded oder full
background	no-background oder background
horizontalAlignment	left, center oder right
verticalAlignment	upp, center oder low

Laden Sie das Bild zuerst hoch. Das geschieht als Multipart-Formular mit der Datei in image, einem name (3 bis 256 Zeichen) und einer category (hier widget, floorPlan für einen Grundriss, mapOverlay für eine Karte). Die _id in der Antwort ist die imageId.

curl -sS -X POST "https://$YGGIO_URL/api/images" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -F "image=@logo.png" -F "name=company-logo" -F "category=widget"

{
  "width": 6, "height": 8,
  "template": "image",
  "settings": {
    "imageId": "IMAGE_ID", "imageSize": "medium", "shape": "none",
    "background": "no-background", "horizontalAlignment": "center", "verticalAlignment": "center"
  }
}

Siehe auch

• Zugriff auf die API - Tokens, curl und Postman.
• Benutzerhandbuch zu Dashboards - jedes Widget, mit Bildern.
• Rollen und Zugriffsrechte.
• Swagger - die vollständige Referenz der REST-API.