Aansluiting op de service

Prj. KSZ-BCSS WebServices – KSZ-BCSS Webservices: HTTP SOAP WSDL
19-jul-17
Ksz-Bcss Webservices: Http Soap Wsdl
Inhoudsopgave
KSZ-BCSS WEBSERVICES: HTTP SOAP WSDL ..................................................................................... 1
INHOUDSOPGAVE ......................................................................................................................................... 1
BEDOELING VAN DIT DOCUMENT .......................................................................................................... 1
DE VERSCHILLENDE LAGEN .................................................................................................................... 1
AANSLUITING OP DE SERVICE ................................................................................................................ 1
WEBSERVICE-CONNECTOR .............................................................................................................................. 1
XML EN XSD’S ................................................................................................................................................ 2
ONTHAALPAGINA ........................................................................................................................................ 3
CONTACTEN ................................................................................................................................................... 4
Bedoeling van dit document
Het betreft een technisch document waarin de technische achtergrond wordt toegelicht waar
de interactie tussen de klanten en de KSZ plaatsvindt met het oog op de toegang tot de
online XML-diensten.
De verschillende lagen
Om een webservice die door de KSZ wordt aangeboden te kunnen uitvoeren, moet de klant
een geldig XML-verzoek opsturen. De transportlaag om het XML-bericht te verkrijgen van
en te versturen naar de KSZ is TCP/IP. Het gebruikte toepassingsprotocol is http(s). De
switch tussen http en https is enkel een kwestie van configuratie. Het XML-bericht zelf is
ingebed in het http-protocol dat de definitie van webservice gebruikt, dit alles vervat in een
SOAP-bericht.
Message definition: XML, SOAP, WSDL
HTTP(S)
TCP/IP
Aansluiting op de service
Webservice-connector
U krijgt toegang tot de service aan de hand van een webservice gebaseerd document
(opgelet: gebruik niet de RPC-stijl). De webservice heeft één enkle methode : sendXML.
Deze methode gebruikt een String (het verzoek is reeds in XML omgezet) en stuurt een
String terug (het XML-antwoord van één van onze services). Dit XML-antwoord wordt
gewoonlijk opgesplitst (unmarshalled) in business objects, naargelang de gebruikte
technologie.
De klantcode van de webservice (die u nodig heeft om de aansluiting tot stand te brengen)
wordt automatisch door tools gegenereerd naargelang uw doelplatform:
317494189
1/4
Prj. KSZ-BCSS WebServices – KSZ-BCSS Webservices: HTTP SOAP WSDL
19-jul-17
- voor Java bestaat er een tool genaamd ‘wsdl2java’
- .NET beschikt hiertoe over een in IDE geïntegreerde tool
- C/C++
- WinDEV
- …
De tool die op het WSDL-bestand is gebaseerd, genereert een stub klant die kan worden
gebruikt om de aansluiting op de webservice tot stand te brengen. Het WSDL-bestand kan
automatisch worden teruggevonden door “?WSDL” toe te voegen aan de URL-aansluiting.
De webservice gebruikt de default URL die in het WSDL-bestand wordt vermeld. Deze
URL is niet correct! We kunnen immers niet weten welk IP u nodig heeft om u op de
webservices aan te sluiten, dit hangt af van de typologie van het (de) netwerk(en) aan de
hand waarvan de aansluiting tot stand komt (het IP-adres kan een privaat IP-adres zijn en
kan verschillend zijn voor elke klant en omgeving). Hiertoe moet de default URL
vervangen worden door de correcte URL om u op de KSZ aan te sluiten.
Raadpleeg hiertoe het document https://www.kszbcss.fgov.be/sites/default/files/assets/diensten_en_support/03_ksz_bcss_webservices_aanslui
tingsmogelijkheden_nl.pdf.
U kan deze URL in automatisch gegeneerde klassen inbrengen. U moet normaal gezien een
instantie zonder URL aanmaken (deze instantie gebruikt de default URL die in het WSDLbestand is vastgelegd) of u kan een instantie aanmaken met een URL. U moet de voor de
doelomgeving correcte URL inbrengen. Dezelfde opmerking geldt ook voor de
aansluitingspoort.
Op het moment van het opmaken van dit document heeft de URL het volgende formaat:
http(s)://ipaddress:port/connectors/webservice/KSZBCSSWebServiceConnectorPort
Op het moment van het opmaken van dit document is de WSDL bereikbaar via:
http(s)://ip:port/connectors/webservice/KSZBCSSWebServiceConnectorPort?WSDL
Een geldige aansluiting moet op de aansluiting hierna gelijken (variaties zijn echter
mogelijk)
POST /connectors/webservice/KSZBCSSWebServiceConnectorPort HTTP/1.0
….
SOAPAction: "http://ksz-bcss.fgov.be/connectors/WebServiceConnector/sendXML"
Content-Type: text/xml; charset=utf-8
…
[empty line]
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
<soapenv:Body>
<xmlString xmlns="http://ksz-bcss.fgov.be/connectors/WebServiceConnector">
Your XML message comes here
</xmlString>
</soapenv:Body>
</soapenv:Envelope>
XML en XSD’s
Elke service die door de KSZ wordt aangeboden wordt door een XSD voorgesteld.
Contacteer de KSZ voor de XSD van een specifieke service. Er zou een geldige XMLvoorstelling die op deze XSD’s is gebaseerd, moeten worden aangemaakt en aan de KSZ
317494189
2/4
Prj. KSZ-BCSS WebServices – KSZ-BCSS Webservices: HTTP SOAP WSDL
19-jul-17
worden overgemaakt. Na verwerking van het verzoek wordt het resultaat teruggestuurd. Dit
XML-antwoord kan worden opgesplitst (“unmarshalled”) door gebruik te maken van het
XSD-antwoord van de ingeroepen service.
U vindt een gedetailleerde definitie van de algemene XSD-structuur in het volgende
document: https://www.kszbcss.fgov.be/sites/default/files/assets/diensten_en_support/08_ksz_bcss_webservices_ssdn_r
equest_reply_envelope_definition_nl.doc. Dit wordt in de volgende figuur geïllustreerd
Voor marshalling / unmarshalling van de XML gebruiken we op de KSZ het door Sun
aangeboden framework (JAXB dat deel uitmaakt van JWSDP1). Het gaat om een tool die
Java-klassen genereert vanaf een XSD. Dankzij deze klassen kunnen objecten in XML
worden omgezet en omgekeerd. Het is niet nodig om hiertoe codes te schrijven. JAXB
biedt verschillende mogelijkheden aan om de nodige Java-bronnen en –klassen te
genereren.
Indien Java als platform wordt gebruikt, kan JAXB zonder te veel inspanningen worden
gebruikt. Alle onze XSD zijn compatibel met JAXB. U kan eenvoudig bindingsbestanden
aanmaken die met XSD moeten worden gebruikt. Het spreekt voor zich dat indien u een
ander doelplatform gebruikt of indien u niet met JAXB wenst te werken, u om het even
welke parser implementation kan gebruiken. Voor zover de door u aangemaakte XML
geldig is ten opzichte van onze XSD’s is er geen probleem.
Er bestaan andere mogelijke oplossingen. Op dit ogenblik gebruiken we op de KSZ echter
de hierboven toegelichte oplossing. Indien u een gelijkaardige oplossing gebruikt, zullen we
u graag proberen te helpen. U bent niettemin vrij om een andere met XML en XSD
compatibele technologie te gebruiken indien dit beter in het strategische plan van uw bedrijf
past.
Onthaalpagina
De onthaalpagina is toegankelijk via de web root ‘connectors’. De URL is de volgende:
http://ipaddress:port/connectors/ (het correcte IP en de correcte poort inbrengen).
Ingeval van een mogelijk aansluitingsprobleem bestaat een goede test erin trachten toegang
te krijgen tot deze pagina.
1
Zie http://java.sun.com/webservices/jwsdp/ voor meer informatie over de Java Web Services Developer
Pack (JWSDP) en de componenten ervan (o.a. JAXB)
317494189
3/4
Prj. KSZ-BCSS WebServices – KSZ-BCSS Webservices: HTTP SOAP WSDL
19-jul-17
Contacten
Voor bijkomende functionele informatie bij de KSZ, kan u een e-mail sturen naar:
[email protected]
317494189
4/4