Preskoči na glavno vsebino

API Ninja: Tréning 1/7 - Príprava testovacieho prostredia

V prvom tréningu sa pozrieme na prípravu testovacieho prostredia pre API

Avtor: Petr Pech

Získané schopnosti:

  • prehľad o možnostiach volania webových služieb

  • orientácia v príkazovom riadku

  • tvorba vlastného PHP skriptu

  • autentizácia

Pre tréning API Flexi a jeho testovanie je možné využiť niekoľko prístupov a aplikácií. Ukážeme si základné možnosti, kde si vytrénovať svoje schopnosti až na API Ninju. Zároveň sme pre Vás pripravili vlastné testovacie prostredie na adrese:

developer.flexibee.eu/c/ninja

Tu si môžete jednoducho testovať vlastné API triky.

Najjednoduchší možný prístup, ktorý však využijeme iba v prípade čítania dát, je Váš webový prehliadač. Zadáme požiadavku do adresného riadku prehliadača a prihlásime sa do Flexi štandardným spôsobom a získame presne dáta, ktoré potrebujeme. Príklady si neskôr ukážeme v úrovni Učeň, ktorú zvládne naozaj každý. Pokročilé testovanie, vrátane možnosti odosielať (zapisovať) dáta do ABRA Flexi, odporúčame vykonávať v programe Postman.

V prípade, že sa cítite ako Bojovník a nechcete inštalovať aplikáciu Postman, ponúka sa možnosť trénovať pomocou príkazového riadku systému a nástroja cURL. cURL je rozšírenie, pomocou ktorého je možné do príkazového riadku (CMD, Terminál) pridať ďalšie príkazy. Ak ste zatiaľ na úrovni Učeň, možno sa Vám už točí hlava z toho, čo čítate, ale nebojte sa, všetko si ukážeme ďalej.

Skutočný API Ninja, s ľahkou znalosťou jazyka PHP, má možnosť využiť knižnicu HTTPFul. HTTPFul je PHP knižnica vyvinutá pre jednoduchú a elegantnú komunikáciu s API rôznych aplikácií. S využitím tejto knižnice a jazyka PHP je možné vytvoriť vlastné šikovné skripty, spustiteľné napríklad používateľským tlačidlom. O tom viac neskôr v samostatnom tréningu.

A teraz si už ukážeme jednotlivé tréningové prostredia podľa úrovne.

Úroveň: Učeň

Pre učňov odporúčame dvoch mocných pomocníkov na API bojisku. So čítaním dát z Flexi nám pomôže webový prehliadač. Ešte mocnejší spolubojovník Postman nám pomôže aj s najzložitejším chvatom, čo sa týka zápisu a úpravy dát vo Flexi.

Využitie webového prehliadača

Neexistuje jednoduchší spôsob, ako získať konkrétny záznam alebo sadu záznamov z ABRA Flexi bez toho, aby sme spúšťali Flexi aplikáciu, zdĺhavo klikali a filtrovali, kým sa dostaneme k tomu, čo potrebujeme. Stačí využiť akýkoľvek webový prehliadač, na ktorý ste zvyknutí. Čo tak si napríklad stiahnuť faktúry po splatnosti do PDF alebo Excelu jedným kliknutím? Vyskúšajte.

Prejdite pomocou Vášho webového prehliadača na tieto adresy:

https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).pdf?report-name=fakturaKB

https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xls?detail=custom:kod&limit=0

Zvedavý učeň si všimne, že v adresnom riadku webového prehliadača sa občas objavia znaky s percentami, napríklad %3C. To z dôvodu zakódovania URL pre webový prehliadač, ktorý nepovoľuje špeciálne znaky a medzery v adrese. Viac si povieme v tréningu zostavovania URL.


Z prvej adresy získame PDF zostavu všetkých faktúr po splatnosti. Z druhého odkazu potom stiahneme Excel tabuľku s kódmi všetkých faktúr, ktoré sú k dnešnému dňu po splatnosti. Týmito jednoduchými trikmi je možné získať prehľad potrebných dát. Odkaz je možné upraviť pre svoju licenciu a uložiť do záložky prehliadača. Jednoduché, však, učedník? Užitočných príkladov sa nájde celá rada, iste Ťa napadnú ďalšie.
​

Webový prehliadač bohužiaľ nezvládne všetky triky.

Webový prehliadač nie je plnohodnotné testovacie prostredie. Poslúži iba v prípade, že chceme rýchlo čítať konkrétne dáta z Flexi. Ak by sme chceli napríklad faktúry upraviť, zmeniť dátum upomenutia, musíme k adrese ešte zaslať telo požiadavky metódou POST. Na to nám poslúži aplikácia Postman.
​

Aplikácia Postman

Postman je spoľahlivým spoločníkom každého API Učňa. Ponúka jednoduché grafické rozhranie a pomôže vám tak vykonávať aj najzložitejšie API triky a chvaty. Pozrieme sa teda, ako s ním spolupracovať. Postman je voľne na stiahnutie na adrese GetPostman, prípadne je možné pridať ho ako rozšírenie do Google Chrome, odporúčame však plnohodnotnú desktopovú aplikáciu.

Po úspešnej inštalácii sa dôkladne zorientujte v prostredí aplikácie. Pre akúkoľvek operáciu je najprv nutná autentizácia používateľa, urobíte tak na záložke Auth, kde vyplníte Vaše prihlasovacie údaje.

Pre náš API tréning postačí typ Basic Auth, čo je bežná HTTP autentizácia. Slovami pre učňa - obdobné prihlásenie ako priamo do webového rozhrania Flexi. Samozrejme je možný aj iný typ autentizácie, čo je však za hranicami poznania na úrovni Učeň.

Teraz sa zameriame na najdôležitejšiu oblasť v rozhraní Postmana. Sústreďte sa na číslované oblasti, vysvetlivky sú popísané nižšie. Týchto niekoľko bodov musí každý Učeň využívajúci Postmana poznať aj pri polnočnom cvičnom API chvate.

Ťažko na cvičisku, ľahko na bojisku!

1) Výber HTTP operácie

  • Postman ponúka širokú škálu podporovaných operácií, avšak pre prácu s Flexi nám momentálne postačia základné metódy HTTP - GET, POST, PUT, DELETE

Pre zvedavých učňov viac informácií tu
​

2) Pole pre zadanie URL adresy, s ktorou bude Postman pracovať

3) Výber formátu, v ktorom budú dáta posielané na danú URL

  • táto oblasť sa nás týka iba v prípade, že budeme dáta zasielať

  • POZOR – príponu URL adresy je nutné uvádzať zhodnú s formátom zasielaných dát

4) Výber podoby vytváraného requestu (štandardne raw)

  • táto oblasť súvisí s oblasťou 3 a taktiež nás zaujíma v prípade odosielania dát

5) Oblasť pre odpoveď

  • Flexi pri volaní API komunikuje späť, teda v tejto oblasti sa nám zobrazí odpoveď (response) Flexi, ak sme žiadali dáta, prípadne o priebehu požiadavky, či prebehla v poriadku alebo s chybou, v prípade, že sme zasielali dáta do ABRA Flexi

6) Telo požiadavky (request)

  • tu zapisujeme obsah svojej požiadavky v prípade zasielania dát do Flexi, napríklad vo formáte XML/JSON

Príklad hovorí za všetko, vyskúšame teda prvý chvat v Postmane. V záložke Auth vyplňte svoje prihlasovacie údaje (Kde ich vezmem?). Vyberte HTTP operáciu POST na adresu https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml.

A zapíšte raw telo požiadavky, vo formáte XML (application/xml) s nasledujúcim obsahom:

<?xml version="1.0" encoding="utf-8"?> 
  <winstrom version="1.0"> 
   <faktura-vydana> 
     <typDokl>code:FAKTURA</typDokl> 
     <firma>code:FLEXI</firma> 
     <popis>Ninja faktura z CURL</popis>
     <sumZklZakl>1000.0</sumZklZakl> 
     <bezPolozek>true</bezPolozek> 
   </faktura-vydana>
  </winstrom>

Zostáva Send! Success: true? Áno, učedník, práve si vytvoril faktúru vo Flexi pomocou API. Postman všetky príkazy ukladá do histórie, kedykoľvek sa k nim môžeš vrátiť.

Postman toho samozrejme vie viac, vydaj sa na prieskum, učedník.

Úroveň: Bojovník

Bojovník iste využije variantu, pre ktorú nie je nutná inštalácia aplikácie s grafickým rozhraním a vystačí si s príkazovým riadkom, pomocou ktorého môže dáta získať aj zaslať do ABRA Flexi.

cURL

cURL je príkaz, ktorý umožňuje jednoducho stiahnuť dáta z ľubovoľnej adresy, ale tiež je možné pomocou neho dáta odoslať na zadanú adresu. cURL je možné získať pre Váš systém na adrese https://curl.haxx.se/. V sekcii Download nájdete obsiahlu radu verzií, vyberte si vhodnú podľa Vášho operačného systému.

Na stránkach získate tiež informácie o inštalácii v závislosti od Vášho systému. V prípade Linuxu postačí pomocou príkazového riadku vykonať inštaláciu podľa vašej distribúcie. V prípade Windows bude pravdepodobne potrebné nastaviť systémovú premennú PATH. MacOS X obsahuje cURL už v základe a je možné ho začať hneď používať.

Utiahni si opasok, bojovník, ideme na to!

Ak máte pripravený cURL, vrhneme sa do príkazového riadku, teda "cmd" na Windows, "terminál" na Linux a Mac. Základný príkaz vyzerá nasledovne:

curl -u jmeno:heslo -L -o soubor.pdf

  • -u určuje autorizačné údaje do Flexi.

  • -L nasleduje presmerovanie. Ak v budúcnosti dôjde k zmene štruktúry URL, tento príkaz zaistí, že skript bude stále fungovať.

  • -o zaručí, že vrátené dáta budú zapísané do súboru "soubor.pdf".

  • -f určuje, že ak na strane servera nastane chyba, nemá sa nič zapisovať do výstupu, ale hneď ukončiť.

  • -k ak používate vlastnú inštaláciu a automaticky generovaný certifikát, je nutné ignorovať nedôveryhodnú certifikačnú autoritu.

  • -T zasielaný súbor (telo požiadavky)

Viac informácií o skladbe príkazov získate pomocou príkazu "curl --help".

Správny tréning si žiada vyskúšať nejaké triky. Napríklad získanie všetkých neuhradených faktúr do PDF súboru je možné nasledujúcim príkazom:

curl -u login:heslo -k -L -f "https://developer.flexibee.eu:5434/c/ninja/faktura-vydana/(stavUhrK%20!=%20%27stavUhr.uhrazeno%27).pdf" -o neuhrazene-faktury.pdf

Samozrejme je nutné namiesto login:heslo uviesť Vaše prihlasovacie údaje, ktoré získate pomocou formulára na konci prvého článku API Ninja seriálu. PDF súbor neuhrazene-faktury.pdf sa uloží do priečinka, kde sa práve nachádzate v príkazovom riadku.

Dokážeš uložiť súbor inam, bojovník?

Čítanie je teda veľmi jednoduché, obdobne je to aj so zápisom do Flexi. Uvažujme tvorbu faktúry. Aby sme mohli vytvoriť faktúru, budeme najprv potrebovať XML súbor s dátami. Vytvorte súbor faktura.xml s nasledujúcim obsahom:
​

<?xml version="1.0" encoding="utf-8"?> 
 <winstrom version="1.0"> 
  <faktura-vydana> 
   <typDokl>code:FAKTURA</typDokl> 
   <firma>code:FLEXI</firma> 
   <popis>Ninja faktura z CURL</popis> 
   <sumZklZakl>1000.0</sumZklZakl> 
   <bezPolozek>true</bezPolozek> 
  </faktura-vydana> 
 </winstrom>

Potom zostáva zavolať cURL príkaz z miesta v príkazovom riadku, kde je uložený vytvorený súbor. Odpoveď Flexi získate späť do príkazového riadku.

curl -u login:heslo -k -L https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml -T faktura.xml

Cítiš, že máš na viac, bojovník? Nebojíš sa vkročiť do oblasti PHP? Vyskúšaj úroveň Ninja a zaraď sa hneď v prvom tréningu do elitnej úrovne API Ninja.
​

Úroveň: Ninja

Ninja bojovník nikoho ďalšieho nepotrebuje. Vytvorí si svoje vybavenie a cvičisko sám. K tomu môže poslúžiť HTTPFul.

HTTPFul

HTTPFul je PHP knižnica, ktorá umožňuje jednoducho komunikovať pomocou HTTP protokolu v PHP prostredí. Tvorca knižnice uvádza na svojich stránkach aj možnosti, ako knižnicu nainštalovať. Samozrejme je potrebné mať na svojom počítači sprevádzkované PHP prostredie.

Pre naše potreby tréningu bude najvhodnejšia inštalácia variantou číslo 1. Stiahnutý súbor iba priradíme k nášmu skriptu:

<?php 
//Cesta ke staženému souboru include('./httpful.phar'); 
... 
?>

Potom môžeme pokračovať v našom skripte, ktorý obsahuje HTTPFul volanie API Flexi a potom výsledok vypíšeme na obrazovku:

<?php 
$flexiLogin = 'ninja'; 
$flexiHeslo = 1234; 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xml?limit=0; 

$response = \Httpful\Request::get($uri) 
 ->expectsXML() 
 ->authenticateWith($flexiLogin, $flexiHeslo) 
 ->send(); 

echo $response->body->winstrom->{'faktura-vydana'}; 
... 
?>

Takto najjednoduchšie získame XML všetkých faktúr po splatnosti. Ak budeme chcieť nejaké dáta do Flexi zaslať pomocou HTTPFul, najprv si dáta pripravíme vo formáte XML/JSON. Pre PHP využijeme najlepšie formát JSON, ktorý je možné jednoducho vytvoriť z PHP poľa.

A opäť zavoláme HTTPFul na pomoc s metódou POST:

<?php 
$idFaktury = 1; 
$faktura['winstrom']['faktura-vydana']['id'] = $idFaktury; $faktura['winstrom']['faktura-vydana']['varSym'] = '123456789'; 
$json = json_encode($faktura); 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana.json'; 
$response = \Httpful\Request::post($uri) 
  ->sendsJson()
  ->authenticateWith($flexiLogin, $flexiHeslo) 
  ->send(); 
... 
?>

Týmto skriptom sme vybranej faktúre zmenili variabilný symbol. Základy použitia knižnice ako nástroja pre prístup k API Flexi sme si ukázali. Skutočný API Ninja s ľahkou znalosťou PHP obohatí skripty o potrebné rozšírenia, ako odovzdať hodnoty či spracovať výsledky, to už však necháme na vašej tvorivosti.

Zoznámte sa dôkladne s vybraným testovacím prostredím. V ďalšom tréningu nás už čaká teória o štruktúre a zostavovaní URL.


​

Sorodni članki
Ste s tem dobili odgovor na svoje vprašanje?