Data Domain: Jak používat integrované rozhraní REST API pro systémy DD a DDMC

Nejnovější dokumentaci naleznete na https://developer.dell.com/apis/products/data-protection.

DD i DDMC byly ve výchozím nastavení dodávány s povoleným webovým rozhraním REST API. Rozhraní REST API je prostředek pro programovou interakci se systémy DD a nástroji DDMC. V tomto článku jsou uvedeny příklady systémů DD, které od nynějška používají jednoduchý protokol klienta a serveru. Protokol HTTP neuchovává žádný stav a umožňuje klientovi číst stav ze systémů DD a spouštět příkazy se speciálně vytvořenými voláními HTTP.

Následující příkaz z příkazového řádku informuje o stavu webové služby REST API (webová služba):

# adminaccess show
Service       Enabled   Allowed Hosts
-----------   -------   ---------------------
ssh           yes       -
scp           yes       (same as ssh)
telnet        no        DD3300.example.com
                        DD3300.example.com
ftp           no        DD3300.example.com
                        DD3300.example.com
ftps          yes       -
http          yes       -
https         yes       -
web-service   yes       N/A
-----------   -------   ---------------------
...

Upozorňujeme, že rozhraní REST API je obsluhováno ze stejných portů jako uživatelské rozhraní, a proto jej nelze zakázat samostatně. To nepředstavuje žádné bezpečnostní riziko, protože všechny požadavky na rozhraní API musí být ověřeny stejným způsobem jako požadavky na uživatelské rozhraní nebo rozhraní příkazového řádku.

Nejlepší způsob, jak začít s rozhraním REST API, je používat přibaleného klienta v každém systému DD a nástroji DDMC. Lze se k němu dostat z následujícího umístění:

https://DD_OR_DDMC_IP_ADDRESS/api/

Zobrazí se stránka s odkazy na několik důležitých zdrojů, jmenovitě:

• Dokumentace API: Podrobný seznam všech dostupných volání API podporovaných DD nebo DDMC
• Test klienta REST: Test volání API ze samotného webového rozhraní systému DD

Dokumentace k rozhraní API je vše, co musí programátor použít, aby mohl využívat rozhraní DD REST API k vytváření aplikací nad systémem DD. 

Aby bylo možné používat rozhraní API, je vyžadováno ověření DD. Jsou potřeba dvě informace:

• X-DD-AUTH-TOKEN: Soubor cookie, který systém DD poskytuje po úspěšném ověření a musí být použit jako ověřovatel pro jakékoli další požadavky.
• X-DD-UUID: Jedinečný identifikátor DD, který se má použít pro (většinu) požadavků na rozhraní API. Poznámka pro jednotlivé DD se to může zdát nadbytečné, ale je to zjevně nezbytné pro DDMC, kde lze zvolit individuální DD.

K ověření v systému DD použijte metodu "/rest/v1.0/auth". Pokud tak chcete učinit z libovolného hostitele s nainstalovaným příkazem "curl" a síťovým přístupem k systému DD, odešlete požadavek následujícím způsobem:

# curl --include --insecure -X 'POST' --header 'Content-Type: application/json' --header 'Accept: application/text' -d '{ "auth_info":{ "username":"sysadmin","password":"SomePass" } }' 'https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth'

Následuje několik poznámek k výše spuštěnému příkazovému řádku:

• Je potřeba možnost --include, protože některé odpovědi na dotazy se vracejí jako značky odpovědí HTTP, nikoli jako součást těla
• Možnost "--insecure" je nutná, pokud je curl nakonfigurován tak, aby kontroloval certifikát certifikační autority serveru podle seznamu známých a důvěryhodných autorit certifikační autority. Protože klient REST TEST dodávaný se systémem DD tuto možnost nepřidá, je však nutné ji použít k ověření certifikátů certifikační autority, jinak všechny příkazy spuštěné z testovacího klienta selžou (undefinedERROR Text Status: error). Pokud se místo toho pokusíte spustit příklad příkazu "curl" z příkazového řádku, dojde k chybě:

curl: (60) SSL certificate problem: self signed certificate in certificate chain
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

• Používáme metodu HTTP "POST". Každá metoda API má svou vlastní metodu, která je jasně zvýrazněna v dokumentaci.
• Volby "--header" se používají k předání hlaviček nebo parametrů na úrovni HTTP volanému systému DD
• "-d" odešle do systému DD text požadavku, v tomto případě uživatelské jméno a heslo
• Nakonec je identifikátor URI volající konkrétní metodu ověřování volán jako poslední parametr ( https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth ). Protože používáme protokol HTTPS, přihlašovací údaje se šíří šifrované po drátě. Všimněte si, že zatímco k dokumentaci a vloženému testovacímu klientovi se přistupuje přes port 443, vstupní bod služby REST API je na portu 3009 a musí používat HTTPS (ne HTTP), aby fungoval

Odpověď na výše uvedený ověřovací dotaz je uvedena níže:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 112
X-DD-AUTH-TOKEN: 434f1d6dc1528bb8d3ad66c70dc7f74f9
X-DD-UUID: 7850d7a24f93f502:1346d63c57821e38
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Server: Data Domain OS
Access-Control-Expose-Headers: AUTHORIZATION, X-DD-AUTH-TOKEN, X-DD-JSON-RESPONSE-WITH-ROOT, X-DD-PEER-USERNAME

{"service_status": {"details": "success", "code": 0, "link": [{"rel": "related", "href": "/rest/v1.0/system"}]}}

Vše před prázdným řádkem jsou hlavičky HTTP odeslané v odpovědi. Obsah po je tělo odpovědi, které v tomto případě informuje o úspěchu. Pro tuto metodu jsou nejdůležitější údaje:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Jedná se o dočasný ověřovací token, který lze po danou dobu použít k ověření dalších operací
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) požadované ID systému DD, které je nutné použít pro pozdější požadavky

Pro jakýkoli další požadavek musíme použít tyto hodnoty. Řekněme například, že chceme zjistit informace o systému souborů DD. Přejděte do "Dokumentace API" a vyhledejte volání, které nejlépe vyhovuje našim potřebám, jak je uvedeno na snímku obrazovky níže:




Po kontrole potřebných parametrů můžeme vytvořit požadavek, jak je uvedeno níže.  Všimněte si, že v tomto případě spustíme požadavek typu "GET" místo "POST", jako je metoda ověřování:

# curl --include --insecure -X 'GET' --header 'Content-Type: application/json' --header 'Accept: application/text' --header 'X-DD-AUTH-TOKEN:434f1d6dc1528bb8d3ad66c70dc7f74f9' 'https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/dd-systems/7850d7a24f93f502%3A1346d63c57821e38/file-systems'

Zobrazí se ale následující odpověď, která indikuje, že ověřovací token je neplatný nebo vypršela jeho platnost:

{"details": "**** Authentication token \"434f1d6dc1528bb8d3ad66c70dc7f74f9\" is invalid.", "code": 5427, "link": [{"rel": "self", "href": "/rest/v1.0/auth"}]}

Museli bychom vygenerovat nový ověřovací token, abychom mohli spustit dotaz a získat zamýšlené výsledky, například:

# curl --include --insecure -X GET --header 'Accept: application/json' --header 'X-DD-AUTH-TOKEN: 178a7b8f337ce3027acdcd889ed10446c' 'https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/dd-systems/7850d7a24f93f502%3A1346d63c57821e38/file-systems'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1123
X-DD-AUTH-TOKEN: 178a7b8f337ce3027acdcd889ed10446c
X-DD-UUID: 7850d7a24f93f502:1346d63c57821e38
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Server: Data Domain OS
Access-Control-Expose-Headers: AUTHORIZATION, X-DD-AUTH-TOKEN, X-DD-JSON-RESPONSE-WITH-ROOT, X-DD-PEER-USERNAME

{"hostname": "DD3300.example.com", "fs_status": "sn_enabled", "fs_clean_status": "inactive", "fs_cleaning_info": {"filesys_clean_info": {"cleaning_status": "inactive", "cleaning_dates": {"start_epoch": 1663879075, "end_epoch": 1663879131, "success_epoch": 1663679711}, "is_aborted": true, "abort_reason": "Cleaning was aborted by user.", "throttle": 50, "schedule": {"occurrence": "weekly", "days": ["Tue"], "time": "0600"}}, "cloud_clean_info": {"cleaning_status": "inactive", "cleaning_dates": {}, "is_aborted": false, "throttle": 50, "frequency": 0}}, "fs_uptime_secs": 344738, "fs_options": [{"key": "local-compression-type", "value": "gz"}, {"key": "marker-type", "value": "auto"}, {"key": "report-replica-as-writable", "value": "disabled"}, {"key": "staging-reserve", "value": "5% = 4271.2 GiB percent of total space"}, {"key": "warning-space-usage", "value": "90"}, {"key": "critical-space-usage", "value": "95"}], "link": [{"rel": "self", "href": "/rest/v1.0/dd-systems/7850d7a24f93f502%3A1346d63c57821e38/file-systems"}, {"rel": "parent", "href": "/rest/v1.0/dd-systems/7850d7a24f93f502%3A1346d63c57821e38"}]}

Výstup v textu odpovědi je odeslán volajícímu ve formátu JSON, což je standard.