Izbornik Zatvoriti

PHP, nusoap i veb servis za kursnu listu NBS

Skraćena veza: https://pedja.supurovic.net/veza/4685

Pre nekoliko dana sam krenuo da uradim rutinu za preuzimanje kursne liste sa sajta Narodne Banke Srbije. Na prvi pogled, s obzirom da su ponudili javni veb servis u SOAP tehnologiji, izgledalo je da će stvar biti urađena rutinski. Nažalost nije. Pošteno sam se namučio da sve namestim.

Dokumentacija koja je ponuđena na sajtu NBS je prilično štura i nije baš od velike pomoći, naročito nekome ko se prvi put upušta u ovakvu stvar. I Gugl o celoj ovoj stvari malo zna, te uglavnom prikazuje linkove na pomenutu dokumentaciju ali i na nekoliko sajtova gde ljudi traže pomoć pokušavajući da se izbore sa korišćenjem servisa i bez vidnih rešenja.

Stoga, s obzirom da mi je najzad uspelo da izvedem povezivanje, evo uputstva kako se iz PHP-a koristi veb servis NBS za pristup kursnim listama.

Kako početi

Najpre, da biste koristili veb servise NBS morate biti registrovani korisnik. Detaljno objašnjenje kako se to čini imate na sajtu NBS , a ukratko, treba da pošaljete popunjen i overen zahtev za učlanjenje u sistem veb-servisa NBS. Procedura je jednostavna i završava se za nekoliko dana, s obzirom da zahtev morate, pored imejla, poslati i običnom poštom, odštampan.

Kada postanete član, dobićete šifru licence koja vam je neophodna da biste servis mogli koristiti. Pored ove šifre, potrebni su vam i korisničko ime i lozinka a njih sami određujete i navodite u zahtevu za učlanjenje.

Nakon što postanete član moći ćete odmah koristiti sve besplatne veb servise NBS. Među njima je i servis za pristup kursnim listama koji nas interesuje. Ako vas interensuju servisi koji se naplaćuju njih posebno morate aktivirati.

Šta je SOAP?

Za detaljan odgovor na ovo pitanje poslaću vas na Gugl. Stvar je suviše složena da nema svrhe da vam prepričavam obilje dokumentacije koja je dostupna. Daču vam vrlo kratko i uopšteno objašnjenje.

Internet je omogućio da se funkcionalnost aplikacija proširi van jednog računara i van lokalne mreže – na ceo Internet. To znači da je moguće na jednom računaru pokrenuti aplikaciju, a ona će koristiti podatke sa neke druge lokacije koja može biti bilo gde, samo je važno da server sa podacima bude dostupan preko Interneta. Nešto složeniji pristup omogućava da se i sama aplikacija nalazi na Internetu, a da korisnik ima samo jednostavan klijent na svom računaru.

Najočigledniji primer takvog pristupa je veb čitač kojim upravo čitate ovaj članak. To je jednostavna aplikacija koja, sama za sebe nema neku svrhu, ali kada otvorite neki sajt vi u stvari učitavate program koji veb čitaču daje funkcionalnost. Za neke druge namene koriste se drugačiji klijenti i drugačiji serveri koji omogućuju i veoma složene aplikacije.

Sa tim, pojavila se i neizbežna potreba da seomogući da raznorodni računari, operativni sistemi i programi mogu međusobno ne samo da komuniciraju nego i da izvršavaju aplikacije. Pojavili su se protokoli koji su upravo to omogućili. Oni omogućuju da sa klijenta izvršite programske procedure na serveru. Te procedure mogu jednostavno da vam daju tražene podatke ali mogu i da izvrše obradu podataka na serveru. SOAP (Simple Object Access Protocol) je jedan od takvih protokola.

Pogodnost SOAP-a je u tome što je on univerzalan i prevazilazi razlike između hardvera, operativnih sistema, programskih jezika kao i samih aplikacija. SOAP aplikacija može da se izvršava na bilo čemu, počev od običnog računara, preko PDA, mobilnog telefona kao i na svakom drugom uređaju koji može da sa SOAP serverom komunicira preko Interneta.

Naravno, ne izvršava se stvarno se SOAP aplikacija na svim ovim uređajima već oni mogu, korišćenjem SOAP protokola, da pokreću procedure koje se izvršavaju na serveru i da dobiju od njega podatke koje dalje mogu da koriste.

Tako široka kompatibilnost SOAP protokola se zasniva na tome što on svu komunikaciju između klijenata i servera zasniva na XML porukama. SOAP poruke su, u stvari, samo XML poruke sa unapred jasno definisanom strukturom.

Nije zato iznenađujuće zašto se Narodna banka Srbije odlučila da ovaj protokol koristi za obezbeđenje svog javnog veb servisa: time su omogućili da podatke sa njihovog servera možete dobiti na bilo kom uređaju i iz bilo kog okruženja koje ima pristup Internetu.

Kako funkcioniše veb sevis NBS

Da biste mogli da dobijete neku informaciju od veb servisa NBS potrebni su vam sledeći podaci:

– korisničko ime (UserName)

– lozinka za pristup (Password)

– šifra licence (LicenceID)

– lokacija WSDL defincije servisa

– naziv imenskog prostora (NameSpace)

– naziv metoda (programske funkcije) servisa

– parametri koji se prosleđuju izabranoj metodi

Nije neophodno da ručno kreirate XML poruke da biste koristli veb servis. Postoje gotove biblioteke koje to mogu uraditi umesto vas, na osnovu parametara koje im prosledite.

Prilikom uspostavljanja konekcije sa veb servisom neophodno je da se identifikujete. Za to služi zaglavlje za autentifikaciju (AuthenticationHeader) koje se šalje prilikom uspostavljanja konekcije. Ono je specifično za veb servis NBS tako da ga morate pripremiti ručno. Zaglavlje za autentifikaciju se umeće u zaglavlje SOAP poruke i treba da izgleda ovako:

<AuthenticationHeader  xmlns="http://communicationoffice.nbs.rs">
<UserName>korsinicko_ime</UserName>
<Password>lozinka</Password>
<LicenceID>sifra_licence</LicenceID>
</AuthenticationHeader>

Veb servis NBS koristi nekoliko WSDL servisa, pa tako morate izabrati odgovarajuću definiciju zavisno opd toga kakve podatke želite. Potpun spisak svih servisa naći ćete na sajtu NBS. Nas, za preuzimanje kursne liste interesuje Servis za pristup kursnim listama .

Za svaki servis NBS postoje dva tipa: jedan vraća podatke u XML obliku a drugi kao DataSet. Koristićemo XML, tako da je lokacija WSDL defincije servisa koji ćemo koristiti https://webservices.nbs.rs/CommunicationOfficeService1_0/ExchangeRateXmlService.asmx?WSDL.

Imenski prostor (NameSpace) za sve veb servise NBS je isti: http://communicationoffice.nbs.rs.

Spisku metoda veb servisa ExchangeRateXmlService je podugačak, a nas interesuje metod GetExchangeRateByDate , koji daje podatke o kursnoj listi na zadati dan. Ovaj metod ima dva parametra: date datumskog tipa i exchangeRateListTypeID koji je numerički identifikator kursne liste.

Datumski podaci se prosleđuju kao tekstualni u formatu GGGGMMDD (godina sa četiri cifre, mesec sa dve cifre i dan sa dve cifre, sve spojeno).

Identifikator kursne liste je broj. Može imati tri vrednosti: 1 – za devize, 2 – za efektivu i 3 – srednji kurs. Mi ćemo tražiti srednji kurs.

To su svi podaci potrebni da možemo da preuzmemo podatke od veb servisa NBS.

Kako koristiti SOAP u PHP-u

Iako u principu SOAP upite možemo da izvršavamo ručno, jer se u suštini radi o slanju XML poruka, ipak je mnogo bolje to raditi nekom namenskom bibliotekom koja sadrži potpunu implementaciju SOAP protokola. Ja sam izabrao biblioteku nusoap . Ona ima svu potrebnu funkcionalniost i vrlo se jednostavno koristi.

Instalacija biblioteke je jednostavna: preuzmete arhivu i raspakujete je je u direktorijumu gde će se nalaziti PHP program koji treba da je koristi. Dobićete dva nova poddirektorijuma: lib i samples. Prvi sadrži biblioteku, a drugi možete i da obrišete jer sadrži primere korišćenja biblioteke. Ako vam je potrebno, a trebalo bi da jeste, sa sajta biblioteke možete posebno preuzeti arhivu sa dokumentacijom.

Biblioteku u svoj kod uključujete komandom

require_once('lib/nusoap.php');

SOAP konekciju podešavate kreiranjem objekta iz klase nusoap_client, na primer komandom:

$soap_client = new nusoap_client($soap_wsdl, true);

U bilo kom trenutku možete proveriti stanje objekta klijenta uvidom u brojne metode i svojstva klase nusoap_client. Sve odjednom ih možete pogledati komandom:

print_r ($soap_client);

To će vam svakako trebati ako budete naišli na probleme. Naročito obratite pažnju na metod $soap_client->getError(). Ako ova funkcija vrati bilo kakvu vrednost, to znači da je došlo do neke greške. Ako je greškausledila nakon poziva nekog metoda, onda će ta metoda da vam umesto traženih podataka vrati niz koji opisuje grešku koju je prijavio SOAP server.

Ako imate problema sa pozivom nekog SOAP metoda, dobroje da proverite kako izgleda SOAP poruka koja je poslata serveru. Ona se nalazi u svojstvu $soap_client->request.

Za ostalo, proučite dokumentaciju biblioteke nusoap.

A sad na posao

Posle malo dužeg uvoda možemo da krenemo sa komunikacijom sa SOAP serverom NBS. Pokazaću jednostavan primer koji preuzima kursnu listu na zadati datum po srednjem kursu.

Na početku, moramo uključiti nusoap biblioteku

<?php
require_once('lib/nusoap.php');

a zatim podesiti parametre željene kursne liste

$m_date = '20100811'; // zeljeni datum kursne liste u formatu YYYYMMDD
$m_list_type = 3;     // zelimo kursnu listu posrednjem kursu

Sada podešavamo podatke vezane za registraciju na veb servisu. Ovde morate upisati svoje podatke.

$login_username = 'USERNAME'';
$login_password = 'PASSWORD'';
$login_licenceid = 'LICENCEID';

I preostalo nam je još da podesimo lokaciju WDSL i NameSpace servisa:

$soap_wsdl = "https://webservices.nbs.rs/
CommunicationOfficeService1_0/ExchangeRateXmlService.asmx?WSDL";
$soap_namespace = "http://communicationoffice.nbs.rs";

Krećemo na posao. Prvo kreiramo objekat SOAP klijenta

$soap_client = new nusoap_client($soap_wsdl, true);

i odmah isključimo dekodiranje utf8 znakova, jer veb servisi NBS vraćaju podatke u utf8 formatu a takvi nam i trebaju. Ako ovo ne isključimo sva ćirilična i naša latinična slova bi bila uništena.

$soap_client->decode_utf8 = 0;

Pripremićemo zaglavlje za autentifikaciju, kao što je ranije objašnjeno. To zaglavlje umećemo u zaglavlje SOAP poruke.

$m_header =
'<AuthenticationHeader xmlns="' . $soap_namespace . '">
<UserName>' . $login_username . '</UserName>
<Password>' . $login_password . '</Password>
<LicenceID>' . $login_licenceid . '</LicenceID>
</AuthenticationHeader>';

$soap_client->setHeaders($m_header);

Pripremićemo i parametre koje ćemo proslediti prilikom poziva SOAP metoda. Parametri se prosleđuju u obliku asocijativnog niza.

$p_parameters = array('date'=>$m_date,
                      'exchangeRateListTypeID' => $m_list_type);

Sve je spremno i možemo izvršiti SOAP metod GetExchangeRateByDate sa pripremljenim parametrima.

$m_soap_result = $soap_client->call ('GetExchangeRateByDate',
                                      $p_parameters);

Nakon izvršenog metoda, u $m_soap_result će se nalaziti ili podaci koje smo tražili (u XML obliku) ili poruka o grešci koju je vratio SOAP server. Da li je došlo do greške proveričemo pozivom metoda getError().

Ako nema greške, podaci se nalaze u promenljivoj  $m_soap_result koja je u stvari niz sa jednim elementom pod imenom GetExchangeRateByDateResult.

$m_error = $soap_client->getError();
if ($m_error) {
   //doslo je do greske, ispisacemo dostupne podatke o tome
   echo '<h1>Error:</h1>';
   echo '<pre>';
   print_r ($m_soap_result);
   print_r ($soap_client);
   echo '</pre>';
} else {
   //nema greske, prikazacemo podatke koje smo dobili
   $m_output = $m_soap_result;
   print_r ($m_output);
}
?>

I tu je kraj

Pretpostavljam da ste do ovog mog članka došli nakon što ste i sami naišli na problem i da vam se sada čini da je ovo sve veoma jednostavno. Verujem da se tako činilo i ljudima u NBS pa nisu smatrali za shodno da napišu malo jasniju dokumentaciju. Nadam se da sam na ovaj način upotpunio prazan prostor koji je postojao te da će drugima sada bitilakše da u svoje programe ugrade podršku za veb sevise Narodne banke Srbije.

Ovi servisi nude još mnogo podataka. Ukoliko su vam neki od njih potrebni, proučite dokumentaciju SOAP metoda koji daje to što vam treba i upotrebite ga na sličan način kao u ovom primeru.

Na kraju, evo i datoteke sa kodom koji je korišćen u članku: kursna-lista-nbs-nusoap.zip (5093 downloads )

31 Comments

  1. Knez

    Ovo je super radilo sve do skoro. Poslao sam mejl sa tekstom greske u attachmentu ovima u NBS ali se ne javljaju. Pedja da li tebi ovo jos uvek funkcionise ?

    • Peđa

      Malopre sam probao servis i radi mi primer koji sam napravio prilikom pisanja ovog članka bez ikakvih izmena.

      NBS je promenila adrese stranica sa dokumentaicjom, pa sam ažurirao članak i stavio nove adrese.

  2. Sladjan

    Pozdrav Peđa,
    imaš li neki primer parsiranja rezultata da iygleda lepše na osnovu XSD schema fajla koji je dat uz web servis?

  3. Mlisac

    Python3 resenje ako nekog zanima…

    from suds.client import Client
    from xml_to_dict import XMLtoDict

    WSDL_URL = 'https://webservices.nbs.rs/CommunicationOfficeService1_0/CurrentExchangeRateXmlService.asmx?WSDL'
    uname = 'xxxxxxxxxxxxx'
    passwd = 'xxxxx-xxxx-xxx-xxx-xx'
    lic_id = 'xxxxxxx-xxxxx-xxxxxxx'

    client = Client(WSDL_URL, faults=False, cachingpolicy=1)

    authHead = client.factory.create('AuthenticationHeader')
    authHead.Password = passwd
    authHead.UserName = uname
    authHead.LicenceID = lic_id

    client.set_options(soapheaders=authHead)

    parser = XMLtoDict()

    status, resp = client.service.GetCurrentExchangeRate(1)
    print(status, parser.parse(resp))

Ostavite odgovor na JP Odustani od odgovora

Vaša adresa e-pošte neće biti objavljena. Neophodna polja su označena *

Popunite izraz tako da bude tačan: *

Ovo veb mesto koristi Akismet kako bi smanjilo nepoželjne. Saznajte kako se vaši komentari obrađuju.