Web SPSSoftware • Znalostní báze

Autor: sutrus

Datum: 20 bře 2022 16:24

Zobrazení: 163

Popis:

Přehled
Termín "REST API" obecně označuje rozhraní API, ke kterému se přistupuje prostřednictvím protokolu HTTP na předem definované sadě adres URL orientovaných na zdroje.
Od verze RouterOS v7.1beta4 je implementováno jako obalové rozhraní JSON konzolového rozhraní API. Umožňuje vytvářet, číst, aktualizovat a mazat prostředky a volat libovolné konzolové příkazy.

Chcete-li začít používat rozhraní REST API, musí být nakonfigurována a spuštěna služba www-ssl [odkaz na služby IP]. Je-li služba SSL povolena, lze ke službě REST přistupovat připojením na adresu https://<routers_IP>/rest.

Nejjednodušší způsob, jak začít, je použít cURL, wget nebo jiného klienta HTTP, dokonce i nástroj RouterOS fetch.

Kód: Vybrat vše

$ curl -k -u admin: https://10.155.101.214/rest/system/resource
[{"architecture-name":"tile","board-name":"CCR1016-12S-1S+",
"build-time":"Dec/04/2020 14:19:51","cpu":"tilegx","cpu-count":"16",
"cpu-frequency":"1200","cpu-load":"1","free-hdd-space":"83439616",
"free-memory":"1503133696","platform":"MikroTik",
"total-hdd-space":"134217728","total-memory":"2046820352",
"uptime":"2d20h12m20s","version":"7.1beta4 (development)"}]

Autentizace
Ověřování k rozhraní REST API se provádí pomocí HTTP Basic Auth. Zadejte uživatelské jméno a heslo stejné jako pro uživatele konzole (ve výchozím nastavení "admin" bez hesla).

!	Varování:
	Pro použití zabezpečeného protokolu HTTPS je třeba nastavit certifikáty. Pokud se používají certifikáty podepsané vlastním jménem, je třeba importovat certifikační autoritu do důvěryhodného kořenového systému. Pro účely testování je však možné připojit se nezabezpečeně (pro cUrl použijte příznak -k, pro wget --no-check-certificate).

Formát JSON
Server se v zásadě řídí standardem ECMA-404 s následujícími poznámkami:

V odpovědích JSON jsou všechny hodnoty objektů kódovány jako řetězce, i když jsou podkladovými daty čísla nebo logické hodnoty.
Server také přijímá čísla v osmičkovém formátu (začíná 0) a šestnáctkovém formátu (začíná 0x). Pokud jsou čísla zasílána ve formátu řetězce, předpokládá se, že jsou v desítkovém formátu.
Čísla s exponenty nejsou podporována.

Metody HTTP
Níže je uvedena tabulka shrnuje podporované metody HTTP.

HTTP Verv	CRUD	ROS	Popis
GET	Read	print	Získání záznamů
PATCH	Update/Modify	set	Aktualizace jednoho záznamu
PUT	Create	add	Vytvoření nového záznamu
DELETE	Delete	remove	Smazání jednoho záznamu
POST			Univerzální metoda pro získání přístupu ke všem konzolovým příkazům

Formát adresy URL

GET
Tato metoda umožňuje získat seznam všech záznamů nebo jeden záznam ze zadané nabídky zakódované v adrese URL.
Například získat všechny IP adresy (ekvivalentní příkazu 'ip/adresa/print' z CLI):

Kód: Vybrat vše

$ curl -k -u admin: https://10.155.101.214/rest/ip/address
[{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"},
{".id":"*2","actual-interface":"ether3","address":"10.0.0.109/24","disabled":"true",
"dynamic":"false","interface":"ether3","invalid":"false","network":"10.0.0.0"}]

Chcete-li vrátit jeden záznam, připojte ID na konec adresy URL:

Kód: Vybrat vše

$ curl -k -u admin: https://10.155.101.214/rest/ip/address/*1
{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}

Pokud tabulka obsahuje pojmenované parametry, lze použít jméno místo ID, například get ether1:

Kód: Vybrat vše

$ curl -k -u admin: https://10.155.101.214/rest/interface/ether1

Výstup je možné také filtrovat, například vrátit pouze platné adresy, které patří do sítě 10.155.101.0:

Kód: Vybrat vše

$ curl -k -u admin: "https://10.155.101.214/rest/ip/address?network=10.155.101.0&dynamic=true"
[{".id":"*8","actual-interface":"sfp12","address":"10.155.101.214/24","disabled":"false",
"dynamic":"true","interface":"sfp12","invalid":"false","network":"10.155.101.0"}]

Jiný příklad vrátí pouze adresy na "fiktivním" rozhraní a s komentářem "test":

Kód: Vybrat vše

$ curl -k -u admin: 'https://10.155.101.214/rest/ip/address?comment=test&interface=dummy'
[{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}]

Pokud chcete vrátit pouze konkrétní vlastnosti, můžete použít '.proplist', následovaný znakem '=' a seznamem vlastností oddělených čárkou. Například pro zobrazení pouze adresy a pokud je zakázána:

Kód: Vybrat vše

$ curl -k -u admin: https://10.155.101.214/rest/ip/address?.proplist=address,disabled
[{"address":"10.0.0.111/24","disabled":"false"},{"address":"10.0.0.109/24","disabled":"true"}]

PATCH
Tato metoda se používá k aktualizaci jednoho záznamu. Nastavte tělo volání PATCH jako objekt JSON, který obsahuje pole a hodnoty aktualizovaných vlastností. Například přidání komentáře:

Kód: Vybrat vše

Kód: Vybrat vše

$ curl -k -u admin: -X PATCH https://10.155.101.214/rest/ip/address/*3 \
  --data '{"comment": "test"}' -H "content-type: application/json"
{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}

V případě úspěšné aktualizace vrátí server aktualizovaný objekt se všemi jeho parametry.

PUT
Metoda slouží k vytvoření nových záznamů v nabídce zakódované v adrese URL. Tělo by mělo být nastaveno jako objekt JSON obsahující parametry použité na nově vytvořený záznam.
V případě úspěchu server vrátí vytvořený objekt se všemi parametry.
V rámci jednoho požadavku lze vytvořit pouze jeden prostředek.

Například přidání IP adresy do fiktivního rozhraní:

Kód: Vybrat vše

$ curl -k -u admin: -X PUT https://10.155.101.214/rest/ip/address \
  --data '{"address": "192.168.111.111", "interface": "dummy"}' -H "content-type: application/json"
{".id":"*A","actual-interface":"dummy","address":"192.168.111.111/32","disabled":"false",
"dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.111.111"}

DELETE
Tato metoda slouží k odstranění záznamu se zadaným ID z nabídky zakódované v adrese URL. Pokud se smazání podařilo, server odpoví prázdnou odpovědí. Například volání pro odstranění záznamu dvakrát, při druhém volání router vrátí chybu 404:

Kód: Vybrat vše

$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
{"error":404,"message":"Not Found"}

POST
Všechny funkce rozhraní API jsou k dispozici prostřednictvím metody POST. Příkazové slovo je zakódováno v hlavičce a volitelné parametry jsou předávány v objektu JSON s odpovídajícími poli a hodnotami. Chcete-li například změnit heslo aktivního uživatele, odešlete příkaz

Kód: Vybrat vše

POST https://router/rest/password
{"old-password":"old","new-password":"N3w", "confirm-new-password":"N3w"}

Odpověď REST má podobnou strukturu jako odpověď API:

Pokud odpověď obsahuje věty '!re' (záznamy), bude odpověď JSON obsahovat seznam objektů
Pokud věta "!done" obsahuje data, bude odpověď JSON obsahovat objekt s daty
Pokud věta "!done" neobsahuje žádné záznamy ani data, bude odpověď obsahovat prázdný seznam

Existují dva speciální klíče: .proplist a .query, které se používají s příkazovým slovem print. Více informací o odpovědích, proplistech a dotazech API najdete v dokumentaci API.

Proplist
The '.proplist' key is used to create .proplist attribute word. The values can be a single string with comma-separated values:

Kód: Vybrat vše

POST https://router/rest/interface/print
{".proplist":"name,type"}

nebo seznam řetězců:

Kód: Vybrat vše

POST https://router/rest/interface/print
{".proplist":["name","type"]}

Například vracení adresy a vlastností rozhraní ze seznamu ip/adresa:

Kód: Vybrat vše

$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print\
  --data '{"_proplist": ["address","interface"]}' -H "content-type: application/json"
[{"address":"192.168.99.2/24","interface":"dummy"},
{"address":"172.16.5.1/24","interface":"sfpplus1"},
{"address":"172.16.6.1/24","interface":"sfp2"},
{"address":"172.16.7.1/24","interface":"sfp3"},
{"address":"10.155.101.214/24","interface":"sfp12"},
{"address":"192.168.111.111/32","interface":"dummy"}]

Query
Klíč '.query' se používá k vytvoření zásobníku dotazů. Hodnotou je seznam slov dotazu. Například tento požadavek POST :

Kód: Vybrat vše

POST https://router/rest/interface/print
{".query":["type=ether","type=vlan","#|!"]}

odpovídá této větě API

Kód: Vybrat vše

/interface/print
?type=ether
?type=vlan
?#|!

Zkombinujme například 'query' a 'proplist', abychom vrátili vlastnosti '.id', 'address' a 'interface' pro všechny dynamické záznamy a záznamy se sítí 192.168.111.111.

Kód: Vybrat vše

$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print \
  --data '{".proplist": [".id","address","interface"], ".query": ["network=192.168.111.111","dynamic=true","#|"]}'\
  -H "content-type: application/json"
[{".id":"*8","address":"10.155.101.214/24","interface":"sfp12"},
{".id":"*A","address":"192.168.111.111/32","interface":"dummy"}]

Časový limit
Pokud příkaz poběží neomezeně dlouho, dojde k vypršení časového limitu a připojení se ukončí s chybou. Aktuální interval timeoutu je 60 sekund. Chcete-li se vyhnout chybám timeoutu, přidejte parametr, který by dostatečně omezil dobu provádění příkazu.

!	Varování:
	Časový limit není ovlivněn parametry předanými příkazům. Pokud je příkaz nastaven tak, že má běžet hodinu, ukončí se předčasně a vrátí chybové hlášení.

Podívejme se například, co dostaneme, když příkaz ping překročí časový limit, a jak tomu zabránit přidáním parametru count:

Kód: Vybrat vše

$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
  --data '{"address":"10.155.101.1"}' \
  -H "content-type: application/json"
{"detail":"Session closed","error":400,"message":"Bad Request"}
 
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
  --data '{"address":"10.155.101.1","count":"4"}' \
  -H "content-type: application/json"
[{"avg-rtt":"453us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"453us","packet-loss":"0","received":"1","sent":"1","seq":"0","size":"56","time":"453us","ttl":"64"},
{"avg-rtt":"417us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"382us","packet-loss":"0","received":"2","sent":"2","seq":"1","size":"56","time":"382us","ttl":"64"},
{"avg-rtt":"495us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"382us","packet-loss":"0","received":"3","sent":"3","seq":"2","size":"56","time":"650us","ttl":"64"},
{"avg-rtt":"461us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"359us","packet-loss":"0","received":"4","sent":"4","seq":"3","size":"56","time":"359us","ttl":"64"}]

Dalším příkladem je nástroj pro testování šířky pásma, který může být omezen poskytnutím doby trvání běhu:

Kód: Vybrat vše

$ curl -k -u admin: -X POST 'https://10.155.101.214/rest/tool/bandwidth-test' \
  --data '{"address":"10.155.101.1","duration":"2s"}' \
  -H "content-type: application/json"
[{".section":"0","connection-count":"20","direction":"receive","lost-packets":"0",
"random-data":"false","rx-10-second-average":"0","rx-current":"0","rx-size":"1500",
"rx-total-average":"0",
"status":"connecting"},
{".section":"1","connection-count":"20","direction":"receive","duration":"1s",
"lost-packets":"0","random-data":"false","rx-10-second-average":"0","rx-current":"0",
"rx-size":"1500","rx-total-average":"0",
"status":"running"},
{".section":"2","connection-count":"20","direction":"receive","duration":"2s",
"lost-packets":"581175","random-data":"false","rx-10-second-average":"854372352",
"rx-current":"854372352","rx-size":"1500","rx-total-average":"854372352",
"status":"running"},
{".section":"3","connection-count":"20","direction":"receive","duration":"3s",
"lost-packets":"9014","random-data":"false","rx-10-second-average":"891979008",
"rx-current":"929585664","rx-size":"1500","rx-total-average":"891979008",
"status":"done testing"}]

Chyby
Úspěšnost nebo neúspěšnost volání API je indikována stavovým kódem HTTP. V případě selhání (stavový kód 400 nebo větší) obsahuje tělo odpovědi objekt JSON s kódem chyby, popisem chyby a volitelnými podrobnostmi o chybě. Například při pokusu o odstranění rozhraní se vrátí následující údaje

Kód: Vybrat vše

{"error":406,"message":"Not Acceptable","detail":"no such command or directory (remove)"}