REST-API

Ca. 16 Min. Lesezeit

Mit der REST-API von 2WinScada können Programme von Drittanbietern die aktuellen Zustände von Geräten und Tags lesen und Archivdaten (Logs) abfragen. Diese Seite beschreibt nur die Endpunkte, die für externe Integrationen geeignet sind und auch mit einem API-Schlüssel verwendet werden können.

Die Endpunkte auf dieser Seite lesen nur Daten. Um Daten aus externen Systemen an 2WinScada zu senden, verwenden Sie den Kanal REST-Server; damit 2WinScada periodisch Daten aus einem externen System abruft, verwenden Sie den Kanal REST-Client.

Serveradresse

Die API wird unter derselben Adresse und demselben Port wie die Weboberfläche bereitgestellt. Alle Pfade auf dieser Seite werden an die Adresse der Weboberfläche angehängt, zum Beispiel https://<Server>/api/Monitor/Devices.

Setzen Sie für <Server> die Adresse ein, unter der die Benutzer 2WinScada im Browser öffnen (DNS-Name oder IP-Adresse). Wird die Weboberfläche auf einem anderen als dem Standardport bereitgestellt, geben Sie auch den Port an (https://<Server>:<Port>). Verwenden Sie HTTPS, damit Anmeldedaten und API-Schlüssel nicht im Klartext über das Netzwerk übertragen werden. Für eine Änderung der Adresse oder des Ports wenden Sie sich an Ihren Systemintegrator.

Authentifizierung

Anfragen werden auf einem von zwei Wegen autorisiert:

• API-Schlüssel: Empfohlen für die Integration von Maschine zu Maschine. Anmeldung und Token-Aktualisierung sind nicht erforderlich.
• Benutzeranmeldung (Token): Sie melden sich mit einem im System definierten Benutzer an und senden das zurückgegebene Zugriffstoken mit jeder Anfrage.

Die beiden Verfahren werden nicht in derselben Anfrage zusammen verwendet. Enthält die Anfrage einen Authorization-Header, wird der ApiKey-Header nicht berücksichtigt; ein ungültiges oder abgelaufenes Token führt zur Ablehnung der Anfrage, auch wenn ein gültiger API-Schlüssel vorhanden ist.

Mit API-Schlüssel

API-Schlüssel werden auf der Registerkarte API-Schlüssel der Seite Benutzerverwaltung erstellt. Einzelheiten finden Sie auf der Seite API-Schlüssel.

1. Klicken Sie auf der Registerkarte API-Schlüssel über der Tabelle auf die Schaltfläche zum Hinzufügen. Das Fenster API-Schlüsseldefinition öffnet sich.

2. Füllen Sie die Felder aus:

   Feld	Beschreibung	Standardwert	Bereich
   Benutzername	Der Benutzer, dem der Schlüssel gehört. Der Schlüssel arbeitet mit den Rollen und Prozessgruppenberechtigungen dieses Benutzers. Kann nach dem Speichern nicht geändert werden.
   Schlüsselname	Name zur Kennzeichnung des Schlüssels. Zwei Schlüssel desselben Benutzers können nicht denselben Namen haben.		Höchstens 100 Zeichen
   Zweck	Für die REST-API muss SCADA API ausgewählt werden. Schlüssel mit dem Zweck MCP-Zugriff gelten in der REST-API als ungültig. Kann nach dem Speichern nicht geändert werden.	MCP-Zugriff	SCADA API, MCP-Zugriff
   Maximale Anfragen	Höchstzahl der Anfragen innerhalb von 10 Minuten.	300	1–30.000.000

3. Speichern Sie. Im Fenster API-Schlüssel erstellt wird der Schlüssel nur ein einziges Mal angezeigt. Kopieren Sie ihn mit Kopieren, bewahren Sie ihn an einem sicheren Ort auf, und klicken Sie dann auf Gespeichert, schließen. Der Schlüssel kann später nicht erneut angezeigt werden; geht er verloren, wird ein neuer Schlüssel erstellt.

Schlüssel mit dem Zweck SCADA API beginnen mit 2Win-. Einem Benutzer können mehrere Schlüssel zugewiesen werden; so kann jede Integration einen eigenen Schlüssel erhalten, und bei Bedarf wird nur dieser Schlüssel widerrufen.

Der Schlüssel wird bei jeder Anfrage im Header ApiKey gesendet:

GET /api/Monitor/Devices HTTP/1.1
Host: <Server>
ApiKey: <API-Schluessel>

curl -H "ApiKey: <API-Schluessel>" "https://<Server>/api/Monitor/Devices"

Regeln für die Verwendung der Schlüssel:

• Schlüssel haben keine Gültigkeitsdauer. Um einen Schlüssel zu widerrufen, löschen Sie ihn auf der Registerkarte API-Schlüssel; Anfragen mit einem gelöschten Schlüssel werden sofort abgelehnt. Beim Bearbeiten können nur Schlüsselname und Maximale Anfragen geändert werden.
• Können sich Konten nicht anmelden, weil das Kontolimit der Lizenz überschritten ist, werden auch die Schlüssel dieser Konten abgelehnt (siehe Lizenz).
• Die Spalten Anfragen und Letzte Anfrage zeigen die Nutzung des Schlüssels. Anfragen werden in festen 10-Minuten-Fenstern gezählt; ein Fenster beginnt mit der ersten Anfrage nach Ablauf des vorherigen Fensters. Ist Maximale Anfragen überschritten, werden Anfragen mit dem Schlüssel bis zum Ablauf des Fensters abgelehnt; im neuen Fenster beginnt der Zähler bei null, und der Client kann wieder Anfragen senden. Wählen Sie die Abfragehäufigkeit und den Wert für Maximale Anfragen entsprechend.
• Für Archivabfragen mit einem API-Schlüssel gelten engere Grenzen als für eine Benutzersitzung (siehe Abfragegrenzen).

Mit Benutzeranmeldung

Um mit einem Token zu arbeiten, melden Sie sich zuerst an:

POST /api/User/login HTTP/1.1
Host: <Server>
Content-Type: application/json

{
  "UserName": "<Benutzername>",
  "Password": "<Passwort>"
}

Erfolgreiche Antwort:

{
  "Payload": {
    "AccessToken": "<access_token>",
    "RefreshToken": "<refresh_token>",
    "RefreshTokenExpiryTime": "2026-10-22T09:30:00+03:00",
    "PasswordChangeRequired": false
  },
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Feld	Beschreibung
AccessToken	Das Zugriffstoken, das bei den folgenden Anfragen im Header Authorization gesendet wird. Die Standardgültigkeit beträgt 240 Minuten.
RefreshToken	Wird zum Erneuern des Zugriffstokens verwendet. Die Standardgültigkeit beträgt 7 Tage.
RefreshTokenExpiryTime	Ablaufzeitpunkt des Aktualisierungstokens.
PasswordChangeRequired	Ist der Wert true, muss das Passwort des Kontos geändert werden. Ändern Sie das Passwort des Kontos, das für die Integration verwendet wird, zuerst in der Oberfläche.

Sind Benutzername oder Passwort falsch, ist Success gleich false und ErrorCode gleich 2107. Nach zu vielen fehlgeschlagenen Versuchen wird die Anmeldung vorübergehend gesperrt (2110).

Bei den folgenden Anfragen wird das Zugriffstoken im Header Authorization mit dem Präfix Bearer gesendet:

GET /api/Monitor/Devices HTTP/1.1
Host: <Server>
Authorization: Bearer <access_token>

Token-Aktualisierung

Ist das Zugriffstoken abgelaufen, geben die Endpunkte auf dieser Seite HTTP 403 und "ErrorMessage": "Geçersiz Giriş Token" zurück. In diesem Fall wird mit dem abgelaufenen Zugriffstoken und dem Aktualisierungstoken ein neues Zugriffstoken abgerufen:

PUT /api/User/RefreshToken HTTP/1.1
Host: <Server>
Content-Type: application/json

{
  "AccessToken": "<abgelaufenes_access_token>",
  "RefreshToken": "<refresh_token>"
}

Die Antwort hat denselben Aufbau wie die Antwort auf die Anmeldung. Payload.AccessToken enthält das neue Zugriffstoken; das Aktualisierungstoken ändert sich nicht.

Schlägt die Aktualisierung fehl, ist der HTTP-Statuscode trotzdem 200, und Success ist false. Ist ErrorCode gleich 2108, ist das Aktualisierungstoken abgelaufen, bei 2106 ist es ungültig. In beiden Fällen müssen Sie sich erneut anmelden.

Der Server führt pro Konto ein einziges Aktualisierungstoken. Jede Anmeldung mit demselben Konto (auch in der Weboberfläche) erzeugt ein neues Aktualisierungstoken und macht das bisherige ungültig. Verwenden Sie für eine Integration ein eigenes Konto, das nicht in der Weboberfläche verwendet wird, oder einen API-Schlüssel.

Ab 2.11 speichert die Weboberfläche das Aktualisierungstoken ihrer eigenen Sitzung in einem Cookie, das Browser-Skripte nicht lesen können. Diesen Modus schaltet nur die Weboberfläche ein; die Anmelde- und Aktualisierungsaufrufe auf dieser Seite ändern sich nicht, und das Aktualisierungstoken wird weiterhin im Antwort-Body zurückgegeben. Auch der MCP-Server ist nicht betroffen.

Aufbau der Antwort

Alle Endpunkte geben denselben JSON-Umschlag zurück. Feldnamen beginnen mit einem Großbuchstaben (PascalCase); bei Feldnamen im Anfragetext wird die Groß-/Kleinschreibung nicht beachtet.

{
  "Payload": {},
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Feld	Beschreibung
Payload	Das Ergebnis der Anfrage. Der Aufbau hängt vom Endpunkt ab. Im Fehlerfall kann das Feld leer oder null sein.
Success	true, wenn der Vorgang erfolgreich war.
ErrorMessage	Fehlermeldung (auf Türkisch). Bei erfolgreichen Anfragen null.
ErrorCode	Fehlercode. Bei erfolgreichen Anfragen 0.

Fehler in der Geschäftslogik (fehlender Parameter, nicht gefundene Log-Definition, Abfragegrenze usw.) werden mit HTTP 200 und Success: false zurückgegeben. Der Client muss bei jeder Antwort das Feld Success prüfen.

Anfragen, die bei der Authentifizierung abgelehnt werden, kommen mit dem Statuscode 401 oder 403 zurück. Diese Antworten enthalten nur die Felder Success und ErrorMessage, kein ErrorCode:

{
  "Success": false,
  "ErrorMessage": "Geçersiz API Anahtarı"
}

HTTP-Statuscodes

Status	ErrorMessage	Bedeutung
401	Lütfen Geçerli Gir API Anahtarı Sağlayın	Die Anfrage enthält weder einen Authorization- noch einen ApiKey-Header.
401	API Anahtarı Doğrulanırken Hata Oluştu	Bei der Prüfung des Schlüssels ist ein Serverfehler aufgetreten; versuchen Sie es nach einiger Zeit erneut.
403	Geçersiz API Anahtarı	Der Schlüssel wurde nicht gefunden, wurde gelöscht, hat den Zweck MCP-Zugriff, oder das Konto, dem er gehört, kann nicht verwendet werden.
403	Maksimum Sorgulama Limiti Aşıldı	Maximale Anfragen des Schlüssels wurde überschritten. Die Antwort enthält den Header X-RateLimit-RetryAfter.
403	Geçersiz Giriş Token	Das Token im Header Authorization ist ungültig oder abgelaufen.
403	Bu Kullanıcı Bu Müdahaleye Yetkili Değil	Die Rolle des Benutzers oder des Schlüsselbesitzers reicht für diesen Endpunkt nicht aus.

Häufige Fehlercodes

ErrorCode	Bedeutung
1101	Fehlender oder fehlerhafter Parameter. Bei Archivabfragen beschreibt ErrorMessage das fehlende Feld.
1203	Grenze für Archivabfragen überschritten (Anzahl der Log-Definitionen, geschätzte Zellenzahl, gleichzeitige Abfragen oder Zeitüberschreitung der Abfrage).
1208	Der angeforderte Datumsbereich überschreitet die zulässige Grenze.
2106	Aktualisierungstoken ungültig.
2107	Benutzername oder Passwort falsch.
2108	Sitzung abgelaufen; erneute Anmeldung erforderlich.
2110	Zu viele fehlgeschlagene Anmeldeversuche; warten Sie eine Weile.
3101	Tag nicht gefunden.
3501	Log-Definition nicht gefunden.
4400	Log-Tabelle nicht gefunden.
4401	Keine Verbindung zur Log-Datenbank.

Live-Daten

Gerätezustände

GET /api/Monitor/Devices

Listet die im System definierten Geräte mit ihrem Kommunikationszustand und dem letzten Fehler auf. Benutzer ohne die Rolle Editor und die API-Schlüssel dieser Benutzer sehen nur die Geräte in den Prozessgruppen, für die sie berechtigt sind.

{
  "Payload": [
    {
      "Id": 3,
      "Active": true,
      "Name": "Kompresor_1",
      "ChannelId": 1,
      "ConnectionType": 2,
      "ConnectionTypeStr": "ModbusTcp",
      "ConnectionQuality": 1,
      "DeviceQualityStr": "Good",
      "TagQuality": 1,
      "TagQualityStr": "Good",
      "ConnectionDescription": "192.168.1.10:502",
      "ErrorString": null,
      "ErrorOccurredTime": "0001-01-01T00:00:00",
      "Parameters": "",
      "AlarmState": -1,
      "ChangedTime": "2026-10-15T10:42:07.123+03:00",
      "IsOutOfDate": false,
      "IsConnected": false,
      "Tags": null
    }
  ],
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Feld	Beschreibung
Id	Eindeutige ID des Geräts.
Active	true, wenn die Kommunikation mit dem Gerät aktiviert ist.
Name	Gerätename.
ChannelId	ID des Kanals, zu dem das Gerät gehört.
ConnectionType	Zahl für den Verbindungstyp des Kanals (siehe Tabelle unten).
ConnectionTypeStr	Textform des Verbindungstyps.
ConnectionQuality	Qualität der Verbindung zum Gerät: 0 = Bad, 1 = Good, 2 = Uncertain.
DeviceQualityStr	Textform von ConnectionQuality.
TagQuality	Lesequalität der Tags des Geräts; sie verschlechtert sich, wenn eines der Tags nicht gelesen werden kann. Nimmt dieselben Werte wie ConnectionQuality an.
TagQualityStr	Textform von TagQuality.
ConnectionDescription	Kurzbeschreibung der Verbindungsparameter.
ErrorString	Letzte Fehlermeldung der Gerätekommunikation.
ErrorOccurredTime	Zeitpunkt des letzten Fehlers.
Parameters	Text mit den Verbindungsparametern.
AlarmState	Zustand der Alarme, die für die Tags des Geräts definiert sind: -1 = kein Alarm, 0 = Alarm beendet, 1 = Alarmbedingung nicht mehr erfüllt, Rücksetzen ausstehend, 2 = Alarm bestätigt, 3 = neuer Alarm.
ChangedTime	Zeitpunkt der letzten Aktualisierung eines Tags des Geräts. Hat das Gerät keine Tags, wird 0001-01-01T00:00:00 zurückgegeben.
IsOutOfDate	true, wenn die Gerätedefinition geändert wurde und das Gerät neu initialisiert werden muss.
IsConnected	Wird bei diesem Endpunkt nicht verwendet, immer false.
Tags	Wird bei diesem Endpunkt nicht verwendet, immer null. Für Tag-Werte verwenden Sie die folgenden Endpunkte.

Werte von ConnectionType:

Wert	Text	Wert	Text
1	ModbusSerial	8	MtConnect
2	ModbusTcp	9	BacNet
3	ModbusOverEth	10	Database
4	OpcServer	11	RestClient
5	SiemensTcp	13	RestServer
6	Mqtt	14	EtherNetIp
7	OpcUa	999	Internal

Werte, die nicht in der Tabelle stehen, gehören zu älteren Verbindungstypen, die in diesem Handbuch nicht beschrieben werden.

Tag-Werte eines Geräts

Die aktuellen Werte aller Tags eines Geräts erhalten Sie über drei Endpunkte:

Endpunkt	Beschreibung
GET /api/Monitor/Devices/TagsByName/{deviceName}	Über den Gerätenamen. Beim Namen wird die Groß-/Kleinschreibung beachtet.
GET /api/Monitor/Devices/TagsById/{deviceId}	Über die Geräte-ID.
GET /api/Monitor/Devices/Tags/ByDeviceIds?deviceIds=3,5	Die Tags mehrerer Geräte in einer Liste. Die IDs können durch Kommas getrennt oder in der Form deviceIds=3&deviceIds=5 wiederholt werden. Ein Wert, der keine Zahl ist, liefert HTTP 400.

Wird das Gerät nicht gefunden, wird kein Fehler zurückgegeben; Payload ist eine leere Liste.

GET /api/Monitor/Devices/TagsByName/Kompresor_1

{
  "Payload": [
    {
      "Id": 41,
      "DeviceId": 3,
      "DeviceName": "Kompresor_1",
      "Name": "Basinc",
      "Address": "40001",
      "FullName": "Kanal_1.Kompresor_1.Basinc",
      "Value": 6.82,
      "ChangedTime": "2026-10-15T10:42:07.123+03:00",
      "Quality": 1,
      "QualityStr": "Good",
      "IsAlarmDefined": true,
      "IsLogDefined": true,
      "Unit": "bar",
      "Description": "Hat basıncı"
    }
  ],
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Feld	Beschreibung
Id	Eindeutige ID des Tags.
DeviceId	ID des Geräts, zu dem das Tag gehört.
DeviceName	Name des Geräts, zu dem das Tag gehört.
Name	Tag-Name.
Address	Adresse des Tags im Gerät.
FullName	Vollständiger Name in der Form Kanal.Gerät.Tag. Im System eindeutig.
Value	Zuletzt gelesener Wert des Tags. Je nach Datentyp des Tags eine Zahl, ein boolescher Wert oder ein Text.
ChangedTime	Zeitpunkt der letzten Aktualisierung des Werts.
Quality	Lesequalität: 0 = Bad (kann nicht gelesen werden), 1 = Good (fehlerfrei), 2 = Uncertain (unklar, z. B. noch nicht gelesen).
QualityStr	Textform von Quality.
IsAlarmDefined	true, wenn für das Tag ein Alarm definiert ist.
IsLogDefined	true, wenn für das Tag ein Log (Archiv) definiert ist.
Unit	Für das Tag definierte Einheit.
Description	Beschreibung des Tags.

Wert eines einzelnen Tags

Endpunkt	Beschreibung
GET /api/Monitor/Tag/{tagFullName}	Über den vollständigen Namen (Kanal.Gerät.Tag).
GET /api/Monitor/TagById/{tagId}	Über die Tag-ID.

Payload hat denselben Aufbau wie das Tag-Objekt oben. Wird das Tag nicht gefunden, ist Success gleich true und Payload gleich null. Da der vollständige Name in der URL gesendet wird, schreiben Sie Leerzeichen und Sonderzeichen URL-codiert (z. B. %20 für ein Leerzeichen).

Archivdaten

Die Archiv-Endpunkte fragen die gespeicherten Daten von Tags ab, für die eine Log-Definition (Archiv) angelegt ist. In den Abfragen wird nicht die Tag-ID, sondern die ID der Log-Definition (Ids) verwendet. Informationen zu Log-Definitionen finden Sie auf der Seite Log-Definitionen (Archiv).

ID der Log-Definition ermitteln

GET /api/Tags/ByName/{name}/LogInfos

Als {name} muss der vollständige Name des Tags (Kanal.Gerät.Tag) angegeben werden. Auch der reine Tag-Name wird akzeptiert; gibt es jedoch mehrere Tags mit demselben Namen, werden nur die Log-Definitionen des zuerst gefundenen Tags zurückgegeben. Wird das Tag nicht gefunden, ist ErrorCode gleich 3101.

Payload ist die Liste der Log-Definitionen des Tags. Für Abfragen verwendete Felder:

Feld	Beschreibung
Id	ID der Log-Definition. Wird in Archivabfragen im Parameter Ids angegeben.
TagId	ID des Tags, zu dem die Log-Definition gehört.
Desc	Beschreibung der Log-Definition.

Abfragegrenzen

Archivabfragen werden zum Schutz des Servers begrenzt: Begrenzt sind die Abfragedauer, die Anzahl der Log-Definitionen in einer Abfrage, die Anzahl der zurückgegebenen Zeilen und der Datumsbereich einer Abfrage der Rohdatensätze. Für Abfragen mit einem API-Schlüssel gelten engere Grenzen.

Senden Sie Archivabfragen mit einem API-Schlüssel nacheinander und nicht gleichzeitig; eine gleichzeitig gesendete Abfrage kann mit dem Code 1203 abgelehnt werden.

Die auf dem Server geltenden Grenzen können Sie über diesen Endpunkt lesen:

GET /api/History/QueryLimits

{
  "Payload": {
    "Profile": "ApiKey",
    "QueryTimeoutSeconds": <Sekunden>,
    "MaxLogInfoCount": <Zahl>,
    "MaxEstimatedCells": <Zahl>,
    "MaxRows": <Zahl>,
    "MaxRawTagRangeSeconds": <Sekunden>,
    "MaxEventRangeSeconds": <Sekunden>,
    "MaxSnapshotItems": <Zahl>
  },
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Der Wert von Profile ist bei Anfragen mit einem API-Schlüssel ApiKey, bei einer Benutzersitzung Interactive.

Datumsformat

StartDate und EndDate werden im Format ISO 8601 angegeben, zum Beispiel 2026-10-15T08:00:00Z oder 2026-10-15T08:00:00+03:00. In der Abfragezeichenfolge werden auch die Formate yyyy-MM-dd HH:mm und yyyy-MM-dd HH:mm:ss akzeptiert. Ist keine Zeitzone angegeben, wird die lokale Uhrzeit des Servers angenommen. Codieren Sie das Zeichen + in der Abfragezeichenfolge als %2B. Die Archivzeitpunkte in den Antworten werden in UTC (Z) zurückgegeben.

Rohdatensätze des Archivs

GET /api/History/Tags?Ids=1,2&StartDate=2026-10-15T08:00:00Z&EndDate=2026-10-15T09:00:00Z
POST /api/History/Tags

Gibt alle Datensätze im angegebenen Datumsbereich ohne Abtastung zurück. Bei POST werden dieselben Felder im JSON-Anfragetext gesendet.

Parameter	Beschreibung
Ids	IDs der Log-Definitionen. In der Abfragezeichenfolge durch Kommas getrennt (Ids=1,2) oder wiederholt (Ids=1&Ids=2).
StartDate	Startzeitpunkt. Pflichtangabe.
EndDate	Endzeitpunkt. Pflichtangabe; der Datumsbereich darf die Grenze für Rohdatensätze nicht überschreiten.

Die Antwort hat denselben Tabellenaufbau wie die Antwort für das abgetastete Archiv.

Abgetastetes Archiv

GET /api/History/TagsSampleBy
POST /api/History/TagsSampleBy

Teilt die Datensätze in Intervalle, die durch SampleTime festgelegt werden, und führt für jedes Intervall die mit ValueType gewählte Berechnung aus. Wird die Abtastzeit gleich dem Abstand zwischen den Datensätzen gewählt, kommen die Datensätze nahezu im Rohzustand zurück.

Parameter	Beschreibung	Standardwert	Werte
Ids	IDs der Log-Definitionen. Mindestens eine positive ID ist erforderlich.
StartDate	Startzeitpunkt. Pflichtangabe.
EndDate	Endzeitpunkt. Pflichtangabe; darf nicht vor StartDate liegen.
SampleTime	Abtastintervall in Sekunden.	18600	Größer als 0
ValueType	Berechnung, die in jedem Intervall ausgeführt wird.	0	0 = Min, 1 = Max, 2 = Avg (Durchschnitt), 3 = Sum (Summe), 4 = Count (Anzahl der Datensätze)
FillType	Wie Intervalle ohne Datensätze gefüllt werden.	0	0 = NULL (bleibt leer), 1 = PREV (vorheriger Wert), 2 = LINEAR (lineare Interpolation), 3 = X (wird mit FillValue gefüllt)
FillValue	Ganzzahliger Wert, der bei FillType = 3 verwendet wird.	0
AlignToCalendar	Bei true werden die Intervalle am Kalender ausgerichtet (Beginn von Stunde, Tag und Monat in der Zeitzone IANATimeZone); bei false beginnen die Intervalle mit dem Zeitpunkt des ersten Datensatzes.	true	true, false
CalculateConsumption	Bei true wird anstelle von ValueType der Verbrauch jedes Intervalls nach den Verbrauchseinstellungen der Log-Definition berechnet: Momentanwerte werden summiert; bei kumulativen Zählern werden, beginnend mit dem letzten Wert vor dem Intervall, die Zuwächse zwischen aufeinanderfolgenden Werten summiert (bei einem Zählerrücksetzen zählt der Schritt als 0); das Ergebnis wird mit Faktor und Divisor der Log-Definition skaliert.	false	true, false
IANATimeZone	Zeitzone für die Ausrichtung am Kalender, zum Beispiel Europe/Istanbul. Bleibt der Wert leer, wird die Zeitzone des Servers verwendet.

In der Abfragezeichenfolge können ValueType und FillType als Zahl oder als Name (ValueType=Max) angegeben werden; im JSON-Anfragetext müssen sie als Zahl gesendet werden.

Beispielabfrage (größter Wert in Halbstundenintervallen):

GET /api/History/TagsSampleBy?Ids=1&ValueType=1&FillType=0&FillValue=0&SampleTime=1800&AlignToCalendar=false&CalculateConsumption=false&StartDate=2026-10-15T08:00:00Z&EndDate=2026-10-15T09:00:00Z HTTP/1.1
Host: <Server>
ApiKey: <API-Schluessel>

Anfragetext, wenn dieselbe Abfrage mit POST gesendet wird:

{
  "Ids": [1],
  "ValueType": 1,
  "FillType": 0,
  "FillValue": 0,
  "SampleTime": 1800,
  "AlignToCalendar": false,
  "CalculateConsumption": false,
  "StartDate": "2026-10-15T08:00:00Z",
  "EndDate": "2026-10-15T09:00:00Z"
}

Antwort:

{
  "Payload": {
    "query": "",
    "columns": [
      { "name": "ChangedTime", "type": "timestamp" },
      { "name": "1", "type": "DOUBLE" }
    ],
    "dataset": [
      ["2026-10-15T08:00:37Z", 1194.13919413919],
      ["2026-10-15T08:30:37Z", 1175.82417582418]
    ],
    "count": 2
  },
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Die Feldnamen in Payload werden kleingeschrieben:

Feld	Beschreibung
columns	Liste der Spalten. Die erste Spalte ist ChangedTime, jede weitere Spalte ist eine Log-Definition; der Spaltenname ist die ID der Log-Definition.
dataset	Zeilen. Das erste Element jeder Zeile ist der UTC-Zeitpunkt, die weiteren Elemente sind die Werte der Log-Definitionen in der Reihenfolge von columns. Für eine Log-Definition ohne Wert zu diesem Zeitpunkt wird null zurückgegeben.
count	Anzahl der Zeilen.
query	Wird nicht verwendet, bleibt leer.

Verbrauchsberechnung

POST /api/History/TagsSampleByForPivotDiffSum

Gibt die Verbrauchswerte der Log-Definitionen in den festgelegten Intervallen zeilenweise zusammen mit Aufgabenzentrum und Prozessgruppe zurück. Der Anfragetext enthält dieselben Felder wie beim abgetasteten Archiv; bei diesem Endpunkt muss CalculateConsumption als true gesendet werden, andernfalls wird der Code 3501 zurückgegeben.

Bei Log-Definitionen mit kumulativen Zählern werden die Differenzen aufeinanderfolgender Datensätze summiert; Rücksprünge wie ein Zählerrücksetzen zählen als 0. Bei den übrigen Log-Definitionen werden die Werte summiert. Das Ergebnis wird mit Faktor und Divisor der Log-Definition skaliert. Um den Gesamtverbrauch des Datumsbereichs als einen einzigen Wert zu erhalten, setzen Sie SampleTime auf die Länge des Bereichs in Sekunden.

curl -X POST "https://<Server>/api/History/TagsSampleByForPivotDiffSum" \
  -H "ApiKey: <API-Schluessel>" \
  -H "Content-Type: application/json" \
  -d '{
    "Ids": [1, 2],
    "ValueType": 1,
    "FillType": 0,
    "FillValue": 0,
    "SampleTime": 3600,
    "AlignToCalendar": false,
    "CalculateConsumption": true,
    "StartDate": "2026-10-15T08:00:00Z",
    "EndDate": "2026-10-15T09:00:00Z"
  }'

Antwort:

{
  "Payload": [
    {
      "LogInfoId": 1,
      "Desc": "Hat_1_Buhar [ton]",
      "ChangedTime": "2026-10-15T08:00:37Z",
      "Value": 0.22014652014652,
      "TaskCenter": "Uretim",
      "DataGroup": "Buhar_Tuketimi"
    },
    {
      "LogInfoId": 2,
      "Desc": "Hat_2_Buhar [ton]",
      "ChangedTime": "2026-10-15T08:00:37Z",
      "Value": 0.7927872860635696,
      "TaskCenter": "Uretim",
      "DataGroup": "Buhar_Tuketimi"
    }
  ],
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0
}

Feld	Beschreibung
LogInfoId	ID der Log-Definition.
Desc	Beschreibung der Log-Definition und in eckigen Klammern ihre Einheit. Ist in der Log-Definition eine Einheit für den Gesamtwert eingetragen, wird diese verwendet, sonst die Einheit des Tags.
ChangedTime	Startzeitpunkt des Intervalls (UTC).
Value	Verbrauch im Intervall. Gibt es keine Datensätze, wird der Wert entsprechend FillType gefüllt oder null zurückgegeben.
TaskCenter	Aufgabenzentrum des Geräts, zu dem das Tag gehört.
DataGroup	Prozessgruppe des Aufgabenzentrums des Geräts; wird keine gefunden, die Tag-Gruppe, zu der das Tag gehört.

Swagger

Ist auf dem Server die API-Dokumentation aktiviert, können alle Endpunkte und ihre Schemas in der Swagger-Oberfläche angesehen und ausprobiert werden. Die API-Dokumentation ist standardmäßig deaktiviert; für die Aktivierung und die Zugriffsadresse wenden Sie sich an Ihren Systemintegrator. In Swagger können Sie über Authorize einen Wert für ApiKey oder Authorization eingeben und Anfragen senden.

Fehlerbehebung

Symptom	Prüfung
401, Lütfen Geçerli Gir API Anahtarı Sağlayın	Prüfen Sie, ob die Anfrage einen ApiKey- oder Authorization-Header enthält und der Header-Name richtig geschrieben ist.
403, Geçersiz API Anahtarı	Prüfen Sie, ob der Schlüssel vollständig kopiert und nicht gelöscht wurde und ob Zweck den Wert SCADA API hat. Schlüssel mit MCP-Zugriff funktionieren in der REST-API nicht.
Trotz gesendetem API-Schlüssel wird Geçersiz Giriş Token zurückgegeben	Die Anfrage enthält zusätzlich einen Authorization-Header. Entfernen Sie diesen Header.
403, Maksimum Sorgulama Limiti Aşıldı	Versuchen Sie es nach Ablauf des 10-Minuten-Fensters erneut. Verringern Sie die Abfragehäufigkeit, oder erhöhen Sie den Wert für Maximale Anfragen.
Bei der Arbeit mit einem Token nach einigen Stunden 403, Geçersiz Giriş Token	Das Zugriffstoken ist abgelaufen. Führen Sie eine Token-Aktualisierung durch; gibt die Aktualisierung 2106 oder 2108 zurück, melden Sie sich erneut an.
/api/Monitor/Devices liefert einige Geräte nicht	Prüfen Sie, ob der Benutzer bzw. der Besitzer des Schlüssels in der betreffenden Prozessgruppe berechtigt ist.
Die Abfrage über den Gerätenamen liefert eine leere Liste	Prüfen Sie, ob der Gerätename einschließlich Groß-/Kleinschreibung exakt geschrieben ist, und prüfen Sie die URL-Codierung.
Die Archivabfrage liefert 1203	Verringern Sie die Anzahl der Log-Definitionen, den Datumsbereich oder die Abtasthäufigkeit; senden Sie Archivabfragen mit einem API-Schlüssel nacheinander und nicht gleichzeitig. Prüfen Sie die Grenzen mit GET /api/History/QueryLimits.
Die Archivabfrage liefert 1208	Verkleinern Sie den Datumsbereich der Abfrage der Rohdatensätze, oder verwenden Sie den Endpunkt für das abgetastete Archiv.
Die Archivabfrage liefert 3501	Prüfen Sie, ob die Werte in Ids IDs von Log-Definitionen und nicht von Tags sind. Prüfen Sie bei der Verbrauchsberechnung, ob CalculateConsumption den Wert true hat.
Die Archivabfrage liefert 4401	Prüfen Sie, ob der Dienst der Log-Datenbank läuft.
Archivzeitpunkte sind um einige Stunden verschoben	Die Zeitpunkte in den Antworten sind UTC. Geben Sie die Zeitzone in der Anfrage ausdrücklich an (Z oder +03:00).
Die HTTPS-Anfrage meldet einen Zertifikatsfehler	Prüfen Sie, ob das Serverzertifikat auf der Clientseite als vertrauenswürdig gilt.