Česká Golfová Federace Dokumentace rozhraní web služeb CT-Group, a.s.
Obsah: Účel 3 Základní informace 3 Adresa webové služby 4 Klientské certifikáty 4 Přehled konzumentů 4 Formát vstupních a výstupních parametrů 6 Popis jednotlivých metod 9 TURNAJE 9 ČLENSTVÍ 11 HŘIŠTĚ 12 KLUBY 16 TURNAJOVÉ VÝSLEDKY, REGISTRACE 16 2
Účel Dokumentace popisuje způsob a technické parametry připojení k vybraným datům Federačního serveru ČGF. Přístup je umožněn skrze webovou službu obsahující řadu dále popsaných metod, které jsou zabezpečeny certifikátem. Dokumentace popisuje: adresu uložení webové služby kategorie oprávněných konzumentů a rozsah poskytovaných dat způsob komunikace formát parametrů metod vzor výstupu struktury typu dataset Základní informace Komunikace s datovým úložištěm probíhá výhradně pomocí webových služeb provozovaných na protokolu SOAP (nad HTTPS) s autentizací uživatele pomocí klientského certifikátu (TLS/SSL). Pro volání služeb je nutné použít metodu POST. Požadavky, které nejsou certifikátem podepsány nebo jsou podepsány neznámým certifikátem jsou zamítnuty, veškeré požadavky jsou zaznamenávány do logu. Certifikát je přiřazen uživatelskému účtu a určuje tak jednoznačně konzumenta Klub, Pořadatel atd. Přiřazování certifáktů uživatelským účtům je plně pod kontrolou správců systému. Popis funkcí, přijímaných i odesílaných dat je definován WSDL, které je k dispozici na adrese služby. Volání webové služby je možné z libovolné platformy/prostředí podmínkou je pouze podpora webových služeb a certifikátů. 3
Adresa webové služby Webová služba je dostupná na adrese https://ws.cgf.cz/cgsdataprovider/dataservice.asmx S ohledem na použití protokolu https a plánované zátěži nepodléhá tato služba loadbalancingu. Klientské certifikáty Všichni konzumenti webových služeb musí mít pro svou identifikaci vydán certifikát. Jedná se o standardní certifikát podle X509. Musí jím být podepsány všechny požadavky na data, musí být tedy umístěn na serveru, který o data žádá. Přehled konzumentů Odstavec popisuje jednotlivé kategorie konzumentů a rozsah dat, která jsou oprávněni čerpat. Na základě identifikace konzumenta jsou interně nastaveny rozsahy poskytovaných dat. Rozsah dat je zabudován do webových metod. Jde o omezení na množinu dat se vztahem ke konzumentovi. Kategorie konzumentů Pro účely stanovení rozsahu dat se definují tyto kategorie konzumenta: Klub Pořadatel Spolupořadatel Federace Hřiště Vlastník žebříčku Informační server 4
Definice rozsahu dat Rozsah dat je dán následující tabulkou: Turnaje 1 Žebříčky Členové Hřiště Klub Klub Turnaje a nesoutěžní výsledky jejichž je klub pořadatelem nebo spolupořadatelem Žebříčky vlastněné tímto subjektem Pořadatel Turnaje a Žebříčky nesoutěžní vlastněné výsledky jejichž tímto je pořadatelem subjektem nebo spolupořadatelem Spolupořadatel Turnaje jejichž je Žebříčky spolupořadatelem vlastněné tímto subjektem Vlastník Turnaje a Žebříčky žebříčku nesoutěžní vlastněné výsledky tímto obsažené v tomto subjektem žebříčku Informační Turnaje žebříčky dle server v omezeném výběru rozsahu informací a omezeném časovém intervalu Tabulka rolí a přístupů viz barevné značky u jednotlivých metod Členové klubu informace o smluvních hřištích základní přehled klubů --- --- základní přehled klubů --- --- základní přehled klubů --- --- --- --- informace základní o hřištích přehled se klubů vztahem k federaci 1 maximálně v rozsahu 360 dnů (tam i zpět) 5
CLUB ORGANIZER COORGANIZER MATCH_OWNER CONSUMER TOURNAMENT MEMBERS COURSE CLUB Formát vstupních a výstupních parametrů Parametry se zasílají metodou POST uložené v SOAP. U položek typu datum a číslo je potřeba respektovat formát definovaný normou XML. Příklady volání a odpovědí jsou součástí WSDL a popisu jednotlivých operací a jsou dostupné pomocí www prohlížeče na adrese služby. Návratová hodnota je typu long (celočíselný 64bit), nebo DataTable. Vzorová odpověď včetně XSD popisu DataTable: <?xml version="1.0" encoding="utf-8"?> - <DataTable xmlns="http://cgf.cz/"> - <xs:schema id="newdataset" xmlns="" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> - <xs:element name="newdataset" msdata:isdataset="true" msdata:maindatatable="getclubs" msdata:usecurrentlocale="true"> - <xs:complextype> - <xs:choice minoccurs="0" maxoccurs="unbounded"> - <xs:element name="getclubs"> - <xs:complextype> - <xs:sequence> <xs:element name="idclub" type="xs:decimal" minoccurs="0" /> <xs:element name="codenumber" type="xs:string" minoccurs="0" /> <xs:element name="name" type="xs:string" minoccurs="0" /> <xs:element name="shortname" type="xs:string" minoccurs="0" /> <xs:element name="regionname" type="xs:string" minoccurs="0" /> <xs:element name="countryname" type="xs:string" minoccurs="0" /> <xs:element name="golfregname" type="xs:string" minoccurs="0" /> <xs:element name="federationname" type="xs:string" minoccurs="0" /> <xs:element name="state" type="xs:string" minoccurs="0" /> </xs:sequence> </xs:complextype> </xs:element> 6
</xs:choice> </xs:complextype> </xs:element> </xs:schema> - <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoftcom:xml-diffgram-v1"> - <NewDataSet xmlns=""> - <GetClubs diffgr:id="getclubs1" msdata:roworder="0"> <IDCLUB>63907329</IDCLUB> <CODENUMBER>143</CODENUMBER> <NAME>Albatross Golf Club</NAME> <SHORTNAME>ALBGC</SHORTNAME> <REGIONNAME>Středočeský</REGIONNAME> <COUNTRYNAME>Česká republika</countryname> <GOLFREGNAME>ZÁPAD B</GOLFREGNAME> <FEDERATIONNAME>Česká golfová federace</federationname> <STATE>VALID</STATE> </GetClubs> - <GetClubs diffgr:id="getclubs2" msdata:roworder="1"> <IDCLUB>96213519</IDCLUB> <CODENUMBER>074</CODENUMBER> <NAME>Amatérský golfový club Victoria</NAME> <SHORTNAME>AGCVA</SHORTNAME> <REGIONNAME>Jihočeský</REGIONNAME> <COUNTRYNAME>Česká republika</countryname> <GOLFREGNAME>ZÁPAD A</GOLFREGNAME> <FEDERATIONNAME>Česká golfová federace</federationname> <STATE>VALID</STATE> </GetClubs> </NewDataSet> </diffgr:diffgram> </DataTable> Příklad voláni podle SOAP 1.2: POST /DataService.asmx HTTP/1.1 Host: localhost Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> 7
<soap12:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <GetClubs xmlns="http://cgf.cz/" /> </soap12:body> </soap12:envelope> HTTP/1.1 Příklad HTTP odpovědi serveru: HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <GetClubsResponse xmlns="http://cgf.cz/"> <GetClubsResult>xmlxml</GetClubsResult> </GetClubsResponse> </soap12:body> </soap12:envelope> 8
Popis jednotlivých metod TURNAJE public DataTable GetOrganizedTournaments(DateTime datefrom, DateTime dateto) konzumenti: Klub, Pořadatel Nejvýše jeden rok vpřed i vzad. Vrací turnaje pořádané nebo spolupořádané konzumentem. datefrom DateTime Počáteční datum dotazu dateto DateTime Koncové datum dotazu viz. souhrnná tabulka návratových hodnot turnajových metod public DataTable GetCourseTournaments(DateTime datefrom, DateTime dateto) konzumenti: Klub Vrací turnaje pořádané na hřišti přiřazeném konzumentovi. Nejvýše jeden rok vpřed i vzad. datefrom DateTime Počáteční datum dotazu dateto DateTime Koncové datum dotazu viz. souhrnná tabulka návratových hodnot turnajových metod 9
public DataTable GetMatchTournaments(long IdMatch) konzumenti: Vlastník žebříčku Vrací turnaje, které jsou součástí žebříčku idmatch Long Id žebříčku viz. souhrnná tabulka návratových hodnot turnajových metod Návratové hodnoty dotazovacích metod u turnajů: IDTOURNAMENT Id turnaje NAME Název turnaje SHORTNAME Zkrácený název turnaje DATE_ACTION_FROM Datum konání od DATE_ACTION_TO Datum konání do TOURNAMENTTYPE Typ turnaje (interní, vždy O) ONLY_FOR_MEMBERS Pouze pro členy REDUCTION_ONLY V turnaji je evidováno kolo, vyhodnocené pouze pro snižování HCP AUTOGENERATE_STARTLIST Automatické generování startovní listiny (zatím nevyužito) DESCRIPTION Popis turnaje CAPACITY Kapacita turnaje ROUND_COUNT Počet kol v turnaji PARAMS Aditivní XML parametry v tu MIN_REGISTRATIONS Minimální počet registrací DATE_REGISTRATION_FROM Povolené počáteční datum registrace DATE_REGISTRATION_TO Ukončení veřejných registrací WWW_REGISTRATIONS Počet veřejných registrací 10
COURSENAME COUNTDAYS ISFEDERATION Název hřiště Počet dnů trvání turnaje Příznak, zda je turnaj pořádán federací, nebo podřízeným subjektem (region) Aditivní XML parametry turnaje (textové popisy): SETTING_METHOD String Pravidla startu PRIZE String Ceny FORM_OF_REGISTRATION String Způsob registrace WINNER String Vítězství REFUNDCOST string Náhrada BOARDING string Stravování FEE string Poplatky DIRECTOR string Ředitel soutěže BOARD string Soutěžní výbor RESERVATION_NOTE string Poznámka k rezervacím ČLENSTVÍ public DataTable GetMembers(bool ValidOnly) konzumenti: Klub Vrací členy klubu. ValidOnly bool Pouze platná členství IDGOLFER IDMEMBERSHIP NAME FIRSTNAME1 AFTERTITLE Id golfisty Id členství Příjmení hráče Křestní jméno hráče Titul před jménem 11
BEFORETITLE AGE AGECATEGORY FULLNAME IDCLUB MEMBERNUMBER HOMEMEMBER HCPSTR HCPNUM CLUBNAME CLUBCODE CLUBSHORTNAME MEMVALIDFROM MEMVALIDTO MEMBLOCK Titul za jménem Věk Věková kategorie Celé jméno hráče id klubu Členské číslo Příznak domovského členství HCP v řetězcovém tvaru (BEZ,PRO ) Číselný ekvivalent hendikepu Název klubu Kód klubu Zkrácený název klubu Platnost členství od Platnost členství do Příznak blokace člena HŘIŠTĚ public DataTable GetClubCourses() konzumenti: Klub Vrací smluvní hřiště pro konzumenta. - NAME IDCOURSE Název hřiště Id hřiště 12
public DataTable GetCourses() Vrací seznam všech hřišť. - IDCOURSE CODENUMBER NAME SHORTNAME TYPE HOLESCOUNT APPROVE REGIONNAME COUNTRYNAME ADDRESS CITY GOLFREGION Id hřiště Kód hřiště Název hřiště Zkratka hřiště Typ (IN/OUT) Počet jamek Schválené normované hřiště Název regionu Název státu Adresa hřiště Město Golfový region public DataTable GetStipulatedRounds(long IdCourse) Vrací seznam předepsaných kol hřiště IdCourse Long Id hřiště 13
IDSTIPULATEDROUND Id předepsaného kola IDCOURSE Id hřiště NAME Název předepsaného kola APPROVED Schváleno (Y/N) DESCRIPTION Popis SHORTNAME Zkrácený název CODE Kód TYPE Typ předepsaného kola (počet jamek 9/18) VALIDFROM Platné od VALIDTO Platné do HCPCORRECTIONTYPE Jaké HCP je možné na hřišti upravovat: - None - CLUB - EGA public DataTable GetStipRoundParams(long IdStipulatedRound) Vrací tabulku paremetrů předepsaného kola IdStipulatedRound Long Id předepsaného kola IDSTIPROUNDPARAM IDSTIPULATEDROUND NORM_MF PAR_SUM LENGTH_SUM USGA_COURSE_RATING BOGEY_SLOPE_RATING Id parametru předepsaného kola Id předepsaného kola Norma muži/ženy (M/F) Par předepsaného kola Celková délka předepsaného kola Course rating Slope rating 14
SSS VALIDFROM VALIDTO COLORCODE ORD Dnes nepoužívané SSS Platnost od Platnost do Barva odpaliště Pořadí odpaliště public DataTable GetStipRoundHoles(long IdStipulatedRound,string codecolor) Vrací jamky i s parametry pro danou barvu odpaliště IdStipulatedRound Long Id předepsaného kola codecolor String Kód barvy odpaliště IDSTIPROUNDHOLE IDHOLE HOLECODE HOLENAME HOLENUMBER HOLEAPPROVE IDCOURSEPARTITION COURSEPARTNAME COURSEPARTCODE HCPINDEX STIPROUND_ORDER LENGTH PAR_M PAR_F Id vazby jamky na předepsané kolo Id Jamky Kód jamky Název jamky Index jamky Schválená normovaná jamka Id části hřiště Název části hřiště Kód části hřiště HCP index Pořadí jamky v předepsaném kole Délka jamky z daného odpaliště Par muži Par ženy 15
KLUBY public DataTable GetClubs() Vrací seznam všech klubů - IDCLUB CODENUMBER NAME SHORTNAME REGIONNAME COUNTRYNAME GOLFREGNAME FEDERATIONNAME STATE Id klubu Kód klubu Název Zkratka Název regionu Název státu Název golfového regionu Federace Platnost TURNAJOVÉ VÝSLEDKY, REGISTRACE, STARTOVNÍ LISTINA public DataTable GetTournamentCategories(long IdTournament) Vrací konzumentovi kategorie turnaje. IdTournament Long Id turnaje 16
IDTOURNAMENTCATEGORY Id kategorie turnaje NAME Název kategorie CATEGORY_CAPACITY Kapacita kategorie turnaje IDPLAYINGSYSTEM Hrací systém HANDICAPUSE S vyrovnáním HCP HCPCORRECTION S úpravou HCP ORDERNUM Pořadí kategorie ve výpise ONLY_FOR_MEMBER Kategorie pouze pro členy LIMITHCP Limitní hendikep MAIN Příznak hlavní kategorie REGISTRATIONORDERING Princip řazení přihlášek (DATE/HCP) COEFFICIENT_HCP Použitý krácený HCP koeficientem (3/4..) REGISTERED Počet registrovaných hráčů v kategorii PLAYINGSYSTEMDATE Název hracího systému public DataTable GetResults(long IdTournamentCategory) Vrací konzumentovi výsledky turnaje. IdTournamentCategory Long Id soutěžní kategorie pro vyhodnocení FULLNAME IDRESULTTOURNAMENT IDGOLFER IDTOURNAMENTCATEGORY STABLEFORD_RES Celé jméno hráče Id výsledku Id hráče Id kategorie turnaje Stableford body pro výpočet HCP 17
ORDER_FROM ORDER_TO SCORE HCP_BEFORE HCP_RES USED_IN_MATCH CLUB SCR1..SCR4 Umístění Umístění do (pokud je dělené) Score podle pravidla kategorie HCP před turnajem HCP po turnaji Příznak, zda je výsledek započítán do žebříčku Zkratka klubu Score za jednotlivá kola public long RegisterToTournament(long IdGolfer, long IdTournament) Přihlášení hráče na turnaj. IdGolfer long Id hráče IdTournament long Id turnaje -152 Hráč je blokován -160 Turnaj je v minulosti -181 Nenastal čas registrace -182 Vypršel čas registrace -200 Je překročena kapacita turnaje -220 Je vyčerpána kapacita veřejných přihlášek -230 Nebylo nalezeno domovské členství -210 Hráč je přihlášen na jiný turnaj na úpravu HCP 18
public DataTable GetTournamentRegistrations(long IdTournament, long IdTournamentCategory) Vrací konzumentovi přihlášky do turnaje IdTournament Long Id turnaje IdTournamentCategory Long Id kategorie turnaje IDREGISTRATION IDGOLFER MEMBERNUMBERACTUAL HCPNUM HCPSTR MEMBERNUMBER CLUBSHORTNAME FULLNAME SEX CLUBNAMEACTUAL FOREIGNCLUB Id registrace Id hráče Členské číslo hráče Numerická hodnota HCP HCP Členské číslo hráče v době přihlášky Zkratka domovského klubu v době přihlášky Celé jméno Pohlaví hráče Zkratka klubu Název klubu u zahraničního hráče public DataTable GetTournamentRounds(long IdTournament) Vrací konzumentovi kola turnaje turnaje IdTournament Long Id turnaje IDTOURNAMENTROUND Id kola turnaje 19
IDTOURNAMENT ORDERNUM IDCOURSE CLOSED REDUCTION_ONLY PLAYINGDATE CSA COURSENAME Id turnaje Číslo kola Id hřiště Uzavřené kolo (Y/N) Kolo pouze pro snižování HCP (Y/N) Datum odehrání kola XML tabulka výpočtu CSA Název hřiště public DataTable GetTournamentStartList(long IdTournament, long IdTournamentRound, long IdTournamentCategory) Vrací konzumentovi startovní listinu za kategorii, nebo souhrnnou (IdTournamentCategory = -1). IdTournament Long Id turnaje IdTournamentRound Long Id kola turnaje IdTournamentCategory Long Id kategorie turnaje, pokud je -1, pak se jedná o souhrnnou výsledkovou listinu STARTTIME FLIGHTNUM STARTHOLE G1..G4 CODECOUNTRY1..CODECOUNTRY4 NAME1..NAME4 TeeTime Číslo flightu Jamka ze které hráč startuje Id hráče na pozicích 1..4 ve flightu Kód země hráče na pozicích 1..4 ve flightu Jméno hráče na pozicích 1..4 ve flightu 20
ŽEBŘÍČKY public DataTable GetMatchList() Vrací seznam žebříčků - IDMATCH NAME CODE DESCRIPTION CREATED_DATE STATUS IDSUBJECT VALIDFROM VALIDTO RESULT_FORMAT RESULT_TYPE Id žebříčku Název žebříčku Kód žebříčku Popis Datum vytvoření Stav Id vlastníka Platnost od Platnost do public DataTable GetMatchCategory(long IdMatch) Vrací kategorie žebříčku IdMatch Long Id soutěže IDMATCHCATEGORY NAME CODE Id kategorie žebříčku Název kategorie žebříčku Kód kategorie žebříčku 21
RANKINGDATE Datum posledního přepočtení public DataTable getmatchrankings(long IdMatchCategory) Vrací pořadí v kategorii žebříčku IdMatchCategory Long Id kategorie soutěže IDRANKING IDGOLFER GOLFERFULLNAME IDTEAM CLUBSHORTNAME ORDER_FROM ORDER_TO ORDER_STRING RESULT SCORES HCP Id umístění Id hráče Celé jméno hráče Id týmu, pokud jde o žebříček družstev Zkratka domovského klubu Umístění Umístění (dolní hranice, pokud se jedná o dělené umístění) Řadící řetězec, dle aplikovaných pravidel Výsledek Dílčí výsledky HCP v době přepočtení ONLINE SCORING public DataTable GetOnlineScoringResults(LibDB DB,long idtournamentcategory) Vrací pořadí, podle odchylky od paru 22
IdTournamentCategory Long Id soutěžní kategorie pro vyhodnocení FULLNAME MEMBERNUMBER IDRESULTTOURNAMENT IDGOLFER IDTOURNAMENTCATEGORY STABLEFORD_RES ORDER_FROM ORDER_TO SCORE HCP_BEFORE HCP_RES USED_IN_MATCH CLUB SCR1..SCR4 DIFF_PAR INX_HOLEPLAYED CODECOUNTRY Celé jméno hráče Členské číslo Id výsledku Id hráče Id kategorie turnaje Stableford body pro výpočet HCP Umístění Umístění do (pokud je dělené) Score podle pravidla kategorie HCP před turnajem HCP po turnaji Příznak, zda je výsledek započítán do žebříčku Zkratka klubu Score za jednotlivá kola Odchylka od paru Číslo právě hrané jamky Kód země 23