Data Domain: Slik bruker du innebygd REST API for DD og DDMC

Den nyeste dokumentasjonen finner du på https://developer.dell.com/apis/products/data-protection.

Både DD-er og DDMC-er kom som standard med en nettbasert REST-API aktivert. En REST API er en måte å samhandle programmatisk med DD-er og DDMC-er. Denne artikkelen bruker eksempler på DD-er fra nå av ved hjelp av en enkel klient- og serverprotokoll. HTTP-protokollen beholder ingen tilstand, og lar en klient lese tilstand fra DD-ene og kjøre kommandoer med spesiallagde HTTP-kall.

Fra kommandolinjen informerer følgende kommando om statusen for den webbaserte REST API-tjenesten (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
-----------   -------   ---------------------
...

Siden REST-API-en betjenes fra de samme portene som brukergrensesnittet, er det ikke mulig å deaktivere den separat. Dette utgjør ingen sikkerhetsrisiko da alle forespørsler til API-et må autentiseres, på samme måte som forespørsler til brukergrensesnittet eller CLI

.Den beste måten å komme i gang med REST API på, er å bruke den medfølgende klienten på hver DD og DDMC. Den kan nås på følgende sted:

https://DD_OR_DDMC_IP_ADDRESS/api/

Dette presenterer en side med lenker til flere viktige ressurser, nemlig:

• API-dokumentasjon: Detaljert liste over alle tilgjengelige API-kall som støttes av DD eller DDMC
• REST-testklient: Test API-kallene fra selve DD-webgrensesnittet

API-dokumentasjonen er alt en programmerer må bruke for å utnytte DD REST API til å bygge programmer på toppen av DD. 

DD-godkjenning kreves for å bruke API-en. To opplysninger er nødvendig:

• X-DD-AUTH-TOKEN: En informasjonskapsel som DD gir ved vellykket autentisering og må brukes som autentisator for ytterligere forespørsler.
• X-DD-UUID: Den unike DD-identifikatoren som skal brukes for (de fleste) forespørsler til API-en. Merk for en enkelt DD kan dette se overflødig ut, men det er helt klart nødvendig for DDMC-er, der en individuell DD kan velges.

Hvis du vil godkjenne mot DD, bruker du metoden "/rest/v1.0/auth". For å gjøre dette fra en vert med "curl" installert og nettverkstilgang til DD, og utstede forespørselen 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'

Noen kommentarer om kommandolinjen kjørt ovenfor følger:

• Alternativ "--include" er nødvendig, siden noen av spørringssvarene kommer tilbake som HTTP-svarkoder, ikke som en del av brødteksten
• Alternativ "--insecure" er nødvendig når curl er konfigurert til å kontrollere serverens CA-sertifikat mot en liste over kjente og pålitelige CA-instanser. Siden REST TEST-klienten som følger med DD, ikke legger til dette alternativet, men det må brukes til å bekrefte CA-sertifikatene, ellers kjøres alle kommandoene fra testklienten mislykkes (undefinedERROR Text Status: error). Hvis du prøver å kjøre et eksempel "curl" fra kommandolinjen i stedet, vil feilen 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 bruker HTTP-metoden "POST". Hver API-metode har sin egen metode, som er tydelig fremhevet i dokumentasjonen.
• "--header"-alternativene brukes til å sende HTTP-nivåoverskrifter eller -alternativer til den kalt DD
• "-d" sender hoveddelen av forespørselen til DD, i dette tilfellet brukernavnet og passordet
• Til slutt kalles URI-en som kaller den spesifikke godkjenningsmetoden, som den siste parameteren (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Når vi bruker HTTPS, reiser legitimasjon kryptert over ledningen. Mens dokumentene og den innebygde testklienten åpnes via port 443, er inngangspunktet for REST API-tjenesten på port 3009 og må bruke HTTPS (ikke HTTP) for å fungere

Svaret på autentiseringsspørringen ovenfor vises 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 linjen er HTTP-overskrifter sendt i svaret. Innhold etter er responsorganet, som i dette tilfellet informerer om suksess. For denne metoden er de viktigste dataene:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Dette er et midlertidig godkjenningstoken som kan brukes i en gitt tidsperiode til å godkjenne videre operasjoner
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) ID-en for DD det blir bedt om, som må brukes for senere forespørsler

For ytterligere forespørsler må vi bruke disse verdiene. La oss for eksempel si at vi ønsker å finne ut informasjon for et DD-filsystem. Gå til "API-dokumentasjon" for å finne samtalen som passer best for våre behov, som i skjermbildet nedenfor:




Etter å ha sjekket de nødvendige parametrene, kan vi bygge forespørselen som nedenfor.  Merk at i dette tilfellet kjører vi en forespørselstype "GET" i stedet for en "POST", for eksempel godkjenningsmetoden:

# 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, som indikerer enten autentiseringstokenet er ugyldig eller har utløpt:

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

Vi må generere et nytt godkjenningstoken for å kjøre spørringen og få de tiltenkte resultatene, 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"}]}

Utdata i svarlegemet sendes til innringeren i JSON-format, som er standarden.