SOT Learning Portal

Sending measured values

Measured values are values that a device measures continuously, for example a temperature or a rotation speed. They are shown in the measurement chart and evaluated by rules.

Prerequisites

  • The device exists in the configuration with a Technical ID, for example cnc1-1.

  • The measuring points exist and are assigned to the device or its device type, for example temperature and rotation-speed.

  • A technical client with the permission measurements:write. See Authentication.

Request

POST /data-ingest/api/v1/tenants/{tenantId}/ingest HTTP/1.1
Host: <sot-host>
Authorization: Bearer <access token>
Content-Type: application/json
X-Message-Type: measurement
X-Api-Version: 1.0
{
  "reference": {
    "identifier": "cnc1-1",
    "type": 0
  },
  "measurementTimeSeries": [
    {
      "name": "temperature",
      "firstSampleTimestamp": "2026-10-16T10:00:00Z",
      "timeOffsets": [0, 1000, 2000],
      "values": [47.2, 47.5, 48.1],
      "measurementUnit": "°C",
      "measurementType": 0
    },
    {
      "name": "rotation-speed",
      "firstSampleTimestamp": "2026-10-16T10:00:00Z",
      "timeOffsets": [0, 1000, 2000],
      "values": [11980, 12010, 12005],
      "measurementUnit": "rpm"
    }
  ]
}

The service answers with 202 Accepted. A few seconds later, the values are shown in the measurement chart of the device.

Message format

Field Required Description

reference.identifier

yes

Technical ID of the device. Maximum 80 characters.

reference.type

yes

Type of the reference. Use 0 (device). Other values: -1 unknown, 1 facility, 2 tool, 3 geo location.

part

no

Part that was processed while the values were measured: identifier (part ID), typeNumber (part type) and optionally partResult and additionalData.

measurementTimeSeries

yes

1 to 50 time series per request.

measurementTimeSeries[].name

yes

Name of the measuring point. Must match the name in the configuration. Maximum 128 characters.

measurementTimeSeries[].firstSampleTimestamp

yes

Time of the first value in UTC, ISO 8601, for example 2026-10-16T10:00:00Z.

measurementTimeSeries[].timeOffsets

yes

Time of every value in milliseconds after firstSampleTimestamp. 1 to 200 entries.

measurementTimeSeries[].values

yes

Values, one per time offset. timeOffsets and values must have the same length. null values are skipped.

measurementTimeSeries[].measurementUnit

no

Unit, for example °C. Maximum 32 characters.

measurementTimeSeries[].measurementType

no

0 absolute values, 1 delta values.

measurementTimeSeries[].constantLimits

no

Limits that apply to all values: target, lowerWarn, lowerError, upperWarn, upperError. Set type to constantLimits.

measurementTimeSeries[].seriesLimits

no

Limits per value. Every array has the same length as values. Set type to seriesLimits. Cannot be combined with constantLimits.

Recommendations

  • Send values in batches instead of one request per value, for example all values of one second or of a few seconds in one request.

  • Use the time of the measurement as firstSampleTimestamp, not the time of sending.

  • Keep the device and its measuring points in the configuration up to date before you send data for new measuring points.

  • If you receive 429 or 503, wait for the time in the Retry-After header and send the request again.

Verifying the result

  1. In the menu, click Devices and open the device.

  2. Check that the Measurement Chart shows the new values. See Measured values.

If the values are not shown, check that:

  • reference.identifier matches the Technical ID of the device exactly,

  • name matches the Name of a measuring point of the device exactly,

  • the timestamps are in the selected time range of the chart.

Messwerte senden

Messwerte sind Werte, die ein Gerät kontinuierlich misst, zum Beispiel eine Temperatur oder eine Drehzahl. Sie erscheinen im Messwerte Diagramm und werden von Regeln ausgewertet.

Voraussetzungen

  • Das Gerät ist in der Konfiguration angelegt und hat eine Technische ID (Technical ID), zum Beispiel cnc1-1.

  • Die Messpunkte sind angelegt und dem Gerät oder seinem Gerätetyp zugeordnet, zum Beispiel temperature und rotation-speed.

  • Ein technischer Client mit der Berechtigung measurements:write. Siehe Authentifizierung.

Anfrage

POST /data-ingest/api/v1/tenants/{tenantId}/ingest HTTP/1.1
Host: <sot-host>
Authorization: Bearer <access token>
Content-Type: application/json
X-Message-Type: measurement
X-Api-Version: 1.0
{
  "reference": {
    "identifier": "cnc1-1",
    "type": 0
  },
  "measurementTimeSeries": [
    {
      "name": "temperature",
      "firstSampleTimestamp": "2026-10-16T10:00:00Z",
      "timeOffsets": [0, 1000, 2000],
      "values": [47.2, 47.5, 48.1],
      "measurementUnit": "°C",
      "measurementType": 0
    },
    {
      "name": "rotation-speed",
      "firstSampleTimestamp": "2026-10-16T10:00:00Z",
      "timeOffsets": [0, 1000, 2000],
      "values": [11980, 12010, 12005],
      "measurementUnit": "rpm"
    }
  ]
}

Der Dienst antwortet mit 202 Accepted. Wenige Sekunden später zeigt das Messwerte Diagramm des Geräts die Werte an.

Nachrichtenformat

Feld Pflicht Beschreibung

reference.identifier

ja

Technische ID des Geräts. Maximal 80 Zeichen.

reference.type

ja

Typ der Referenz. 0 (Gerät) verwenden. Weitere Werte: -1 unbekannt, 1 Anlage, 2 Werkzeug, 3 Geoposition.

part

nein

Teil, das während der Messung bearbeitet wurde: identifier (Teile-ID), typeNumber (Teiletyp) und optional partResult und additionalData.

measurementTimeSeries

ja

1 bis 50 Zeitreihen je Anfrage.

measurementTimeSeries[].name

ja

Name des Messpunkts. Muss mit dem Namen in der Konfiguration übereinstimmen. Maximal 128 Zeichen.

measurementTimeSeries[].firstSampleTimestamp

ja

Zeitpunkt des ersten Werts in UTC, ISO 8601, zum Beispiel 2026-10-16T10:00:00Z.

measurementTimeSeries[].timeOffsets

ja

Zeitpunkt jedes Werts in Millisekunden nach firstSampleTimestamp. 1 bis 200 Einträge.

measurementTimeSeries[].values

ja

Werte, einer je Zeitversatz. timeOffsets und values müssen gleich lang sein. null-Werte werden übersprungen.

measurementTimeSeries[].measurementUnit

nein

Einheit, zum Beispiel °C. Maximal 32 Zeichen.

measurementTimeSeries[].measurementType

nein

0 absolute Werte, 1 Deltawerte.

measurementTimeSeries[].constantLimits

nein

Grenzwerte, die für alle Werte gelten: target, lowerWarn, lowerError, upperWarn, upperError. type auf constantLimits setzen.

measurementTimeSeries[].seriesLimits

nein

Grenzwerte je Wert. Jedes Array hat dieselbe Länge wie values. type auf seriesLimits setzen. Nicht mit constantLimits kombinierbar.

Empfehlungen

  • Werte gebündelt senden statt einer Anfrage je Wert, zum Beispiel alle Werte einer Sekunde oder einiger Sekunden in einer Anfrage.

  • Den Zeitpunkt der Messung als firstSampleTimestamp verwenden, nicht den Zeitpunkt des Sendens.

  • Gerät und Messpunkte in der Konfiguration aktualisieren, bevor Daten für neue Messpunkte gesendet werden.

  • Bei 429 oder 503 die Zeit aus dem Header Retry-After abwarten und die Anfrage erneut senden.

Ergebnis prüfen

  1. Im Menü auf Geräte (Devices) klicken und das Gerät öffnen.

  2. Prüfen, ob das Messwerte Diagramm (Measurement Chart) die neuen Werte zeigt. Siehe Messwerte.

Werden die Werte nicht angezeigt, Folgendes prüfen:

  • reference.identifier stimmt exakt mit dem Wert im Feld Technische ID des Geräts überein,

  • name stimmt exakt mit dem Wert im Feld Name eines Messpunkts des Geräts überein,

  • die Zeitstempel liegen im gewählten Zeitraum des Diagramms.

Diese Seite bearbeiten Edit this page

Feedback on this pageFeedback zu dieser Seite