REST Sunucu

Yaklaşık 8 dk okuma

REST Sunucu protokolü, IoT cihazlarının, bulut servislerinin ve diğer yazılımların tag değerlerini HTTP POST isteğiyle 2WinScada'ya kendilerinin göndermesini (push) sağlar. REST İstemci protokolünden farklı olarak 2WinScada dış sistemi sorgulamaz; dış sistem veriyi istediği aralıkla 2WinScada'nın veri alım ucuna iletir.

Her REST Sunucu cihazı ayrı bir veri kaynağını temsil eder. Dış sistem her istekte cihaz kimliğini ve o cihaz için üretilmiş cihaz anahtarını HTTP başlığında gönderir; kimlik doğrulanırsa gövdedeki değerler cihazın tag'lerine yazılır.

Lisans

REST Sunucu, Standard ve Professional lisans sürümlerinde kullanılabilir; Starter sürümünde kullanılamaz. Lisans REST entegrasyonunu içermiyorsa veri alım ucu istekleri 4900 hata koduyla reddeder. Ayrıntılar için Lisans sayfasına bakın.

Kanal Tanımı

Yeni kanal penceresinin Genel sekmesinde Adı girilir ve Bağlantı Tipi olarak RestServer seçilir.

REST Sunucu kanalında yalnız Genel sekmesi bulunur; kanalın bağlantı parametresi yoktur. Kanal dış sisteme bağlanmaz, veri alım ucuna gelen istekleri kabul eder. Kimlik doğrulama ve gövde ayarları her cihazın kendi Parametreler sekmesinde yapılır.

Cihaz Tanımı

Genel sekmesinde Adı ve Aktif alanları diğer protokollerdeki gibi doldurulur. Veri kabul edilmesi için cihazın Aktif olması gerekir.

Parametreler sekmesinde Rest Server Veri Alımı grubu bulunur:

• Rest Server Veri Alımı Aktif: Cihazın veri alımını açar (varsayılan: işaretli). İşaretsizse bu cihaza gelen istekler 4603 hata koduyla reddedilir.

Grubun altında Kimlik ve Anahtar, Payload Parse Ayarları ve No-Data Watchdog sekmeleri yer alır.

Kimlik ve Anahtar

Alan	Açıklama
Harici Cihaz Kimliği	Dış sistemin bu cihazı tanıtmak için X-Device-Id başlığında göndereceği kimlik (ör. kazan-dairesi-01). Büyük/küçük harf duyarsız eşleştirilir. Her cihaz için tahmin edilmesi zor bir Harici Cihaz Kimliği girmeniz önerilir. Boş bırakılırsa X-Device-Id başlığına cihazın sistemdeki sayısal kimliği yazılmalıdır.
Cihaz Anahtarı	Dış sistemin X-Device-Key başlığında göndereceği gizli anahtar. Alan maskelenmiş gösterilir; altındaki yardım metninde belirtildiği gibi anahtarı paylaşmak için kopyalama butonu kullanılır. Anahtar boşsa bu cihaza hiçbir istek kabul edilmez.
Anahtar Üret	Sunucudan rastgele yeni bir anahtar alır ve Cihaz Anahtarı alanına yazar. Kayıtlı bir cihazda Harici Cihaz Kimliği boşsa bu alana cihazın sayısal kimliği de yazılır.
Anahtarı Kopyala	Anahtarı görüntülemeden panoya kopyalar.

Anahtar oluşturma ve yenileme:

1. Anahtar Üret butonuna tıklayın. Üretilen anahtar dev_ ile başlar.
2. Anahtarı Kopyala ile anahtarı kopyalayıp dış sistemin yapılandırmasına güvenli biçimde aktarın.
3. Cihaz formunu Kaydet ile kaydedin. Yeni anahtar kayıttan sonra geçerli olur; önceki anahtarla gelen istekler bu andan itibaren 4600 hata koduyla reddedilir.

WARNING

Cihaz anahtarını e-posta, ekran görüntüsü veya sorgu parametresi gibi açık kanallarla paylaşmayın; anahtar, isteği gönderen sistemin o cihaza veri yazmasına izin verir. Anahtarın ağda açık metin taşınmaması için veri alım ucuna HTTPS ile erişin. Bir cihaz kopyalandığında Harici Cihaz Kimliği ve Cihaz Anahtarı da kopyalanır; kopyada yeni bir anahtar üretin ve kimliği değiştirin.

Payload Parse Ayarları

Bu sekme, gövdedeki serbest yapılı JSON'un tag değerlerine nasıl çevrileceğini tanımlar. Gövde biçimlerinin örnekleri Veri Gönderme bölümündedir.

Alan	Açıklama	Varsayılan
Liste JSON Yolu	Gövdede tag listesini veya tag nesnesini içeren alanın noktayla ayrılmış yolu (ör. data.items). Yolun ilk bölümü gövdenin kök düzeyindeki bir alan olmalıdır; kökün kendisi gösterilemez. Veri alımı aktifken zorunludur.	Boş
Tag Adres Anahtarı	Liste elemanında tag adresini taşıyan alanın adı. Tag adresi nesne key'lerinde işaretsizken zorunludur.	sourceKey
Tag Değer Anahtarı	Liste elemanında değeri taşıyan alanın adı. Zorunludur.	value
Tag Zaman Anahtarı	Liste elemanında zaman damgasını taşıyan alanın adı. İsteğe bağlıdır.	ts
Ondalık Ayırıcı	Sayısal tag'lere metin olarak gelen değerlerdeki ondalık ayırıcı: Nokta (.) veya Virgül (,).	Nokta (.)
Tag adresi nesne key'lerinde	İşaretlenirse Liste JSON Yolu ile gösterilen nesnenin alan adları tag adresi, alan değerleri tag değeri kabul edilir.	İşaretsiz

Alan adları büyük/küçük harf duyarsız eşleştirilir.

TIP

Yalnızca Metrics veya Tags gövde biçimini kullanacaksanız Liste JSON Yolu yine de doldurulmalıdır; gövdenizde bulunmayan bir ad (ör. items) girebilirsiniz.

No-Data Watchdog

Dış sistemden belirli bir süre veri gelmediğinde cihazın ve tag'lerin kalitesini düşürür.

Alan	Açıklama	Varsayılan	Aralık
No-Data Watchdog Aktif	Watchdog'u açar. Kapalıyken veri gelmese de cihaz kalitesi Good olarak kalır.	İşaretsiz	–
No-Data Timeout [sn]	Son kabul edilen veriden bu kadar saniye sonra kalite düşürülür. Servis başladıktan sonra hiç veri gelmemişse kalite hemen düşürülür.	30	1–86400
No-Data Kalitesi	Süre aşıldığında cihaza ve tag'lere atanacak kalite: Bad veya Uncertain.	Uncertain	–
Veri gelince kaliteyi Good yap	İşaretliyse kabul edilen her istekten sonra cihazın ve tüm tag'lerinin kalitesi Good yapılır. İşaretsizse yalnızca değer gelen tag'ler Good olur, cihaz kalitesi düşük kalır.	İşaretli	–

Tag Tanımı

Kanal ağacından cihaz seçilir ve sağdaki tag tablosunda yeni tag eklenir. Genel alanlar Tag Yönetimi sayfasındaki gibi doldurulur.

Gelen her değer, yalnızca kimliği doğrulanan cihazın tag'leri arasında şu sırayla eşleştirilir:

1. Gövdede TargetTagId verilmişse, bu sayısal kimliğe sahip tag.
2. Gelen adres (ör. sourceKey değeri veya Metrics alan adı) ile Adres alanı aynı olan tag.
3. Bulunamazsa, gelen adres ile tag adı aynı olan tag.

Adres ve ad karşılaştırması büyük/küçük harf duyarsızdır; baştaki ve sondaki boşluklar dikkate alınmaz. Eşleşmeyen değerler reddedilir ve yanıttaki Errors listesine yazılır.

Veri Tipi gelen değere uygun seçilmelidir; dönüştürülemeyen değer reddedilir. Güncelleme Süresi[s] alanı REST Sunucu'da kullanılmaz; tag, istek geldiği anda güncellenir.

Veri Gönderme

İstek

Özellik	Değer
Adres	https://<sunucu>/api/RestIngest/Telemetry
Metot	POST
Content-Type başlığı	application/json
X-Device-Id başlığı	Harici Cihaz Kimliği veya cihazın sayısal kimliği
X-Device-Key başlığı	Cihaz Anahtarı

<sunucu>, 2WinScada web arayüzünün adresidir; uç nokta web arayüzüyle aynı HTTPS adresi üzerinden yayınlanır. Web arayüzü varsayılandan farklı bir portta yayınlanıyorsa portu da ekleyin (https://<sunucu>:<port>). Uç nokta kullanıcı oturumu veya API anahtarı istemez; kimlik doğrulama yalnızca cihaz anahtarıyla yapılır.

Örnek istek:

POST /api/RestIngest/Telemetry HTTP/1.1
Host: <sunucu>
Content-Type: application/json
X-Device-Id: kazan-dairesi-01
X-Device-Key: <cihaz-anahtarı>

{
  "MessageId": "kazan-0001",
  "DeviceTime": "2026-10-15T08:30:00Z",
  "Metrics": {
    "Kazan1_Run": 1,
    "Kazan1_Temp": 45.2
  }
}

Aynı istek curl ile:

curl -X POST "https://<sunucu>/api/RestIngest/Telemetry" \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: kazan-dairesi-01" \
  -H "X-Device-Key: <cihaz-anahtarı>" \
  -d '{"Metrics":{"Kazan1_Run":1,"Kazan1_Temp":45.2}}'

Gövde biçimleri

Gövde bir JSON nesnesi olmalıdır (kök düzeyde dizi kabul edilmez). Gövdede şu sabit alanlar kullanılabilir; alan adları büyük/küçük harf duyarsızdır:

Alan	Açıklama
MessageId	İsteğe bağlı mesaj kimliği (en fazla 200 karakter). Aynı cihaz için aynı kimlikle 24 saat içinde gelen ikinci istek işlenmez; yanıtta IsDuplicate true döner. Bu kayıt bellekte tutulur, servis yeniden başlatılınca sıfırlanır.
DeviceTime	İsteğe bağlı, ISO 8601 biçiminde zaman damgası (ör. 2026-10-15T08:30:00Z). Kendi zamanı olmayan değerler için kullanılır.
Metrics	Alan adı tag adresi, değeri tag değeri olan nesne.
Tags	SourceKey veya TargetTagId, Value ve isteğe bağlı Ts alanlarından oluşan dizi.

Bu alanların dışında kalan her alan, Payload Parse Ayarları'na göre işlenir. Bir istekte en az bir değer kaynağı bulunmalıdır; birden fazla biçim aynı istekte birlikte kullanılabilir.

Metrics biçimi: Tüm değerler DeviceTime (yoksa sunucu zamanı) ile kaydedilir.

{
  "DeviceTime": "2026-10-15T08:30:00Z",
  "Metrics": { "Kazan1_Run": 1, "Kazan1_Temp": 45.2 }
}

Tags biçimi: Her eleman kendi zaman damgasını taşıyabilir. TargetTagId verilirse tag sayısal kimliğiyle eşleştirilir.

{
  "Tags": [
    { "SourceKey": "Kazan1_Run", "Value": 1, "Ts": "2026-10-15T08:30:00Z" },
    { "TargetTagId": 1234, "Value": 45.2 }
  ]
}

Liste biçimi: Liste JSON Yolu data.items iken ve diğer ayarlar varsayılandayken:

{
  "data": {
    "items": [
      { "sourceKey": "Kazan1_Run", "value": 1, "ts": "2026-10-15T08:30:00Z" },
      { "sourceKey": "Kazan1_Temp", "value": 45.2 }
    ]
  }
}

Yol bir dizi yerine tek bir nesneyi gösteriyorsa bu nesne tek bir değer olarak okunur.

Adresler alan adında: Liste JSON Yolu data iken ve Tag adresi nesne key'lerinde işaretliyken. Alanın değeri doğrudan tag değeri olabilir ya da Tag Değer Anahtarı ve Tag Zaman Anahtarı alanlarını içeren bir nesne olabilir:

{
  "data": {
    "Kazan1_Run": 1,
    "Kazan1_Temp": { "value": 45.2, "ts": "2026-10-15T08:30:00Z" }
  }
}

Değerler ve zaman damgası

• Değer JSON sayısı, metin veya true / false olabilir. null, nesne veya dizi değerleri reddedilir.
• Sayısal tag'lere metin olarak gelen değerlerde ondalık ayırıcı Ondalık Ayırıcı ayarına göre yorumlanır; binlik ayırıcı kullanılmamalıdır. JSON sayısı olarak gönderilen değerler bu ayardan etkilenmez.
• Zaman damgaları ISO 8601 biçiminde metin olarak gönderilmelidir. Unix zaman damgası (sayı) desteklenmez: liste ve alan adı biçimlerinde yok sayılır, DeviceTime veya Ts alanında ise isteğin tamamının reddedilmesine yol açar.
• Bir değerin zamanı sırasıyla elemanın kendi zaman damgasından, DeviceTime alanından veya sunucu zamanından alınır.
• Tek bir değerin JSON gösterimi 262.144 karakteri aşamaz; aşan değer reddedilir.

Yanıt

İstek uç noktaya ulaşıp işlendiğinde, kimlik doğrulama hataları dahil yanıt HTTP 200 kodu ile döner; sonuç gövdedeki Success ve ErrorCode alanlarından değerlendirilir. Gövde geçerli JSON değilse veya sabit alanlardan biri beklenen tipte değilse HTTP 400, Content-Type JSON değilse HTTP 415 döner.

Başarılı yanıt örneği:

{
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0,
  "Payload": {
    "DeviceIdentifier": "kazan-dairesi-01",
    "DeviceId": 12,
    "MessageId": "kazan-0001",
    "IsDuplicate": false,
    "AcceptedCount": 2,
    "RejectedCount": 0,
    "Errors": []
  }
}

Success değeri true olsa da bazı değerler reddedilmiş olabilir. AcceptedCount kabul edilen, RejectedCount reddedilen değer sayısıdır; Errors listesi reddedilme nedenlerini içerir (ör. Tag mapping not found, Type conversion failed, Payload item too large).

Hata kodları:

ErrorCode	Anlamı
1101	X-Device-Id veya X-Device-Key başlığı eksik.
4600, 4602	Cihaz kimliği veya cihaz anahtarı geçerli değil ya da cihaz çalışma zamanında yüklü değil.
4601	Gövde geçersiz: değer kaynağı yok, Tags elemanında adres/kimlik veya değer eksik, MessageId 200 karakteri aşıyor ya da gövdeden hiç değer çıkarılamadı.
4603	Cihaz pasif, Rest Server Veri Alımı Aktif işaretsiz ya da cihaz şu anda veri kabul etmiyor.
4900	Lisans REST entegrasyonunu içermiyor.
1000	Beklenmeyen hata; ayrıntı servis logundadır.

Sorun giderme

Belirti	Kontroller
1101 dönüyor	X-Device-Id ve X-Device-Key başlık adlarının doğru yazıldığını ve boş olmadığını kontrol edin.
4600 veya 4602 dönüyor	X-Device-Id değerinin Harici Cihaz Kimliği ile aynı olduğunu ve cihazın RestServer tipindeki bir kanalda bulunduğunu kontrol edin. Aynı Harici Cihaz Kimliği'nin birden fazla cihazda kullanılmadığından emin olun. Dış sistemdeki anahtarın, cihazda kayıtlı son anahtarla aynı olduğunu kontrol edin; anahtar yenilendiyse cihazın kaydedildiğinden ve dış sistemin güncellendiğinden emin olun. Cihaz yeni eklendiyse çalışma zamanına yüklendiğinden emin olun.
4603 dönüyor	Cihazın Aktif ve Rest Server Veri Alımı Aktif seçimlerini kontrol edin; değişiklikten sonra cihazın çalışma zamanına yüklendiğinden emin olun.
4601 dönüyor	Gövdenin bir JSON nesnesi olduğunu, Liste JSON Yolu'nun gövdedeki gerçek yolu gösterdiğini ve Tag Adres Anahtarı / Tag Değer Anahtarı adlarının gövdedeki alan adlarıyla aynı olduğunu kontrol edin.
Tag mapping not found hatası	Gelen adresin tag'in Adres alanıyla veya tag adıyla aynı olduğunu ve tag'in aynı cihaza ait olduğunu kontrol edin.
Type conversion failed hatası	Değerin tipini, tag'in Veri Tipi seçimini ve metin olarak gelen sayılarda Ondalık Ayırıcı ayarını kontrol edin.
HTTP 400 dönüyor	Gövdenin geçerli JSON olduğunu, DeviceTime ve Ts alanlarının ISO 8601 metin olduğunu ve Tags alanının dizi olduğunu kontrol edin.
Tag kalitesi Uncertain veya Bad'e düşüyor	No-Data Watchdog açıksa veri gönderme aralığının No-Data Timeout [sn] değerinden kısa olduğunu kontrol edin.