Data Domain: come utilizzare l'API REST integrata per DD e DDMC

La documentazione più recente è disponibile all'indirizzo https://developer.dell.com/apis/products/data-protection.

Sia DD che DDMC sono forniti per impostazione predefinita con un'API REST web-based abilitata. Un'API REST è un mezzo per interagire a livello di codice con DD e DDMC. Questo articolo utilizza esempi per i DD d'ora in poi utilizzando un semplice protocollo client e server. Il protocollo HTTP non mantiene alcuno stato e consente a un client di leggere lo stato dai DD ed eseguire comandi con chiamate HTTP appositamente predisposte.

Dalla riga di comando, il comando seguente informa dello stato del servizio API REST web-based (web-service):

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

Poiché l'API REST viene riparata dalle stesse porte dell'interfaccia utente, non è possibile disabilitarla separatamente. Ciò non comporta alcun rischio per la sicurezza in quanto tutte le richieste all'API devono essere autenticate, allo stesso modo delle richieste all'interfaccia utente o alla CLI.

Il modo migliore per iniziare a utilizzare l'API REST è utilizzare il client in bundle su ogni DD e DDMC. È possibile accedervi dalla seguente posizione:

https://DD_OR_DDMC_IP_ADDRESS/api/

Questo presenta una pagina con collegamenti a diverse risorse importanti, vale a dire:

• Documentazione API: elenco dettagliato di tutte le chiamate API disponibili supportate da DD o DDMC
• Client di test REST: consente di testare le chiamate API dall'interfaccia web di DD

La documentazione API è tutto ciò che un programmatore deve utilizzare per utilizzare l'API REST di DD e creare applicazioni su DD. 

Per utilizzare l'API è necessaria l'autenticazione DD. Sono necessarie due informazioni:

• X-DD-AUTH-TOKEN: cookie che DD fornisce dopo l'autenticazione riuscita e deve essere utilizzato come autenticatore per eventuali ulteriori richieste.
• X-DD-UUID: l'identificatore DD univoco da utilizzare per la (maggior parte) delle richieste all'API. Nota: per un singolo DD ciò può sembrare superfluo, ma è chiaramente necessario per i DDMC, dove è possibile scegliere un singolo DD.

Per eseguire l'autenticazione con DD, utilizzare il metodo "/rest/v1.0/auth". A tale scopo, da qualsiasi host con "curl" installato e accesso di rete a DD, inviare la richiesta come segue:

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

Di seguito sono riportati alcuni commenti sulla riga di comando eseguita sopra:

• L'opzione "--include" è necessaria, in quanto alcune delle risposte alle query vengono restituite come tag di risposta HTTP, non come parte del corpo
• L'opzione "--insecure" è necessaria quando curl è configurato per controllare il certificato CA del server rispetto a un elenco di autorità CA note e attendibili. Poiché il client REST TEST in dotazione con DD non aggiunge questa opzione, questa deve essere utilizzata per verificare i certificati CA oppure tutti i comandi eseguiti dall'interno del client di test hanno esito negativo (undefinedERROR Text Status: error). Se si tenta invece di eseguire un esempio di "curl" dalla riga di comando, l'errore sarebbe:

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.

• Utilizziamo un metodo HTTP "POST". Ogni metodo API ha il proprio metodo, chiaramente evidenziato nella documentazione.
• Le opzioni "--header" vengono utilizzate per passare le intestazioni o le opzioni di livello HTTP al DD chiamato
• "-d" invia il corpo della richiesta al DD, in questo caso il nome utente e la password
• Infine, l'URI che chiama il metodo di autenticazione specifico viene chiamato come ultimo parametro (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Poiché utilizziamo HTTPS, le credenziali viaggiano crittografate via cavo. Nota: mentre i documenti e il client di test integrato sono accessibili tramite la porta 443, il punto di ingresso del servizio API REST si trova sulla porta 3009 e deve utilizzare HTTPS (non HTTP) per funzionare

La risposta alla query di autenticazione precedente è mostrata di seguito:

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

Tutto ciò che precede la riga vuota sono intestazioni HTTP inviate nella risposta. Il contenuto dopo è il corpo della risposta, che in questo caso informa dell'esito positivo. Per questo metodo, i dati più importanti sono:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Si tratta di un token di autenticazione temporaneo, che può essere utilizzato per un determinato periodo di tempo per autenticare ulteriori operazioni
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) l'ID del DD richiesto, che deve essere utilizzato per le richieste successive

Per qualsiasi ulteriore richiesta, dobbiamo utilizzare tali valori. Supponiamo, ad esempio, di voler recuperare informazioni per un file system DD. Vai alla "Documentazione API" per individuare la chiamata più adatta alle nostre esigenze, come nello screenshot qui sotto:




Dopo aver controllato i parametri necessari, possiamo costruire la richiesta come di seguito.  Si noti che in questo caso eseguiamo una richiesta di tipo "GET", anziché una "POST", come il metodo di autenticazione:

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

Viene tuttavia visualizzata la seguente risposta, indicante che il token di autenticazione non è valido o è scaduto:

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

È necessario generare un nuovo token di autenticazione per eseguire la query e ottenere i risultati desiderati, ad esempio:

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

L'output nel corpo della risposta viene inviato al chiamante in formato JSON, che è lo standard.