MxService v2 |
  
|
MxService v2 |
|
Na domovské stránce aplikace (např https://localhost:8443/MxService) je od UMS 5.26 umístěn seznam webových služeb určené pro komunikaci s klienty podporujícími šifrování a stránek (pozor na konf. proměnné MainPageShowServiceDescriptions a MainPageShowDownloadLink), které aplikace poskytuje, spolu s odkazy na dynamicky generovaná WADL (WADL je u REST služeb obdobou WSDL u SOAP služeb). K dispozici jsou následující služby a webové stránky:
GET metoda list: MxService/v2/event/list?batch={MaxRecords}
•vrátí seznam zachycených událostí (JSON seznam struktur s položkami: id=ID události, ver=verze události (1 nebo 2), data=Base64 řetězec obsahující balíček s daty události)
•pracuje pouze se záznamy dané linky (login=LineId)
•parametr batch (maximální počet vrácených událostí) je nepovinný; defaultní hodnota 20
•metoda je ochráněna Basic autentifikací (ID linky/heslo z konfigurace)
DELETE metoda delete: MxService/v2/event/{EventId}
•odstraní zadanou událost z interní databáze
•pracuje pouze se záznamy dané linky (login=LineId)
•parametr EventId (ID události) je povinný
•metoda je ochráněna Basic autentifikací (ID linky/heslo z konfigurace)
POST metoda create: MxService/v2/file/{name}
•uloží soubor (text/přílohu datové zprávy) do interní databáze a vrátí identifikátor souboru, pod kterým si ho může příjemce zprávy stáhnout; identifikátor je pseudonáhodně vygenerovaný řetězec, aby ho nebylo možno jednoduše uhádnout
•Content-Type: application/octet-stream
•parametr name (jméno souboru) je povinný
•hlavička Encrypted (je soubor šifrovaný?) je nepovinná: 1=ano, 0=ne; defaultně je 1
•hlavička Overwrite (přepsat již existující soubor?) je nepovinná: 1=ano, 0=ne (pokud soubor již v úložišti existuje, vrací HttpStatus.CONFLICT); defaultně je 0
•hlavička RegNumber (registrační číslo klienta) je nepovinná
•hlavička TimeToLive (doba platnosti souboru) je udávána v hodinách a je nepovinná; defaultně je 72 hodin (3 dny)
•metoda je ochráněna Basic autentifikací (ID linky/heslo z konfigurace)
POST metoda create: MxService/v2/event/create
•vloží novou událost do interní databáze
•hlavička X-DataSMS-Content-Signature je povinná - obsahuje signaturu události; pokud signatura nesouhlasí s obsahem požadavku, vrátí služba chybu "Bad Request"
•hlavička X-DataSMS-LineId je povinná - obsahuje ID linky (musí být obsažen v konfigurační proměnné DataSMSLineIds); je-li zadán prázdný řetězec, k získání ID linky se použije hlavička X-DataSMS-RefId
•hlavička X-DataSMS-RefId je nepovinná - obsahuje identifikátor zákazníka; vytváří ho správce MxService a přidělí ho zákazníkovi (nutno nakonfigurovat v klientské aplikaci) a v konfiguraci MxService nastaví mapování mezi ním a ID linky
•tělo požadavku obsahuje binární data (balíček/blob s daty události), kterým služba nerozumí a nijak s nimi nepracuje
•vrátí ID události (EventId)
•bez autentifikace
POST metoda create_client: MxService/v2/file/client/{name}
•uloží zašifrovaný soubor (přílohu zprávy) do interní databáze a vrátí identifikátor souboru, pod kterým si ho může příjemce zprávy stáhnout; identifikátor je pseudonáhodně vygenerovaný řetězec, aby ho nebylo možno jednoduše uhádnout
•Content-Type: application/octet-stream
•parametr name (jméno souboru) je povinný; jméno souboru by mělo být co nejjednoznačnější, tj. nejlépe aby obsahovalo třeba nonce apod.
•hlavička X-DataSMS-Content-Signature je povinná - obsahuje signaturu události; pokud signatura nesouhlasí s obsahem požadavku, vrátí služba chybu "Bad Request"
•hlavička Overwrite (přepsat již existující soubor?) je nepovinná: 1=ano, 0=ne (pokud soubor již v úložišti existuje, vrací HttpStatus.CONFLICT); defaultně je 0
•hlavička RegNumber (registrační číslo klienta) je povinná
•hlavička TimeToLive (doba platnosti souboru) je udávána v hodinách a je nepovinná; defaultně je 72 hodin (3 dny)
•bez autentifikace
GET metoda get: MxService/v2/file
•vrátí šifrovaný (ENCRYPTED=1) soubor s daným identifikátorem (určeno ke stažení textu a příloh DataSMS zprávy)
•metoda je ochráněna Basic autentifikací (REG_NUMBER klienta / ID souboru)