REST İstemci

Yaklaşık 6 dk okuma

REST İstemci protokolünde 2WinScada, HTTP/HTTPS API'si olan bir dış sistemden tag değerlerini belirlenen aralıklarla kendisi çeker (pull) ve gerekirse aynı sisteme değer yazar. Dış sistemin veriyi 2WinScada'ya kendisinin göndermesi gerekiyorsa REST Sunucu protokolünü kullanın.

Çalışma özeti:

• Bir cihazın tag'leri Güncelleme Süresi[s] değerine göre gruplanır; her grup için okuma adresine tek bir HTTP isteği gönderilir ve istekte o gruptaki tüm tag adresleri yer alır.
• Gelen JSON yanıtında tag adresleri aranır, bulunan değerler tag'lere yazılır.
• Bir tag'e değer yazıldığında yazma adresine JSON gövdeli bir istek gönderilir.
• Okuma ve yazma isteklerinde zaman aşımı 30 saniyedir; okuma yanıtı en fazla 4 MB olabilir.

Lisans

REST İstemci, Standard ve Professional lisans sürümlerinde kullanılabilir; Starter sürümünde kullanılamaz. 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 RestClient seçilir.

Bağlantı Parametereleri sekmesi:

Alan	Açıklama	Varsayılan	Aralık
Http İstemcisini Paylaş	İşaretlendiğinde kanaldaki aktif cihazlar aynı anda değil, sırayla sorgulanır; bir cihazın okuma turu bitmeden sıradaki cihaz istek göndermez. Dış sistem eşzamanlı istekleri kaldıramıyorsa kullanın.	İşaretsiz	–
JSON Derinlik Seviyesi	Cihazda Key isimlerini Tag Adresi olarak kullan seçiliyken yanıttaki iç içe nesnelerin ne kadar derine taranacağını belirler.	2	1–15

Cihaz Tanımı

Genel sekmesinde Adı ve Aktif alanları diğer protokollerdeki gibi doldurulur. REST İstemci cihazında ayrıca Parametreler, Okuma ve Yazma sekmeleri bulunur.

Parametreler sekmesi

Başlık Parametreleri tablosu, okuma ve yazma isteklerinin hepsine eklenecek HTTP başlıklarını (header) tanımlar. Tablonun sağ üstündeki + butonuyla yeni satır eklenir; ilk sütuna başlık adı, ikinci sütuna değeri yazılır.

Yetkilendirme gerektiren API'lerde gerekli bilgi bu tabloya başlık olarak girilir. Örnekler:

Başlık adı	Değer
Authorization	Bearer <erişim-anahtarı>
Authorization	Basic <kullanıcı:şifre metninin Base64 karşılığı>
X-Api-Key	<api-anahtarı> (başlık adı, API belgesinde yazdığı gibi girilir)

Kaydedilmiş bir cihaz açıldığında adı kimlik bilgisi taşıyan başlıkların (Authorization, API anahtarı, token, cookie vb.) değeri ******** olarak görünür. Değiştirmeden kaydetmek değeri korur, yeni değer yazmak değiştirir, başlığı silmek değeri siler. Izgarada kopyala/yapıştır ile oluşturulan cihazda bu değerler kopyalanmaz; yeniden girilmelidir.

WARNING

Gövdeli isteklerde Content-Type: application/json otomatik gönderilir; bu başlığı tabloya eklemeniz gerekmez. Tabloya eklenen içerik başlıkları (Content- ile başlayanlar) isteğin gövdesine uygulanır. Geçersiz veya çakışan bir başlık atlanır ve servis günlüğüne uyarı yazılır; cihazın diğer okuma ve yazmaları etkilenmez.

Okuma sekmesi

Okuma İsteği grubunda okumanın yapılacağı adres ve isteğin biçimi belirlenir.

Alan	Açıklama	Seçenekler
Url	Okuma yapılacak API adresi. Adrese yazılan sabit sorgu parametreleri (? sonrası) korunur.	–
İstek Metodu	Okuma isteğinin HTTP metodu.	GET (varsayılan), PUT, POST
Param Tipi	Tag adreslerinin isteğe nasıl ekleneceği.	None, Query (varsayılan), Body

Param Tipi seçenekleri:

• None: İsteğe tag adresi eklenmez; API tüm değerleri parametresiz döndürüyorsa kullanılır.
• Query: Gruptaki her tag adresi, Okuma İsteği Parametreleri tablosundaki TagAddress satırında yazan anahtar adıyla sorgu parametresi olarak eklenir. Adres uzunluğu sunucu ve proxy sınırlarına takılabileceğinden çok sayıda tag için Body tercih edilebilir.
• Body: Tag adresleri JSON gövdesinde bir dizi olarak gönderilir.

Sekmenin alt kısmında Okuma İsteği, Cevap Şablonu ve Değer Şablonu sekmeleri bulunur.

Okuma İsteği sekmesi: Okuma İsteği Parametreleri tablosu, okuma isteğine eklenecek parametreleri tanımlar. İlk sütundaki listeden parametre seçilir, ikinci sütuna değeri yazılır.

• TagAddress: Tag adreslerinin hangi anahtar adıyla gönderileceğini belirtir. Adres gönderilecekse bu satır tanımlanmalıdır.
• Period, SampleTime, ValueType, FillType, FillValue, StartTime, EndTime, AlignToCalendar, CalculateConsumption, IANATimeZone, PeriodCount: Bu satırlar isteğe, listedeki adla ve ikinci sütundaki değerle ek parametre olarak eklenir. Kullanılan API bu parametreleri bekliyorsa tanımlayın.

Örneğin TagAddress değeri ids olan bir cihazda, adresleri Kazan.Sicaklik ve Kazan.Basinc olan iki tag için istekler şöyle oluşur.

Param Tipi Query iken:

GET https://<api-sunucusu>/read?ids=Kazan.Sicaklik&ids=Kazan.Basinc

Param Tipi Body iken istek gövdesi:

{ "ids": ["Kazan.Sicaklik", "Kazan.Basinc"] }

Cevap Şablonu sekmesi: Cevap Parametreleri tablosu, yanıtta değerlerin bulunduğu yeri tanımlar. En fazla iki satır eklenebilir.

• Values: Değer listesini içeren, yanıtın kök düzeyindeki alanın adı (ör. readResults). Bu satır yoksa veya alan yanıtta bulunamazsa yanıtın kökü kullanılır.
• TimeStamp: Bu sürümde kullanılmaz.

Değer Şablonu sekmesi: Değer listesindeki her elemanın nasıl okunacağını tanımlar.

Key isimlerini Tag Adresi olarak kullan seçeneği, yanıtta tag adresi alan adı, tag değeri de o alanın değeri olarak geliyorsa (ör. { "Kazan.Sicaklik": 81.5 }) işaretlenir. Bu durumda Değer Cevabı Şablonu tablosu kullanılmaz; iç içe nesneler kanaldaki JSON Derinlik Seviyesi ayarına göre taranır. Aynı alan adı yanıtta birden fazla geçmemelidir; en güvenilir sonuç için değerleri yanıtta tek düzeyde tutun.

Seçenek işaretsizken değer listesinin bir dizi olması beklenir ve Değer Cevabı Şablonu tablosu doldurulur:

Satır	Açıklama
TagAddress	Dizi elemanında tag adresini taşıyan alanın adı. Zorunludur.
TagValue	Dizi elemanında değeri taşıyan alanın adı. Zorunludur.
TagChangeTime	Bu sürümde kullanılmaz; değerin zamanı olarak okuma zamanı kaydedilir.
TagQuality	Bu sürümde kullanılmaz.

Dizi elemanları nesne değil de dizi ise (ör. ["Kazan.Sicaklik", 81.5]), alan adı yerine elemanın sıra numarası (0'dan başlayarak) yazılır.

Yukarıdaki şablona (Values = readResults, TagAddress = id, TagValue = v) uyan bir yanıt örneği:

{
  "readResults": [
    { "id": "Channel1.Device1.tag1", "s": true, "r": "", "v": 263, "t": 1442606724647 }
  ]
}

Bu yanıtla Channel1.Device1.tag1 adresli tag'e 263 değeri yazılır.

Yazma sekmesi

Dış sistem yazmayı destekliyorsa Yazma İsteği grubu doldurulur. Url boş bırakılırsa tag'lere yazma yapılmaz.

Alan	Açıklama	Seçenekler
Url	Yazma yapılacak API adresi.	–
İstek Metodu	Yazma isteğinin HTTP metodu.	PUT, POST (varsayılan)
Param Tipi	Listede yer alır, ancak yazma isteği her durumda JSON gövdesiyle gönderilir.	None (varsayılan), Body

Yazma İsteği Parametreleri tablosunda satır eklenip silinemez, yalnızca değerler değiştirilebilir:

• TagAddress: Tag adresinin gönderileceği alan adı. Zorunludur.
• TagValue: Yazılacak değerin gönderileceği alan adı. Zorunludur.

TagAddress = id ve TagValue = v iken Channel1.Device1.tag1 tag'ine 42 yazıldığında gönderilen gövde:

[{ "id": "Channel1.Device1.tag1", "v": 42 }]

Bool tag'ler 0 veya 1 olarak gönderilir. Her yazma tek bir istekle bir kez gönderilir; başarısız yazma tekrarlanmaz; HTTP hata kodu Cihaz Durumları ekranındaki Hata alanında görülür.

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. REST İstemci için önemli alanlar:

Alan	Açıklama
Adres	Dış sistemin tag'i tanıdığı kimlik (1–250 karakter). Okuma isteğinde bu değer gönderilir ve yanıttaki adres alanıyla büyük/küçük harf duyarlı olarak birebir eşleştirilir. Yukarıdaki örnekte adres Channel1.Device1.tag1 olmalıdır.
Veri Tipi	Okunan değere uygun tip seçilir; değer bu tipe dönüştürülemezse tag güncellenmez.
Güncelleme Süresi[s]	Okuma aralığı. Aynı süreye sahip tag'ler tek istekte okunur.

Sorun giderme

Belirti	Kontroller
Cihaz ve gruptaki tüm tag'ler Bad	API'nin 2xx dışında bir HTTP kodu döndürüp döndürmediğini, Url değerini, ağ ve güvenlik duvarı erişimini, sertifikayı ve yetkilendirme başlıklarını kontrol edin. Yanıtın 30 saniye içinde gelmesi, geçerli JSON olması ve 4 MB'ı aşmaması gerekir.
Okuma hiç yapılmıyor	Url değerinin dolu ve geçerli olduğunu, servis günlüğünde atlanan başlık uyarısı olup olmadığını kontrol edin. Http İstemcisini Paylaş seçiliyse aynı kanaldaki yavaş bir cihaz diğerlerini bekletebilir.
Tag kalitesi Uncertain	Tag adresi yanıtta bulunamadı. Adres değerinin yanıttakiyle büyük/küçük harf dahil aynı olduğunu, Values ve TagAddress alan adlarını kontrol edin.
Tag değeri güncellenmiyor	TagValue alan adını ve Veri Tipi seçimini kontrol edin.
Yazma çalışmıyor	Yazma Url değerini, İstek Metodu seçimini, TagAddress / TagValue alan adlarını ve cihaz durumundaki son hata mesajını kontrol edin.