REST API

Yaklaşık 13 dk okuma

2WinScada REST API'si, üçüncü parti yazılımların anlık cihaz ve tag durumlarını okumasını ve arşiv (log) verilerini sorgulamasını sağlar. Bu sayfada yalnız dış entegrasyon için uygun olan, API anahtarıyla da kullanılabilen uçlar anlatılır.

Bu sayfadaki uçlar salt okunurdur. Dış sistemlerden 2WinScada'ya veri göndermek için REST Sunucu kanalını, 2WinScada'nın dış sistemden periyodik veri çekmesi için REST İstemci kanalını kullanın.

Sunucu adresi

API, web arayüzüyle aynı adres ve port üzerinden yayınlanır. Bu sayfadaki tüm yollar web arayüzünün adresine eklenir; örneğin https://<sunucu>/api/Monitor/Devices.

<sunucu> yerine kullanıcıların 2WinScada'yı tarayıcıda açtığı adresi (DNS adı veya IP adresi) yazın. Web arayüzü varsayılandan farklı bir portta yayınlanıyorsa portu da ekleyin (https://<sunucu>:<port>). Kimlik bilgileri ve API anahtarları ağda açık metin olarak taşınmasın diye HTTPS kullanın. Adres veya port değişikliği için sistem entegratörünüze başvurun.

Kimlik doğrulama

İstekler iki yoldan biriyle yetkilendirilir:

• API anahtarı: Makineden makineye entegrasyon için önerilir. Giriş ve token yenileme gerekmez.
• Kullanıcı girişi (token): Sistemde tanımlı bir kullanıcıyla giriş yapılır, dönen erişim token'ı her istekte gönderilir.

İki yöntem aynı istekte birlikte kullanılmaz. İstekte Authorization başlığı varsa ApiKey başlığı dikkate alınmaz; geçersiz veya süresi dolmuş bir token, geçerli bir API anahtarı olsa bile isteğin reddedilmesine yol açar.

API anahtarı ile

API anahtarı, Kullanıcı Yönetimi sayfasının API Anahtarları sekmesinde oluşturulur. Ayrıntılar için API Anahtarları sayfasına bakın.

1. API Anahtarları sekmesinde tablonun üstündeki ekle düğmesine tıklayın. Api Anahtarı Tanımlama penceresi açılır.

2. Alanları doldurun:

   Alan	Açıklama	Varsayılan	Aralık
   Kullanıcı Adı	Anahtarın sahibi olan kullanıcı. Anahtar bu kullanıcının rolleri ve proses grubu yetkileriyle çalışır. Kayıttan sonra değiştirilemez.
   Anahtar adı	Anahtarı tanımlayan ad. Aynı kullanıcının iki anahtarı aynı adı taşıyamaz.		En fazla 100 karakter
   Amaç	REST API için SCADA API seçilmelidir. MCP erişimi amaçlı anahtarlar REST API'de geçersiz sayılır. Kayıttan sonra değiştirilemez.	MCP erişimi	SCADA API, MCP erişimi
   Maksimum İstek Sayısı	10 dakika içinde yapılabilecek en fazla istek sayısı.	300	1–30.000.000

3. Kaydedin. API anahtarı oluşturuldu penceresinde anahtar yalnız bir kez gösterilir. Kopyala ile kopyalayıp güvenli bir yerde saklayın, ardından Kaydettim, kapat düğmesine tıklayın. Anahtar daha sonra tekrar görüntülenemez; kaybedilirse yeni bir anahtar oluşturulur.

SCADA API amaçlı anahtarlar 2Win- ile başlar. Bir kullanıcıya birden fazla anahtar tanımlanabilir; böylece her entegrasyona ayrı bir anahtar verilip gerektiğinde yalnız o anahtar iptal edilebilir.

Anahtar, her isteğin ApiKey başlığında gönderilir:

GET /api/Monitor/Devices HTTP/1.1
Host: <sunucu>
ApiKey: <api_anahtarı>

curl -H "ApiKey: <api_anahtarı>" "https://<sunucu>/api/Monitor/Devices"

Anahtar kullanımına ilişkin kurallar:

• Anahtarların bir geçerlilik süresi yoktur. Anahtarı iptal etmek için API Anahtarları sekmesinden silin; silinen anahtarla yapılan istekler hemen reddedilir. Düzenleme ile yalnız Anahtar adı ve Maksimum İstek Sayısı değiştirilebilir.
• Lisanstaki hesap sınırı aşıldığı için hesaplar oturum açamıyorsa bu hesapların anahtarları da reddedilir (bkz. Lisans).
• İstek Sayısı ve Son İstek Zamanı sütunları anahtarın kullanımını gösterir. İstekler sabit 10 dakikalık pencerelerle sayılır; pencere, önceki pencere dolduktan sonraki ilk istekle başlar. Maksimum İstek Sayısı aşıldığında anahtarla yapılan istekler pencere dolana kadar reddedilir; yeni pencerede sayaç sıfırdan başlar ve istemci yeniden istek yapabilir. Sorgulama sıklığını ve Maksimum İstek Sayısı değerini buna göre seçin.
• API anahtarıyla yapılan arşiv sorgularına kullanıcı oturumundan daha dar sınırlar uygulanır (bkz. Sorgu sınırları).

Kullanıcı girişi ile

Token ile çalışmak için önce giriş yapılır:

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

{
  "UserName": "<kullanıcı_adı>",
  "Password": "<parola>"
}

Başarılı cevap:

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

Alan	Açıklama
AccessToken	Sonraki isteklerde Authorization başlığında gönderilecek erişim token'ı. Varsayılan geçerlilik süresi 240 dakikadır.
RefreshToken	Erişim token'ını yenilemek için kullanılır. Varsayılan geçerlilik süresi 7 gündür.
RefreshTokenExpiryTime	Yenileme token'ının geçerlilik bitiş zamanı.
PasswordChangeRequired	true ise hesabın parolası değiştirilmelidir. Entegrasyonda kullanılacak hesabın parolasını önce arayüzden değiştirin.

Kullanıcı adı veya parola hatalıysa Success değeri false, ErrorCode değeri 2107 olur. Çok sayıda hatalı denemeden sonra giriş geçici olarak kilitlenir (2110).

Sonraki isteklerde erişim token'ı Authorization başlığında Bearer ön ekiyle gönderilir:

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

Token yenileme

Erişim token'ının süresi dolduğunda bu sayfadaki uçlar HTTP 403 ve "ErrorMessage": "Geçersiz Giriş Token" cevabı döner. Bu durumda süresi dolmuş erişim token'ı ve yenileme token'ı ile yeni bir erişim token'ı alınır:

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

{
  "AccessToken": "<süresi_dolmuş_access_token>",
  "RefreshToken": "<refresh_token>"
}

Cevap, giriş cevabıyla aynı yapıdadır. Payload.AccessToken yeni erişim token'ını içerir; yenileme token'ı değişmez.

Yenileme başarısız olursa HTTP durum kodu yine 200 olur ve Success değeri false döner. ErrorCode değeri 2108 ise yenileme token'ının süresi dolmuştur, 2106 ise yenileme token'ı geçersizdir. Her iki durumda da yeniden giriş yapılmalıdır.

Sunucu hesap başına tek yenileme token'ı tutar. Aynı hesapla yapılan her giriş (web arayüzünden yapılanlar dahil) yeni bir yenileme token'ı üretir ve önceki token'ı geçersiz kılar. Entegrasyon için web arayüzünde kullanılmayan ayrı bir hesap veya bir API anahtarı kullanın.

2.11'den itibaren web arayüzü kendi oturumunda yenileme token'ını tarayıcı betiklerinin okuyamadığı bir çerezde tutar. Bu yalnız web arayüzünün açtığı bir kiptir; bu sayfadaki giriş ve yenileme çağrıları değişmez ve yenileme token'ı cevap gövdesinde dönmeye devam eder. MCP sunucusu da etkilenmez.

Cevap yapısı

Tüm uçlar aynı JSON zarfını döner. Alan adları büyük harfle başlar (PascalCase); istek gövdesindeki alan adlarında büyük/küçük harf farkı gözetilmez.

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

Alan	Açıklama
Payload	İsteğin sonucu. Yapısı uca göre değişir. Hata durumunda boş veya null olabilir.
Success	İşlem başarılıysa true.
ErrorMessage	Hata mesajı (Türkçe). Başarılı isteklerde null.
ErrorCode	Hata kodu. Başarılı isteklerde 0.

İş kuralı hataları (eksik parametre, bulunamayan log tanımı, sorgu sınırı vb.) HTTP 200 ile ve Success: false olarak döner. İstemci her cevapta Success alanını kontrol etmelidir.

Kimlik doğrulama aşamasında reddedilen istekler 401 veya 403 durum koduyla döner. Bu cevaplarda yalnız Success ve ErrorMessage alanları bulunur, ErrorCode yoktur:

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

HTTP durum kodları

Durum	ErrorMessage	Anlamı
401	Lütfen Geçerli Gir API Anahtarı Sağlayın	İstekte ne Authorization ne de ApiKey başlığı var.
401	API Anahtarı Doğrulanırken Hata Oluştu	Anahtar doğrulanırken sunucu hatası oluştu; bir süre sonra tekrar deneyin.
403	Geçersiz API Anahtarı	Anahtar bulunamadı, silinmiş, MCP erişimi amaçlı veya sahibi olan hesap kullanılamıyor.
403	Maksimum Sorgulama Limiti Aşıldı	Anahtarın Maksimum İstek Sayısı aşıldı. Cevapta X-RateLimit-RetryAfter başlığı bulunur.
403	Geçersiz Giriş Token	Authorization başlığındaki token geçersiz veya süresi dolmuş.
403	Bu Kullanıcı Bu Müdahaleye Yetkili Değil	Kullanıcının veya anahtar sahibinin rolü bu uç için yetersiz.

Sık karşılaşılan hata kodları

ErrorCode	Anlamı
1101	Eksik veya hatalı parametre. Arşiv sorgularında ErrorMessage eksik alanı açıklar.
1203	Arşiv sorgusu sınırı aşıldı (log tanımı sayısı, tahmini hücre sayısı, eşzamanlı sorgu veya sorgu zaman aşımı).
1208	İstenen tarih aralığı izin verilen sınırı aşıyor.
2106	Yenileme token'ı geçersiz.
2107	Kullanıcı adı veya parola hatalı.
2108	Oturum süresi doldu; yeniden giriş yapılmalı.
2110	Çok fazla hatalı giriş denemesi; bir süre bekleyin.
3101	Tag bulunamadı.
3501	Log tanımı bulunamadı.
4400	Log tablosu bulunamadı.
4401	Log veritabanına bağlanılamadı.

Anlık veriler

Cihaz durumları

GET /api/Monitor/Devices

Sistemde tanımlı cihazları, haberleşme ve son hata durumlarıyla birlikte listeler. Editor rolü olmayan kullanıcılar ve bu kullanıcılara ait API anahtarları yalnız yetkili oldukları proses gruplarındaki cihazları görür.

{
  "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
}

Alan	Açıklama
Id	Cihazın tekil kimliği.
Active	Cihaz haberleşmesi etkinse true.
Name	Cihaz adı.
ChannelId	Cihazın bağlı olduğu kanalın kimliği.
ConnectionType	Kanalın bağlantı tipini gösteren sayı (aşağıdaki tabloya bakın).
ConnectionTypeStr	Bağlantı tipinin metin karşılığı.
ConnectionQuality	Cihazla kurulan bağlantının kalitesi: 0 = Bad, 1 = Good, 2 = Uncertain.
DeviceQualityStr	ConnectionQuality değerinin metin karşılığı.
TagQuality	Cihazın tag'lerinin okunma kalitesi; tag'lerden biri okunamıyorsa bozulur. ConnectionQuality ile aynı değerleri alır.
TagQualityStr	TagQuality değerinin metin karşılığı.
ConnectionDescription	Bağlantı parametrelerinin kısa açıklaması.
ErrorString	Cihaz haberleşmesinde oluşan son hata mesajı.
ErrorOccurredTime	Son hatanın oluştuğu zaman.
Parameters	Bağlantı parametrelerini içeren metin.
AlarmState	Cihazın tag'lerine tanımlı alarmların durumu: -1 = alarm yok, 0 = alarm ortadan kalktı, 1 = alarm koşulu kalktı, reset bekliyor, 2 = alarm onaylandı, 3 = yeni alarm.
ChangedTime	Cihazın tag'lerinden en son güncellenenin zamanı. Cihazda tag yoksa 0001-01-01T00:00:00 döner.
IsOutOfDate	Cihaz tanımı değiştirilmiş ve cihazın yeniden başlatılması gerekiyorsa true.
IsConnected	Bu uçta kullanılmaz, her zaman false döner.
Tags	Bu uçta kullanılmaz, her zaman null döner. Tag değerleri için aşağıdaki uçları kullanın.

ConnectionType değerleri:

Değer	Metin	Değer	Metin
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

Tabloda olmayan değerler bu kılavuzda anlatılmayan eski bağlantı tiplerine aittir.

Cihazın tag değerleri

Bir cihazın tüm tag'lerinin anlık değerleri üç uçla alınabilir:

Uç	Açıklama
GET /api/Monitor/Devices/TagsByName/{deviceName}	Cihaz adıyla. Ad büyük/küçük harf duyarlıdır.
GET /api/Monitor/Devices/TagsById/{deviceId}	Cihaz kimliğiyle.
GET /api/Monitor/Devices/Tags/ByDeviceIds?deviceIds=3,5	Birden fazla cihazın tag'leri tek listede. Kimlikler virgülle ayrılabilir veya deviceIds=3&deviceIds=5 biçiminde tekrarlanabilir. Sayı olmayan bir değer HTTP 400 döner.

Cihaz bulunamazsa hata dönmez; Payload boş bir liste olur.

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
}

Alan	Açıklama
Id	Tag'in tekil kimliği.
DeviceId	Tag'in bağlı olduğu cihazın kimliği.
DeviceName	Tag'in bağlı olduğu cihazın adı.
Name	Tag adı.
Address	Tag'in cihazdaki adresi.
FullName	Kanal.Cihaz.Tag biçimindeki tam ad. Sistemde tekildir.
Value	Tag'in son okunan değeri. Tag'in veri tipine göre sayı, mantıksal değer veya metin olabilir.
ChangedTime	Değerin son güncellendiği zaman.
Quality	Okuma kalitesi: 0 = Bad (okunamıyor), 1 = Good (sağlıklı), 2 = Uncertain (belirsiz, örneğin henüz okunmadı).
QualityStr	Quality değerinin metin karşılığı.
IsAlarmDefined	Tag'e alarm tanımlıysa true.
IsLogDefined	Tag'e log (arşiv) tanımlıysa true.
Unit	Tag'e tanımlı birim.
Description	Tag açıklaması.

Tek bir tag'in değeri

Uç	Açıklama
GET /api/Monitor/Tag/{tagFullName}	Tam adla (Kanal.Cihaz.Tag).
GET /api/Monitor/TagById/{tagId}	Tag kimliğiyle.

Payload yukarıdaki tag nesnesiyle aynı yapıdadır. Tag bulunamazsa Success değeri true, Payload değeri null olur. Tam ad URL içinde gönderildiği için boşluk ve özel karakterleri URL kodlamasıyla (ör. boşluk için %20) yazın.

Arşiv verileri

Arşiv uçları, log (arşiv) tanımı yapılmış tag'lerin kayıtlı verilerini sorgular. Sorgularda tag kimliği değil, log tanımının kimliği (Ids) kullanılır. Log tanımları için Log (Arşiv) Tanımları sayfasına bakın.

Log tanımı kimliğini bulma

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

{name} olarak tag'in tam adı (Kanal.Cihaz.Tag) verilmelidir. Yalnız tag adı da kabul edilir, ancak aynı adlı birden fazla tag varsa yalnız ilk bulunanın log tanımları döner. Tag bulunamazsa ErrorCode değeri 3101 olur.

Payload, tag'e ait log tanımlarının listesidir. Sorgularda kullanılacak alanlar:

Alan	Açıklama
Id	Log tanımının kimliği. Arşiv sorgularındaki Ids parametresine yazılır.
TagId	Log tanımının bağlı olduğu tag'in kimliği.
Desc	Log tanımının açıklaması.

Sorgu sınırları

Arşiv sorguları sunucuyu korumak için sınırlandırılır: sorgu süresi, tek sorgudaki log tanımı sayısı, dönen satır sayısı ve ham arşiv sorgusunun tarih aralığı sınırlıdır. API anahtarıyla yapılan sorgulara daha dar sınırlar uygulanır.

API anahtarıyla arşiv sorgularını aynı anda değil sırayla gönderin; eşzamanlı gönderilen sorgu 1203 koduyla reddedilebilir.

Sunucuda geçerli olan sınırlar şu uçla okunabilir:

GET /api/History/QueryLimits

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

Profile değeri API anahtarıyla yapılan isteklerde ApiKey, kullanıcı oturumunda Interactive olur.

Tarih biçimi

StartDate ve EndDate ISO 8601 biçiminde verilir, örneğin 2026-10-15T08:00:00Z veya 2026-10-15T08:00:00+03:00. Sorgu dizesinde yyyy-MM-dd HH:mm ve yyyy-MM-dd HH:mm:ss biçimleri de kabul edilir. Saat dilimi belirtilmezse sunucunun yerel saati kabul edilir. Sorgu dizesinde + karakterini %2B olarak kodlayın. Cevaplardaki arşiv zamanları UTC (Z) olarak döner.

Ham arşiv kayıtları

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

Belirtilen tarih aralığındaki tüm kayıtları örnekleme yapmadan döner. POST ile aynı alanlar JSON gövdede gönderilir.

Parametre	Açıklama
Ids	Log tanımı kimlikleri. Sorgu dizesinde virgülle ayrılabilir (Ids=1,2) veya tekrarlanabilir (Ids=1&Ids=2).
StartDate	Başlangıç zamanı. Zorunludur.
EndDate	Bitiş zamanı. Zorunludur; tarih aralığı ham arşiv sınırını aşamaz.

Cevap, örneklenmiş arşiv cevabıyla aynı tablo yapısındadır.

Örneklenmiş arşiv

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

Kayıtları SampleTime ile belirlenen aralıklara böler ve her aralık için ValueType ile seçilen hesaplamayı yapar. Örnekleme süresi kayıt aralığına eşit seçilirse kayıtlar ham haline yakın döner.

Parametre	Açıklama	Varsayılan	Değerler
Ids	Log tanımı kimlikleri. En az bir pozitif kimlik zorunludur.
StartDate	Başlangıç zamanı. Zorunludur.
EndDate	Bitiş zamanı. Zorunludur; StartDate değerinden önce olamaz.
SampleTime	Saniye cinsinden örnekleme aralığı.	18600	0'dan büyük
ValueType	Her aralıkta yapılacak hesaplama.	0	0 = Min, 1 = Max, 2 = Avg (ortalama), 3 = Sum (toplam), 4 = Count (kayıt sayısı)
FillType	Kaydı olmayan aralıkların nasıl doldurulacağı.	0	0 = NULL (boş bırakılır), 1 = PREV (önceki değer), 2 = LINEAR (doğrusal ara değer), 3 = X (FillValue ile doldurulur)
FillValue	FillType = 3 iken kullanılacak tam sayı değer.	0
AlignToCalendar	true ise aralıklar takvime (IANATimeZone saat dilimine göre saat, gün, ay başlangıçlarına) hizalanır; false ise aralıklar ilk kaydın zamanından başlar.	true	true, false
CalculateConsumption	true ise ValueType yerine log tanımındaki tüketim ayarlarına göre her aralığın tüketimi hesaplanır: anlık değerler toplanır, kümülatif sayaçlarda aralık öncesindeki son değerden başlayarak ardışık değerler arasındaki artışlar toplanır (sayaç sıfırlamasında adım 0 sayılır); sonuç log tanımındaki çarpan ve bölenle ölçeklenir.	false	true, false
IANATimeZone	Takvim hizalaması için saat dilimi, örneğin Europe/Istanbul. Boş bırakılırsa sunucunun saat dilimi kullanılır.

Sorgu dizesinde ValueType ve FillType sayı veya ad olarak (ValueType=Max) yazılabilir; JSON gövdede sayı olarak gönderilmelidir.

Örnek sorgu (yarım saatlik aralıklarla en büyük değer):

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: <sunucu>
ApiKey: <api_anahtarı>

Aynı sorgu POST ile gönderildiğinde gövde:

{
  "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"
}

Cevap:

{
  "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
}

Payload içindeki alan adları küçük harfle yazılır:

Alan	Açıklama
columns	Sütun listesi. İlk sütun ChangedTime, sonraki her sütun bir log tanımıdır; sütun adı log tanımının kimliğidir.
dataset	Satırlar. Her satırın ilk elemanı UTC zaman, sonraki elemanları columns sırasıyla log tanımlarının değerleridir. O zamanda değeri olmayan log tanımı için null döner.
count	Satır sayısı.
query	Kullanılmaz, boş döner.

Tüketim hesabı

POST /api/History/TagsSampleByForPivotDiffSum

Log tanımlarının belirlenen aralıklardaki tüketim değerlerini, iş merkezi ve proses grubu bilgisiyle birlikte satır satır döner. Gövde örneklenmiş arşiv ile aynı alanları alır; bu uçta CalculateConsumption değeri true gönderilmelidir, aksi halde 3501 kodu döner.

Kümülatif sayaç log tanımlarında ardışık kayıtların farkları toplanır; sayaç sıfırlanması gibi geriye düşüşler 0 sayılır. Diğer log tanımlarında değerler toplanır. Sonuç log tanımındaki çarpan ve bölenle ölçeklenir. Tarih aralığının toplam tüketimini tek değer olarak almak için SampleTime değerini aralığın saniye cinsinden uzunluğuna eşitleyin.

curl -X POST "https://<sunucu>/api/History/TagsSampleByForPivotDiffSum" \
  -H "ApiKey: <api_anahtarı>" \
  -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"
  }'

Cevap:

{
  "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
}

Alan	Açıklama
LogInfoId	Log tanımının kimliği.
Desc	Log tanımının açıklaması ve köşeli parantez içinde birimi. Log tanımında toplam değer birimi girilmişse o, girilmemişse tag'in birimi yazılır.
ChangedTime	Aralığın başlangıç zamanı (UTC).
Value	Aralıktaki tüketim. Kayıt yoksa FillType ayarına göre doldurulur veya null döner.
TaskCenter	Tag'in bağlı olduğu cihazın iş merkezi.
DataGroup	Cihazın iş merkezinin proses grubu; bulunamazsa tag'in bağlı olduğu tag grubu.

Swagger

Sunucuda API dokümantasyonu açıksa tüm uçlar ve şemaları Swagger arayüzünden incelenip denenebilir. API dokümantasyonu varsayılan olarak kapalıdır; açılması ve erişim adresi için sistem entegratörünüze başvurun. Swagger'da Authorize ile ApiKey veya Authorization değeri girilerek istek gönderilebilir.

Sorun giderme

Belirti	Kontrol
401, Lütfen Geçerli Gir API Anahtarı Sağlayın	İstekte ApiKey veya Authorization başlığı olduğunu ve başlık adının doğru yazıldığını kontrol edin.
403, Geçersiz API Anahtarı	Anahtarın eksiksiz kopyalandığını, silinmediğini ve Amaç değerinin SCADA API olduğunu kontrol edin. MCP erişimi anahtarları REST API'de çalışmaz.
API anahtarı gönderildiği halde Geçersiz Giriş Token dönüyor	İstekte ayrıca Authorization başlığı gönderiliyor. Bu başlığı kaldırın.
403, Maksimum Sorgulama Limiti Aşıldı	10 dakikalık pencere dolduktan sonra tekrar deneyin. Sorgulama sıklığını azaltın veya Maksimum İstek Sayısı değerini artırın.
Token ile çalışırken birkaç saat sonra 403, Geçersiz Giriş Token	Erişim token'ının süresi dolmuştur. Token yenileme yapın; yenileme 2106 veya 2108 dönerse yeniden giriş yapın.
/api/Monitor/Devices bazı cihazları döndürmüyor	Kullanıcının veya anahtar sahibinin ilgili proses grubunda yetkisi olduğunu kontrol edin.
Cihaz adıyla sorgu boş liste dönüyor	Cihaz adının büyük/küçük harf dahil birebir yazıldığını ve URL kodlamasını kontrol edin.
Arşiv sorgusu 1203 dönüyor	Log tanımı sayısını, tarih aralığını veya örnekleme sıklığını azaltın; API anahtarıyla arşiv sorgularını aynı anda değil sırayla gönderin. Sınırları GET /api/History/QueryLimits ile kontrol edin.
Arşiv sorgusu 1208 dönüyor	Ham arşiv sorgusunun tarih aralığını daraltın veya örneklenmiş arşiv ucunu kullanın.
Arşiv sorgusu 3501 dönüyor	Ids değerlerinin tag değil log tanımı kimliği olduğunu kontrol edin. Tüketim hesabında CalculateConsumption değerinin true olduğunu kontrol edin.
Arşiv sorgusu 4401 dönüyor	Log veritabanı servisinin çalıştığını kontrol edin.
Arşiv zamanları beklenenden birkaç saat kayık	Cevaplardaki zamanlar UTC'dir. İstekte saat dilimini (Z veya +03:00) açıkça belirtin.
HTTPS isteği sertifika hatası veriyor	Sunucu sertifikasının istemci tarafında güvenilir olduğunu kontrol edin.