MERKEZ YAZILIM API Bilgileri Bu dökümanın amacı, Merkez yazılımın izleme istasynlarından veri alabilmesini sağlayabilmek için gerekli API bilgilerini sunmaktır. Bu dküman, T.C. Çevre ve Şehircilik Bakanlığı tarafından 15.09.2014 tarihinde hazırlanmıştır ve 28 Ekim 2014 tarihinde güncellenmiştir. Revizynlar 2. Sayfada yer alan status cde larında yer alan 9999 metni -9999 larak değiştirildi. 4.1 maddesi düzeltildi. 4.10 Lgbk kısmı düzeltildi.
API Bilgileri 1. API Bağlantı Bilgileri Merkez iletişim mdülü API a HTTP/1.1 request i göndererek veri srgulama yapacaktır. API endpint güvenliği sağlamak amacıyla bağlantı esnasında RFC 2617 de tanımlanan Basic access authenticatin ile kullanıcı adı/şifre dğrulamasına izin verebilir. 2. Veri frmatı API a yapılan srguların cevabı RFC 7159 ve ECMA-404 te tanımlanan JSON (JavaScript Object Ntatin) frmatında lacaktır. Aksi belirtilmedikçe, tüm string alanlar en fazla 50 karakter lacaktır. 3. Veri Status Kdları Verilere ait status kdları aşağıda yer alan tablda verilmiştir: Status Kdu Status Kd Adı Açıklama 0 Veri Yk Veri tplama ve kayıt sisteminin çalışmadığı durum. Bu durumda ölçüm verisi -9999 larak yazılabilir. 1 Geçerli Veri Geçerli Ölçüm Verisi.(Yönetmelikte geçerli kılınan 6 veriden 4 tanesinin geçerli lduğu durumda verinin durum bilgisi 1 larak tanımlanacaktır. 2 Kayıt Kapalı Cihazın ölçüm verisi rtalamaya katılmaması için yazılım prgramı üzerinden kapatıldığında. 3 Yetersiz Ortalama Veri rtalama alma kriteri yetersiz. 4 Geçersiz Ölçüm verisinin geçersiz lduğu durum. Cihazın ölçüm kanalının Alarm durumu 5 Kal Sıfır Cihaz sıfır gazı ile ayar/kntrl yaparken ölçüm kanalının durum bilgisi 6 Kal Span Cihaz span gazı ile ayar/kntrl yaparken ölçüm kanalının durum bilgisi 7 Kalibrasyn Limit Dışı Kalibrasyn uyarı eşiği. Ölçüm kanalındaki veriler durum larak "7" de kalacak ve kanalın kalibrasyn snrasındaki ölçüm verileri rtalamaya katılacaktır. Ancak ar darda 5 defa bu kanal için yapılan KGS3 kntrlünde tekrarlanan Kalibrasyn Limit Dışı " durumu lursa ölçüm kanalı "10" durumuna geçecek ve kalibrasyn hatası " lacaktır. Ölçüm kanalı bu duruma geçtiğinde değerler geçersiz sayılacaktır. 8 İletişim Hatası Cihaz ölçüm kanalından gelen veride srun lduğunda yada veri gelmediğinde kanalın durum bilgisi 9 Kalibrasyn Durumu 10 Kalibrasyn Hatası Kalibrasyn uyarı eşiklerinin aşılması durumunda verinin durumu kalibrasyn hatası larak işaretlenecek ve bir snraki kalibrasyna kadar bu durum ölçüm kanalı için sabit larak kalacak. Cihaz ölçüm kanalı veriyi yazacaktır. 11 Cihaz Bakımı Ölçüm kanalının bağlı lduğu cihazın bakım durumunda kanalın durumu 12 Sistem Bakımı Ölçüm kanalının bağlı lduğu örnekleme sistemi bakımda lduğunda kanalın durumu 13 Prses Kapalı Ölçüm nktasında emisyn üretmiyr ise. 14 Tesis Kapalı Fabrika/tesis kapalı iken 15 Örnekleme Sistemi Hatası Örnekleme sisteminde hata luştuğunda ölçüm kanalının değeri durum değeri 16 Enerji Kesintisi Sistemin elektriği kesildiğinde DAS sistemi çalışıyr ise verilerin durum bilgisi 17 KGS2 KGS2 ve YGT dğrulamaları yapılırken kanalın durum bilgisi
18 Alarm 19 Ölçüm Hazır Değil 20 Standby 21 Rezerve 22 Isıtmalı Hat Sıcaklık Alarm 23 O2 Hatası 24 Nem Hatası 25 Sıcaklık Hatası 26 Basınç Hatası 27 Hız Hatası 28-100 Rezerve Cihazların ölçümünü etkileyecek herhangi bir alarm luştuğunda mevcut durum kdlarından herhangi biri ile eşleştirilemiyrsa alarm larak tanımlanmalıdır. Ölçüm kanalının bağlı lduğu cihaz daha ölçüme hazır hale gelmediğimde (warm up) kullanılması gereken durum. Ölçüm kanalının bağlı lduğu cihaz Ölçüm yapmıyrsa kanalın durumu Isıtmalı hat sıcaklığında alarm luştuğunda ısıtmalı hatta bağlı lan tüm kanalların durumu 22 lmalıdır. Hesaplama kanallarında eğer Oksijen düzeltmesi yapılıyrsa ve ksijen kanalında hata varsa hesaplama kanallarının durum bilgisi 23 lmalıdır.
4. Tarih ve Saat Biçim Bilgisi API a yapılan srgularda kullanılacak tarih frmatı ve API cevabında kullanılacak tarih frmatı ISO 8601 standardında lacaktır. Tarih: 2014-09-14 Karma tarih/saat (UTC): 2014-09-14T23:35:00+00:00 5. API Kmutları API kmutlarına ilişkin özet aşağıda verilmiştir. /v1/site/:id/data /v1/site/:id/digitalinput /v1/time /v1/site/:id/digitalmnitrstatus/:channelid /v1/site/:id/calibratin /v1/site/:id/diagnstics /v1/pwerff /v1/site/:id/instantaneus /v1/site/:id/instantcalibratin /v1/site/:id/lgbk /v1/site/:id/channels Örnek: Aşağıda verilen örnekte 1 numaralı ölçüm nktasına ait veriler talep edilmektedir. http://veri.testtesisi.cm.tr:8080/v1/site/1/data?frm=2014-09-15t12:00:00&t=2014-09-15t15:00:00 4.1. Data Data request i, ölçüm nktalarından veri alma amacıyla kullanılmaktadır. /v1/site/:id/data frm <datetime> Başlangıç tarih/saat t <datetime> Bitiş tarih/saat timebase <int> Zaman esası (psiynel) limit <int> Talep edilen veri data adedi (psiynel) /v1/site/:id/data?frm=<datetime>&t=<datetime>[&timebase=<int>][&limit=<int>] Aşağıda yer alan örnek request te 1 numaralı ölçüm nktası için 1 Haziran 2014 09:00 ile 1 Haziran 2014 11:00 arası 30 dakikalık zaman esaslı verilerden ilk 2 adet kayıt talep edilmektedir. Zaman esası gönderilmediği taktirde ölçüm nktasına ait varsayılan zaman esaslı rtalama veri gönderilir. /v1/site/1/data/?frm=2014-06-01t09:00:00&t=2014-06- 01T11:00:00&timebase=30&limit=2
Örnek Respnse "data": [ "datetime": "2014-06-01T09:00:00", "data": [ "channelid": 0, "value": 1.0, "status": 1 "channelid": 1, "value": 249.1, "status": 3 "channelid": 2, "value": -100.1, "status": 4 "datetime": "2014-06-01T09:30:00", "data": [ "channelid": 0, "value": 1.0, "status": 1 "channelid": 1, "value": 248.8, "status": 3 "channelid": 2, "value": -9999, "status": 8
4.2. Digital Input Digitalinput request i, ölçüm nktalarından dijital giriş verilerini alma amacıyla kullanılır. Dijital giriş verilerine örnek larak kapı açık, yüksek kabin sıcaklığı veya elektrik yk verilebilir. Dijital giriş verileri, yalnızca dijital giriş kanallarından birinde durum değişikliği lduğu taktirde yeniden üretilmelidir. /v1/site/:id/digitalinput - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psiynel) /v1/site/:id/digitalinput?frm=<datetime>&t=<datetime>[&limit=<int>] Aşağıda yer alan örnek request te 1 numaralı ölçüm nktası için 13 Mayıs 2014 13:46 ile 14 Mayıs 2014 13:48 arası dijital giriş verilerinden ilk 4 adedi talep edilmektedir. /v1/site/1/digitalinput/?frm=2014-05-13t13:46:00&t=2014-05-14t13:48:00&limit=4 Örnek Respnse "digitalinput": [ "datetime": "2014-05-13T13:46:15", "state": "0x00" "datetime": "2014-05-13T13:47:30", "state": "0x01" "datetime": "2014-05-13T13:52:05", "state": "0x00" "datetime": "2014-05-13T13:52:15", "state": "0x01" 4.3. Time Time request i, veri tplama sistemine ait sistem saatini alma amacıyla kullanılır. Time request inde herhangi bir parametre gönderilmemektedir. /v1/time Örnek Respnse "systemdatetime": "2014-09-16T17:20:40"
4.4. Digital Mnitr Status DigitalMnitrStatus request i, ölçüm nktasındaki bir kanala ait dijital kanal durum bilgisini alma amacıyla kullanılır. Analizörlerden gelen dijital durum bilgileri örneğin WarmUp, Alarm, Zer, Cal, IRLamp Fault, vb. veriler labilir; cihazların röle kntakları değil, dijital çıkış durum bilgileri kullanılmalıdır. Kanala ait lası status bit leri ve açıklamaları kurulum esnasında bakanlığa bildirilmelidir. /v1/site/:id/digitalmnitrstatus/:channelid - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psiynel) /v1/site/:id/digitalmnitrstatus/:channelid/?frm=<datetime>&t=<datetime>[&limi t=<int>] Aşağıda yer alan örnek request te 1 numaralı ölçüm nktasında bulunan 2 id li kanal için 7 Temmuz 2014 13:46 ile 8 Temmuz 2014 13:48 arası dijital kanal durum verilerinden ilk 2 adedi talep edilmektedir. /v1/site/1/digitalmnitrstatus/2/?frm=2014-07-07t13:46:00&t=2014-07-08t13:48:00&limit=2 Örnek Respnse "channelid": 2, "digitalmnitrstatus": [ "datetime": "2014-07-07T13:48:47", "state": "0x18" "datetime": "2014-07-07T13:50:53", "state": "0x18"
4.5. Calibratin Calibratin request i, ölçüm nktasında kanallara ait tüm kalibrasyn bilgilerini alma amacıyla kullanılır. Alınan cevapta site (ölçüm nktası) id si ve kalibrasyn verileri yer alır. Kalibrasyn verileri, her kalibrasyn için ve farklı kalibrasyn tipleri için bilgiler içerir. Bu bilgiler aşağıdaki gibidir: - datetime [datetime]: Kalibrasyn zamanı - valid [bl]: Kalibrasynun geçerli lup lmadığı - factr [duble]: Kalibrasyn snucunda elde edilen sapma faktörü - channelid [int]: Kanal ID si - Zer kalibrasynu için: zer [duble]: sıfır değeri ffset [duble]: t kalibrasyn sekansına başladığından bu yana geçen zaman dakika ve saniye cinsinden duratin [duble]: sıfır için tanımlanan süre samples [duble]: duratin zamanı içerisinde rtalamanın alınmaya başlayacağı süre. reference [duble]: sıfır referans değeri ( O2 için 20.9 labilir) value [duble]: cihazın samples süresi içerisinde kuduğu değerlerin rtalamasıdır. std [duble]: Ortalama alınan verilerin standart sapmasıdır. - Span kalibrasynu için: ffset [duble]: t kalibrasyn sekansına başladığından bu yana geçen zaman dakika ve saniye cinsinden duratin [duble]: span için tanımlanan süre samples [duble]: duratin zamanı içerisinde rtalamanın alınmaya başlayacağı süre. reference [duble]: span referans değeri value [duble]: cihazın samples süresi içerisinde kuduğu değerlerin rtalamasıdır std [duble]: Ortalama alınan verilerin standart sapmasıdır - Multipint (çk nktalı) kalibrasynda her bir kalibrasyn nktası için: ffset [duble]: t kalibrasyn sekansına başladığından bu yana geçen zaman dakika ve saniye cinsinden pint [duble]: Kalibrasyn nktası durum status kdu duratin [duble]: span X için tanımlanan süre reference [duble]: span X referans değeri value [duble]: cihazın duratin süresi içerisinde kuduğu değerlerin rtalamasıdır std [duble]: Ortalama alınan verilerin standart sapmasıdır userlgin [max 50 karakter string]: Sisteme giriş yapan kullanıcı bilgileri peratrname [max 50 karakter string]: Operatör adı peratintype [int]: 1: Otmatik, 2: Manuel /v1/site/:id/calibratin - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psinel) /v1/site/:id/calibratin?frm=<datetime>&t=<datetime>[&limit=<int>]
Aşağıda yer alan örnek request te 1 numaralı ölçüm nktasına ait 20 Temmuz 2014 ile 21 Temmuz 2014 arası kalibrasyn verileri talep edilmektedir. /v1/site/1/calibratin/?frm=2014-07-20&t=2014-07-21 Örnek Respnse "calibratin": [ "datetime": "2014-07-20T12:17:09", "valid": false, "factr": 1.068349589349, "channelid": 2, "zer": "zer": 0.2, "ffset": 5.0, "duratin": 5.0, "samples": 5.0, "reference": 0.0, "value": 0.2, "std": 0.0 "span": "ffset": 15.0, "duratin": 5.0, "samples": 5.0, "reference": 5.0, "value": 4.9, "std": 0.0 "multipint": null "datetime": "2014-06-11T15:49:22", "valid": true, "factr": 1.06382978723404, "channelid": 2, "zer": "zer": 0.2, "ffset": 5.0, "duratin": 5.0, "samples": 5.0, "reference": 0.0, "value": 0.2, "std": 0.0 "span": "ffset": 15.0, "duratin": 5.0, "samples": 5.0, "reference": 5.0, "value": 4.9, "std": 0.0 "multipint": [ "ffset": 25, "pint": "type": 31 "duratin": 5, "reference": 10.0, "value": 10.2, "std": 0.0, "userlgin": "Administratr (Operate Service)", "peratrname": "N User Exists (Operate Viewer)", "peratintype": 2 "ffset": 35, "pint": "type": 38
"duratin": 5, "reference": 20.0, "value": 19.799999, "std": 0.0, "userlgin": "Administratr (Operate Service)", "peratrname": "N User Exists (Operate Viewer)", "peratintype": 2 "ffset": 45, "pint": "type": 39 "duratin": 5, "reference": 30.0, "value": 30.200001, "std": 0.0, "userlgin": "Administratr (Operate Service)", "peratrname": "N User Exists (Operate Viewer)", "peratintype": 2 "ffset": 55, "pint": "type": 43 "duratin": 5, "reference": 70.0, "value": 69.730003, "std": 0.0, "userlgin": "Administratr (Operate Service)", "peratrname": "N User Exists (Operate Viewer)", "peratintype": 2 "ffset": 65, "pint": "type": 44 "duratin": 5, "reference": 100.0, "value": 101.360001, "std": 0.0, "userlgin": "Administratr (Operate Service)", "peratrname": "N User Exists (Operate Viewer)", "peratintype": 2
4.6. Diagnstics Diagnstics request i, ölçüm nktasında kanallara ait diyagnstik verilerini alma amacıyla kullanılır. Alınan cevapta site (ölçüm nktası) id si ve diyagnstik verileri yer alır. Diyagnstik verileri; kanal id si, tarih/saat ve diyagnstik bilgilerinden. Diyagnstik bilgileri aşağıdaki gibidir: - cmmand [max 50 karakter string]: Cihazın sinyal değerini almak için gereken kmut - units [max 50 karakter string]: Ölçülen sensör değerinin birimi (mv, Amp, Deg.C vb..) - value [duble]: Nümerik sinyal değeri /v1/site/:id/diagnstics - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psinel) /v1/site/:id/diagnstics?frm=<datetime>&t=<datetime>[&limit=<int>] /v1/site/1/diagnstics/?frm=2014-02-02&t=2014-02-03 Örnek Respnse "diagnstics": [ "channelid": 1, "datetime": "2014-02-02T00:00:00", "data": [ "cmmand": "cmd1", "units": "unt1", "value": "1.1" "cmmand": "cmd2", "units": "unt2", "value": "2.2" "cmmand": "cmd3", "units": "unt3", "value": "3.3" "channelid": 1, "datetime": "2014-02-02T00:00:00", "data": [ "cmmand": "cmd1", "units": "unt1", "value": "1.1" "cmmand": "cmd2", "units": "unt2", "value": "2.2" "cmmand": "cmd3", "units": "unt3", "value": "3.3"
4.7. Pwer Off PwerOff request i, veri tplama sisteminin kapalı lduğu zamanları srgulamak amacıyla kullanılır. /v1/pwerff - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psinel) /v1/pwerff?frm=<datetime>&t=<datetime>[&limit=<int>] /v1/pwerff/?frm=2014-05-12&t=2014-05-16&limit=3 Örnek Respnse "pwerff": [ "start": "2014-05-12T19:15:36", "end": "2014-05-12T19:15:35" "start": "2014-05-12T19:21:04", "end": "2014-05-12T19:21:03" "start": "2014-05-12T19:33:08", "end": "2014-05-12T19:33:07" 4.8. Instantaneus Instantaneus request i, ölçüm nktasına ait kanalların anlık örnekleme verilerini srgulamak amacıyla kullanılır. Alınan cevaptaki veriler, analizörden kunan ham verilerdir. /v1/site/1/instantaneus Örnek Respnse "instantaneus": [ "datetime": "2014-07-21T16:40:11.05", "channelid": 0, "value": 16.8, "status": 1 "datetime": "2014-07-21T16:40:11.05", "channelid": 1, "value": 4.0, "status": 1 "datetime": "2014-07-21T16:40:11.05", "channelid": 2, "value": -9999.0, "status": 8
4.9. Instant Calibratin InstantCalibratin request i, ölçüm nktasına ait kanalların anlık kalibrasyn verilerini srgulamak amacıyla kullanılır. Herhangi bir sekansın herhangi bir anını çalıştırdığınızda elde edilen değeri temsil eder. Anlık kalibrasyn verileri, gerçekleştirilen her anlık kalibrasyn için bilgiler içerir. Bu bilgiler aşağıdaki gibidir: - datetime [datetime]: Kalibrasyn zamanı - channelid [int]: Kanal ID si - value [duble]: Ölçülen değer - status [int]: değerin durum bilgisi ( span, zer vb..) /v1/site/:id/instantcalibratin - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psinel) /v1/site/:id/instantcalibratin?frm=<datetime>&t=<datetime>[&limit=<int>] /v1/site/1/instantcalibratin/?frm=2014-09-14&t=2014-09-15&limit=2 Örnek Respnse "instantcalibratin": [ "datetime": "2014-09-14T06:00:00", "channelid": 0, "value": 7.0, "status": 1 "datetime": "2014-09-14T05:00:00", "channelid": 0, "value": 6.0, "status": 1
4.10. Lgbk Lgbk request i, ölçüm nktasına ait bakım kayıtlarını ve veritplama sisteminde gerçekleşen işlemleri srgulama amacıyla kullanılır. Lgbk verileri, sistemde kayıtlı lg lar ile ilgili bilgiler içerir. Lgbk verileri, bakım işlemleri haricinde veri tplama sisteminde gerçekleştirilen tüm işlemleri (kullanıcı girişleri, knfigürasyn değişikliği, kanal) içermelidir. Bu bilgiler aşağıdaki gibidir: - datetime [datetime]: Kayıt zamanı - lg : Kayıt verileri equipment [max 50 karakter string]: Cihaz bilgisi invaliddata [int]: Bakım yapılıyrsa, bakım esnasında verinin geçersiz kılınıp kılınmadığı (0: geçerli, 1: geçersiz) tendtype [max 50 karakter string]: Bakımın/işlemin türü (Arıza, Periydik Bakım, Yıllık Bakım, Kntrl, Kullanıcı Girişi, Knfigürasyn değişikliği, vb.) technician [max 50 karakter string]: Bakımı yapan ya da işlemi gerçekleştiren kullanıcı bilgisi descriptin [max 2000 karakter string]: Bakım ya da işlem ile ilgili detaylı açıklama spareparts [max 2000 karakter string]: Değişen yedek parçalar (parçalar ; ile ayrılmış) /v1/site/:id/lgbk - frm <datetime> Başlangıç tarih/saat - t <datetime> Bitiş tarih/saat - limit <int> (ptinal) Talep edilen veri adedi (psinel) /v1/site/:id/lgbk?frm=<datetime>&t=<datetime>[&limit=<int>] /v1/site/1/lgbk/?frm=2014-07-13&t=2014-07-14&limit=2 Örnek Respnse "lgbk": [ "datetime": "2014-10-29T13:21:39", "lg": "equipment": "", "invaliddata": 0, "tendtype": "User Lgin", "technician": "Erl Egemen", "descriptin": "User lgged in.", "spareparts": "" "datetime": "2014-10-29T13:22:47", "lg": "equipment": "PM10 Analizru", "invaliddata": 0, "tendtype": "Scheduled - weekly", "technician": "Erl Egemen", "descriptin": "Haftalik periydik degisim", "spareparts": "Filtre;Hlder"
4.11. Channels Channels request i ölçüm nktasına ait ölçüm kanallarının bilgilerini almak için kullanılır. /v1/site/:id/channels /v1/site/1/channels Örnek Respnse "channels": [ "id": 0, "name": "PM10", "units": "µg/m³", "address": 0 "id": 1, "name": "SO2", "units": "µg/m³", "address": 1 "id": 2, "name": "NO", "units": "µg/m³", "address": 2