Data Domain: DD:n ja DDMC:n sulautetun REST-ohjelmointirajapinnan käyttäminen

Uusin dokumentaatio löytyy osoitteesta https://developer.dell.com/apis/products/data-protection.

Sekä DD:ssä että DDMC:ssä oli oletusarvoisesti käytössä verkkopohjainen REST-ohjelmointirajapinta. REST-ohjelmointirajapinta on keino olla ohjelmallisesti vuorovaikutuksessa DD:iden ja DDMC:iden kanssa. Tässä artikkelissa käytetään tästä lähtien esimerkkejä DD: stä yksinkertaisen asiakas- ja palvelinprotokollan avulla. HTTP-protokolla ei säilytä tilaa ja sallii asiakkaan lukea tilaa DD:istä ja suorittaa komentoja tietyllä tavalla muodostetuilla HTTP-kutsuilla.

Seuraava komento ilmoittaa komentorivillä verkkopohjaisen REST API -palvelun (verkkopalvelun) tilan:

# 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
-----------   -------   ---------------------
...

Huomaa, että koska REST-ohjelmointirajapintaa huolletaan samoista porteista kuin käyttöliittymää, sitä ei voi poistaa käytöstä erikseen. Tämä ei aiheuta tietoturvariskiä, koska kaikki ohjelmointirajapinnan pyynnöt on todennettava samalla tavalla kuin käyttöliittymään tai komentoriviliittymään liittyvät pyynnöt.

Paras tapa aloittaa REST-ohjelmointirajapinnan käyttö on käyttää mukana toimitettua asiakasohjelmaa jokaisessa DD:ssä ja DDMC:ssä. Sitä voi käyttää seuraavassa paikassa:

https://DD_OR_DDMC_IP_ADDRESS/api/

Tämä esittelee sivun, jossa on linkkejä useisiin tärkeisiin resursseihin, nimittäin:

• API-dokumentaatio: Yksityiskohtainen luettelo kaikista käytettävissä olevista DD:n tai DDMC:n tukemista API-kutsuista
• REST Test Client: Testaa ohjelmointirajapintakutsut DD-verkkokäyttöliittymästä

API-dokumentaatio on kaikki, mitä ohjelmoijan on käytettävä hyödyntääkseen DD REST APIA sovellusten luomiseen DD: n päälle. 

API:n käyttö edellyttää DD-todennusta. Tarvitaan kahta tietoa:

• X-DD-AUTH-TOKEN: Eväste, jonka DD antaa onnistuneen todennuksen jälkeen ja jota on käytettävä todentajana kaikissa tulevissa pyynnöissä.
• X-DD-UUID: Yksilöllinen DD-tunniste, jota käytetään (useimmissa) API-pyynnöissä. Huomaa, että yksittäisen DD:n kohdalla tämä saattaa näyttää tarpeettomalta, mutta se on selvästi tarpeen DDMC:ille, joissa voidaan valita yksittäinen DD.

DD-todennus tehdään komennolla /rest/v1.0/auth. Voit tehdä tämän mistä tahansa isännästä, johon on asennettu curl-toiminto, ja käyttää DD:tä verkossa, ja esittää pyynnön seuraavasti:

# 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'

Seuraavassa on muutamia kommentteja yllä olevasta komentorivistä:

• Vaihtoehto "--include" tarvitaan, koska osa kyselyvastauksista tulee takaisin HTTP-vastaustunnisteina, ei osana tekstiosaa
• Vaihtoehtoa --insecure tarvitaan, kun curl on määritetty vertaamaan palvelimen CA-varmennetta tunnettujen ja luotettujen CA-myöntäjien luetteloon. Koska DD:n mukana toimitettu REST TEST -asiakas ei lisää tätä asetusta, mutta sitä on käytettävä CA-varmenteiden tarkistamiseen, tai muuten kaikki testiasiakkaasta suoritettavat komennot epäonnistuvat (undefinedERROR Text Status: error). Jos yrität suorittaa esimerkin "curl" komentoriviltä, virhe olisi:

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.

• Käytämme HTTP-menetelmää POST. Jokaisella API-menetelmällä on oma menetelmänsä, joka on selvästi korostettu dokumentaatiossa.
• "--header"-asetuksilla välitetään HTTP-tason otsikot tai asetukset kutsutulle DD:lle
• "-d" lähettää pyynnön rungon DD: lle, tässä tapauksessa käyttäjätunnuksen ja salasanan
• Lopuksi tiettyä todennusmenetelmää kutsuvaa URI: tä kutsutaan viimeiseksi parametriksi (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Koska käytämme HTTPS: ää, tunnistetiedot kulkevat salattuina langan yli. Huomautus Asiakirjoja ja upotettua testiasiakasohjelmaa käytetään portin 443 kautta, kun taas REST-ohjelmointirajapintapalvelun aloituskohta on portissa 3009, ja sen on toimittava HTTPS:n (ei HTTP) avulla

Vastaus yllä olevaan todennuskyselyyn näkyy alla:

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"}]}}

Kaikki ennen tyhjää riviä on vastauksessa lähetettyjä HTTP-otsikoita. Sisältö jälkeen on vastausrunko, joka tässä tapauksessa ilmoittaa menestyksestä. Tämän menetelmän tärkeimmät tiedot ovat:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Tämä on väliaikainen todennustunnus, jota voidaan käyttää tietyn ajan myöhempien toimintojen todentamiseen
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) Pyydetyn DD:n tunnus, jota on käytettävä myöhemmissä pyynnöissä

Kaikissa lisäpyynnöissä meidän on käytettävä näitä arvoja. Oletetaan esimerkiksi, että haluamme selvittää DD-tiedostojärjestelmän tiedot. Siirry kohtaan "API-dokumentaatio" löytääksesi puhelun, joka parhaiten sopii tarpeisiimme, kuten alla olevassa kuvakaappauksessa:




Kun olet tarkistanut tarvittavat parametrit, voimme rakentaa pyynnön alla olevalla tavalla.  Huomaa, että tässä tapauksessa suoritamme GET-tyyppisen pyynnön POST-testin sijaan, kuten todennusmenetelmä:

# 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'

Mutta saamme seuraavan vastauksen, joka osoittaa, että joko todennustunnus on virheellinen tai vanhentunut:

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

Meidän on luotava uusi todennustunnus kyselyn suorittamiseksi ja haluttujen tulosten saamiseksi, esimerkiksi:

# 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"}]}

Vastausrungon tuloste lähetetään soittajalle JSON-muodossa, joka on vakio.