Data Domain: Sådan bruger du den integrerede REST API til DD og DDMC

Den seneste dokumentation kan findes på https://developer.dell.com/apis/products/data-protection.

Både DD er og DDMC er blev som standard leveret med en webbaseret REST API aktiveret. En REST API er en metode til at interagere programmeringsmæssigt med DD er og DDMC er. I denne artikel bruges eksempler på DD er fra nu af ved hjælp af en simpel klient- og serverprotokol. HTTP-protokollen bevarer ingen tilstand og gør det muligt for en klient at læse tilstand fra DD erne og køre kommandoer med særligt udformede HTTP-opkald.

Fra kommandolinjen informerer følgende kommando om status for den webbaserede REST API-tjeneste (webtjeneste):

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

Bemærk, at da REST API serviceres fra de samme porte som brugergrænsefladen, er det ikke muligt at deaktivere den separat. Dette udgør ingen sikkerhedsrisiko, da alle anmodninger til API'en skal godkendes på samme måde som anmodninger til brugergrænsefladen eller CLI.

Den bedste måde at komme i gang med REST API på er at bruge den medfølgende klient på hver DD og DDMC. Den kan tilgås på følgende sted:

https://DD_OR_DDMC_IP_ADDRESS/api/

Dette præsenterer en side med links til flere vigtige ressourcer, nemlig:

• API-dokumentation: Detaljeret liste over alle tilgængelige API-kald, der understøttes af DD eller DDMC
• REST-testklient: Test API-kaldene fra selve DD-webgrænsefladen

API-dokumentationen er alt, hvad en programmør skal bruge til at udnytte DD REST API til at bygge applikationer oven på DD. 

DD-godkendelse er påkrævet for at bruge API'en. Der er behov for to oplysninger:

• X-DD-AUTH-TOKEN: En cookie, som DD leverer efter vellykket godkendelse og skal bruges som autentifikator til eventuelle yderligere anmodninger.
• X-DD-UUID: Det unikke DD-id, der skal bruges til (de fleste) anmodninger til API'en. Bemærk for en individuel DD kan dette se overflødigt ud, men det er klart nødvendigt for DDMC'er, hvor en individuel DD kan vælges.

Hvis du vil godkende i forhold til DD, skal du bruge metoden "/rest/v1.0/auth". For at gøre dette fra enhver vært med "curl" installeret og netværksadgang til DD, og udstede anmodningen som følger:

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

Et par kommentarer om kommandolinjekørslen ovenfor følger:

• Indstillingen "--include" er nødvendig, da nogle af forespørgselssvarene kommer tilbage som HTTP-svarkoder, ikke som en del af brødteksten
• Indstillingen "--insecure" er nødvendig, når curl er konfigureret til at kontrollere serverens CA-certifikat mod en liste over kendte og betroede CA-myndigheder. Da REST TEST-klienten, der følger med DD, ikke tilføjer denne indstilling, men den skal bruges til at kontrollere CA-certifikaterne, ellers mislykkes alle kommandoer, der køres inde fra testklienten (undefinedERROR Text Status: error). Hvis du forsøger at køre et eksempel "curl" fra kommandolinjen i stedet, ville fejlen være:

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.

• Vi bruger en HTTP-metode "POST". Hver API-metode har sin egen metode, som tydeligt fremhæves i dokumentationen.
• "--header"-indstillinger bruges til at overføre HTTP-niveauoverskrifter eller indstillinger til den kaldte DD
• "-d" sender anmodningens krop til DD, i dette tilfælde brugernavnet og adgangskoden
• Endelig kaldes URI'en, der kalder den specifikke godkendelsesmetode, som den sidste parameter (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Da vi bruger HTTPS, rejser legitimationsoplysninger krypteret over ledningen. Bemærk, at mens dokumenterne og den integrerede testklient åbnes via port 443, er REST API-tjenesteindgangspunktet i port 3009 og skal bruge HTTPS (ikke HTTP) for at fungere

Svaret på godkendelsesforespørgslen ovenfor er vist nedenfor:

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

Alt før den tomme linje er HTTP-overskrifter, der sendes i svaret. Indhold efter er responsorganet, som i dette tilfælde informerer om succes. For denne metode er de vigtigste data:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Dette er et midlertidigt godkendelsestoken, som kan bruges i et bestemt tidsrum til at godkende yderligere handlinger
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) det id for DD, der bliver bedt om, som skal bruges til senere anmodninger

For enhver yderligere anmodning skal vi bruge disse værdier. Lad os f.eks. sige, at vi ønsker at finde oplysninger om et DD-filsystem. Gå til "API-dokumentation" for at finde det opkald, der bedst passer til vores behov, som i skærmbilledet nedenfor:




Efter at have kontrolleret de nødvendige parametre, kan vi opbygge anmodningen som nedenfor.  Bemærk, at vi i dette tilfælde kører en "GET"-anmodning i stedet for en "POST", f.eks. godkendelsesmetoden:

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

Men vi får følgende svar, der angiver, at godkendelsestokenet enten er ugyldigt eller er udløbet:

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

Vi bliver nødt til at generere et nyt godkendelsestoken for at køre forespørgslen og få de tilsigtede resultater, for eksempel:

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

Output i svarteksten sendes til den, der ringer op, i JSON-format, som er standarden.