osos web servisleri kullanımı

OSOS WEB SERVİSLERİ KULLANIMI
21.12.2015
İçindekiler
1.
Amaç .......................................................................................................................................2
2.
Kapsam ...................................................................................................................................2
3.
Login İşlemleri .........................................................................................................................2
4.
Web Servis Sorgu ve Cevap Örnekleri ......................................................................................3
5.
4.1.
Veri Gönderim Fonksiyonu...............................................................................................3
4.2.
Veri Alış Fonksiyonu .........................................................................................................4
4.3.
OSOS Sayaç Bilgilendirmesi ..............................................................................................5
NOTLAR ...................................................................................................................................5
1
1. Amaç
Bu dokümanın amacı OSOS Veri Paylaşımı Projesi kapsamında geliştirilen web servislerin nasıl
kullanılacağına ilişkin örneklerin EDAŞ’lar ile paylaşılmasıdır.
2. Kapsam
OSOS veri paylaşımı projesinin ilk aşaması kapsamında geliştirilen web servislere ait örnek
sorgu ve yanıtlar doküman kapsamında ele alınmıştır. Geliştirilen web servisler şu şekildedir:



Veri Gönderme Web Servisi (Set Metodu)
Veri Okuma Web Servisi (Get Metodu)
OSOS Kapsamı Bilgilendirmesi Web Servisi (Get Metodu)
3. Login İşlemleri
Bütün web servislerde kullanmak üzere login işlemleri şu şekilde gerçekleştirilir:

CAS üzerinden “service ticket” alınması gerekir. Ticket alınırken yapılacak isteğin “header
name”i “Content-Type”, “value” ise “application/x-www-form-urlencoded” olmalıdır.

CAS üzerinden alınan service ticket get metotları için http header'ına eklenmelidir. HTTP
Header'ın “name” alanı “Service-Key”, “value” alanı CAS'tan alınan service ticket
gelmelidir. Get metotları için örnek gösterim aşağıdaki gibidir:
◦
name: Service-Key
◦
value:ST-32-GYYkyetc7PJssurJnKZc-cas01.epias.com.tr

CAS üzerinde oluşturulan “Service Ticket” ın geçerlilik süresi 30sn'dir.

CAS üzerinden ST almak için DGPYS kullanıcı bilgilerini aşağıdaki gibi göndermeniz
gerekmektedir.
◦

Post metotları için CAS üzerinden alınan service ticket request header'ına eklenmelidir.
Örnek gösterim aşağıdaki gibidir:
◦

"header":[ {"key": "Service-Key",
cas02.epias.com.tr"} ]
"value":
CAS'tan service ticket almak için şu adres kullanılacaktır:
◦

username=*****&password=******
https://cas.epias.com.tr/cas/v1/tickets
CAS'tan service ticket alırken kullanılacak servis:
◦
https://cas.epias.com.tr
2
"ST-21-00EjLldcoRcEVGVM5Sgz-
4. Web Servis Sorgu ve Cevap Örnekleri
Bu bölümde web servislerin kullanımına ilişkin örnek sorgu kodları ve geri dönüşlerine dair
örnekler verilmiştir.
4.1.
Veri Gönderim Fonksiyonu
Web servis bağlantı
web/rest/ososData/
URL
(test
sistemi):
https://osos-test.epias.com.tr/osos-
Web servis bağlantı URL (gerçek sistem):https://osos.epias.com.tr/osos-web/rest/ososData/
Yukarıdaki URL kullanılarak HTTP POST isteği yapılmalıdır. Yapılacak olan işlem için iki adet
header kullanılacaktır:

Service Ticket request'in header kısmına eklenmelidir. (Login kısmında belirtildiği şekliyle
kullanılmalıdır.)

HTTP Header'ın “name” alanı “Content-Type”, “value” alanı ise “application/json”
olmalıdır.

Mesajlaşmadaki tarih formatı "yyyy-MM-dd'T'HH:mmZ" şeklinde olacaktır.
Örnek İstek
{ "header":[ {"key": "Service-Key", "value": "ST-29-tDipvkkHEJJfzbtOgr22cas02.epias.com.tr"} ], "body":
{ "ososDataTypeList": [
{
"eic": "40Z00000XXXXXXXX",
"meteringTime": "2015-02-14T09:40+0200",
"meteringPoint": 1,
"period": 15,
"meteringType": 1,
"generationAmount": 1254.63,
"consumptionAmount": 369857.36
}
3
]}
}
Örnek Cevap
{
"resultCode": "0",
"resultDescription": "Isleminiz basariyla tamamlanmistir.",
"body": null
}
Veri yükleme sırasında karşılaşılacak hatalar ve açıklamaları dönen yanıt içerisinde yer
alacaktır.
4.2.
Veri Alış Fonksiyonu
Web servis örnek bağlantı URL (test sistemi): "https://osos-test.epias.com.tr/ososweb/rest/osos/getOSOSData?eic=40Z00000XXXXXXXX&startTime=2015-0214T09:40%2B0100"
Web servis örnek bağlantı URL (gerçek sistem): "https://osos.epias.com.tr/ososweb/rest/osos/getOSOSData?eic=40Z00000XXXXXXXX&startTime=2015-0214T09:40%2B0100"
URL'deki startTime değişkenindeki “%2B” artı (+) işaretine karşılık gelen HTTP gösterimidir.
Yapacağınız isteğe dönen örnek cevap aşağıdaki gibidir:
{"resultCode":"0","resultDescription":"OK","body":{"ososDataTypeList":[{"eic":"40Z00000
XXXXXXXX","meteringTime":"2015-0214T09:40+0200","meteringPoint":1,"period":15,"meteringType":1,"generationAmount":11
11,"consumptionAmount":222,"timeZone":"+0200","recordTime":"2015-1218T09:54+0100"}]}}
4
4.3.
OSOS Sayaç Bilgilendirmesi
Web servis bağlantı URL (test sistemi): https://osos-test.epias.com.tr/ososweb/rest/ososConfig/
Web servis bağlantı URL (gerçek sistem): https://osos.epias.com.tr/ososweb/rest/ososConfig/
Yukarıdaki URL kullanılarak HTTP GET isteği yapılmalıdır.
4.3.1. Organizasyona Ait Tüm Sayaçların Veri Gönderim Şeklinin Okunması
Servis ticket'ın gönderilmesi sonucunda sisteme kayıtlı OSOS ölçüm noktalarının hangi
periyotla veri göndermesi gerektiği bilgisi gönderilir.
Yapılan “request”e dönen “response” örneği şu şekildedir:

{"resultCode":"0","resultDescription":"OK","body":{"ososDataConfigTypeList":[{"eic":
"40Z00000XXXXXXXX","period":15,"meterType":"URETIM","balanceType":"NORMAL"}
]}}
◦

40Z00000XXXXXXXX EIC koduna ait veri 15 dk'lik periyotlarla gönderilmelidir. Üretim
birimi dengeleme birimi olmayan bir tesistir.
{"eic":"40Z00000XXXXXXXX","period":15,"meterType":"URETIM","balanceType":"DEN
GELEME_BIRIMI"}
◦
40Z00000XXXXXXXX EIC koduna ait veri 15 dk'lik periyotlarla gönderilmelidir. Üretim
birimi dengeleme birimi olan bir tesistir.
NOT: Test süreci tamamlanmadan önce organizasyona ait EIC kodu bilgisi ile tek bir ölçüm
noktasına ait sorgulama yapma özelliği eklenecektir.
5. NOTLAR



URL adreslerin sadece test sistemi için aktiftir. Gerçek sistemin 1 Ocak 2016 tarihi
itibariyle devreye alınması planlanmaktadır.
Test ortamının daha esnek olabilmesi açısından zaman kontrolleri yapılmamıştır.
Test sırasında karşılaşılacak hatalar ve öneriler için geri dönüş beklenmektedir.
5