Data Domain: De geïntegreerde REST API gebruiken voor DD en DDMC

De meest recente documentatie vindt u op https://developer.dell.com/apis/products/data-protection.

Zowel DD's als DDMC's werden standaard geleverd met een webgebaseerde REST API ingeschakeld. Een REST API is een manier om programmatisch te communiceren met DD's en DDMC's. In dit artikel worden voorbeelden gebruikt voor DD's die vanaf nu een eenvoudig client- en serverprotocol gebruiken. Het HTTP-protocol behoudt geen status en stelt een client in staat de status van de DD's te lezen en opdrachten uit te voeren met speciaal vervaardigde HTTP-aanroepen.

Vanaf de opdrachtregel informeert de volgende opdracht over de status voor de webgebaseerde REST API-service (webservice):

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

Aangezien de REST API wordt onderhouden vanaf dezelfde poorten als de UI, is er geen manier om deze afzonderlijk uit te schakelen. Dit vormt geen beveiligingsrisico omdat alle verzoeken aan de API moeten worden geverifieerd, op dezelfde manier als verzoeken aan de gebruikersinterface of CLI.

De beste manier om met de REST API aan de slag te gaan, is door de gebundelde client op elke DD en DDMC te gebruiken. Het is toegankelijk op de volgende locatie:

https://DD_OR_DDMC_IP_ADDRESS/api/

Dit presenteert een pagina met links naar een aantal belangrijke bronnen, namelijk:

• API-documentatie: Gedetailleerde lijst met alle beschikbare API-aanroepen die worden ondersteund door de DD of DDMC
• REST Test Client: test de API-aanroepen van de DD-webinterface zelf

De API-documentatie is alles wat een programmeur moet gebruiken om de DD REST API te gebruiken om bovenop het DD applicaties te bouwen. 

DD-authenticatie is vereist om de API te gebruiken. Er zijn twee stukjes informatie nodig:

• X-DD-AUTH-TOKEN: Een cookie die door de DD wordt verstrekt na een succesvolle authenticatie en die moet worden gebruikt als authenticatie voor eventuele verdere verzoeken.
• X-DD-UUID: De unieke DD-identifier die moet worden gebruikt voor (de meeste) verzoeken aan de API. Let op: voor een individueel DD lijkt dit misschien overbodig, maar het is duidelijk noodzakelijk voor DDMC's, waar een individueel DD gekozen kan worden.

Voor authenticatie tegen het DD gebruikt u de methode /rest/v1.0/auth. Om dit te doen vanaf elke host waarop "curl" is geïnstalleerd en netwerktoegang tot het DD, en het verzoek als volgt uit te voeren:

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

Hieronder volgen enkele opmerkingen over de bovenstaande opdrachtregel:

• Optie "--include" is nodig, omdat sommige van de query-antwoorden terugkomen als HTTP-antwoordtags, niet als onderdeel van de hoofdtekst
• De optie "--insecure" is nodig wanneer curl is geconfigureerd om het CA-certificaat van de server te controleren aan de hand van een lijst met bekende en vertrouwde CA-autoriteiten. Aangezien de REST TEST-client die is gebundeld met de DD deze optie niet toevoegt, maar deze moet worden gebruikt om de CA-certificaten te verifiëren, anders mislukken alle opdrachten die vanuit de testclient worden uitgevoerd (undefinedERROR Text Status: error). Als u in plaats daarvan een voorbeeld "curl" probeert uit te voeren vanaf de opdrachtregel, zou de fout zijn:

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.

• We gebruiken de HTTP-methode 'POST'. Elke API-methode heeft zijn eigen methode, die duidelijk wordt benadrukt in de documentatie.
• "--header"-opties worden gebruikt om headers of opties op HTTP-niveau door te geven aan de aangeroepen DD
• "-d" stuurt de hoofdtekst van het verzoek naar de DD, in dit geval de gebruikersnaam en het wachtwoord
• Ten slotte wordt de URI die de specifieke verificatiemethode aanroept, aangeroepen als de laatste parameter (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Omdat we HTTPS gebruiken, worden inloggegevens versleuteld via de kabel verzonden. Opmerking: terwijl de documenten en de ingesloten testclient worden geopend via poort 443, bevindt het REST API-servicepunt zich op poort 3009 en moet HTTPS (niet HTTP) worden gebruikt om te werken

Het antwoord op de bovenstaande verificatievraag wordt hieronder weergegeven:

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

Alles voor de lege regel zijn HTTP-headers die in het antwoord worden verzonden. Inhoud na is de antwoordtekst, die in dit geval informeert over succes. Voor deze methode zijn de belangrijkste gegevens:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Dit is een tijdelijk authenticatietoken, dat gedurende een bepaalde tijd kan worden gebruikt om verdere bewerkingen te verifiëren
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) de ID voor het DD dat wordt gevraagd, dat moet worden gebruikt voor latere aanvragen

Voor elk verder verzoek moeten we die waarden gebruiken. Laten we bijvoorbeeld zeggen dat we informatie willen weten voor een DD-bestandssysteem. Ga naar de "API-documentatie" om de oproep te vinden die het beste bij onze behoeften past, zoals in de onderstaande schermafbeelding:




Na het controleren van de benodigde parameters, kunnen we de aanvraag bouwen zoals hieronder.  Merk op dat we in dit geval een aanvraag van het type "GET" uitvoeren in plaats van een "POST", zoals de verificatiemethode:

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

Maar we krijgen het volgende antwoord, dat aangeeft dat het authenticatietoken ongeldig is of is verlopen:

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

We zouden een nieuw authenticatietoken moeten genereren om de query uit te voeren en de beoogde resultaten te krijgen, bijvoorbeeld:

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

Uitvoer in de hoofdtekst van het antwoord wordt naar de beller verzonden in JSON-indeling, wat de standaard is.