Data Domain: Så här använder du det inbäddade REST API:et för DD och DDMC

Den senaste dokumentationen finns på https://developer.dell.com/apis/products/data-protection.

Både DD:er och DDMC:er kom som standard med ett webbaserat REST API aktiverat. Ett REST API är ett sätt att interagera programmatiskt med DD:er och DDMC:er. I den här artikeln används exempel för DD:er från och med nu med hjälp av ett enkelt klient- och serverprotokoll. HTTP-protokollet behåller inget tillstånd och gör det möjligt för en klient att läsa tillstånd från DD:erna och köra kommandon med särskilt utformade HTTP-anrop.

Från kommandoraden informerar följande kommando om status för den webbaserade REST API-tjänsten (webbtjänsten):

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

Observera att eftersom REST API hanteras från samma portar som användargränssnittet finns det inget sätt att inaktivera det separat. Detta utgör ingen säkerhetsrisk eftersom alla begäranden till API:et måste autentiseras, på samma sätt som begäranden till användargränssnittet eller CLI.

Det bästa sättet att komma igång med REST-API:et är att använda den paketerade klienten på varje DD och DDMC. Den kan nås på följande plats:

https://DD_OR_DDMC_IP_ADDRESS/api/

Detta presenterar en sida med länkar till flera viktiga resurser, nämligen:

• API-dokumentation: Detaljerad lista över alla tillgängliga API-anrop som stöds av DD eller DDMC
• REST-testklient: Testa API-anropen från själva DD-webbgränssnittet

API-dokumentationen är allt som en programmerare måste använda för att utnyttja DD REST API för att bygga program ovanpå DD. 

DD-autentisering krävs för att använda API:et. Två typer av information behövs:

• X-DD-AUTH-TOKEN: En cookie som DD tillhandahåller vid lyckad autentisering och som måste användas som autentiserare för eventuella ytterligare begäranden.
• X-DD-UUID: Den unika DD-identifieraren som ska användas för (de flesta) begäranden till API:et. Observera att för en enskild DD kan detta se överflödigt ut, men det är helt klart nödvändigt för DDMC, där en enskild DD kan väljas.

Om du vill autentisera mot DD använder du metoden "/rest/v1.0/auth". Om du vill göra det från valfri värd med "curl" installerat och nätverksåtkomst till DD och utfärda begäran på följande sätt:

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

Några kommentarer om kommandoradskörningen ovan följer:

• Alternativet "--include" behövs eftersom vissa av frågesvaren kommer tillbaka som HTTP-svarstaggar, inte som en del av brödtexten
• Flaggan "--insecure" behövs när curl är konfigurerat för att kontrollera serverns CA-certifikat mot en lista över kända och betrodda CA-auktoriteter. Eftersom REST TEST-klienten som medföljer DD inte lägger till det här alternativet, men det måste användas för att verifiera CA-certifikaten, annars misslyckas alla kommandon som körs inifrån testklienten (undefinedERROR Text Status: error). Om du försöker köra ett exempel på "curl" från kommandoraden i stället blir felet:

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 använder HTTP-metoden "POST". Varje API-metod har sin egen metod, vilket tydligt markeras i dokumentationen.
• "--header" flaggor används för att skicka HTTP-nivårubriker eller alternativ till anropad DD
• "-d" skickar brödtexten i begäran till DD, i det här fallet användarnamn och lösenord
• Slutligen anropas URI:n som anropar den specifika autentiseringsmetoden som den sista parametern (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Eftersom vi använder HTTPS färdas inloggningsuppgifterna krypterade via kabeln. Observera att dokumenten och den inbäddade testklienten nås via port 443, men startpunkten för REST API-tjänsten finns på port 3009 och måste använda HTTPS (inte HTTP) för att fungera

Svaret på autentiseringsfrågan ovan visas nedan:

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

Allt före den tomma raden är HTTP-huvuden som skickas i svaret. Innehållet efter är svarstexten, som i det här fallet informerar om framgång. För den här metoden är de viktigaste data:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) det här är en tillfällig autentiseringstoken som kan användas under en viss tid för att autentisera ytterligare åtgärder
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) ID:t för den DD som efterfrågas, som måste användas för senare begäranden

För ytterligare förfrågningar måste vi använda dessa värden. Anta till exempel att vi vill ta reda på information för ett DD-filsystem. Gå till "API-dokumentation" för att hitta det anrop som bäst passar våra behov, som i skärmdumpen nedan:




Efter att ha kontrollerat de nödvändiga parametrarna kan vi bygga begäran enligt nedan.  Observera att i det här fallet kör vi en "GET"-typ av begäran i stället för en "POST", till exempel autentiseringsmetoden:

# 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öljande svar, som anger att autentiseringstoken antingen är ogiltig eller har upphört att gälla:

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

Vi skulle behöva generera en ny autentiseringstoken för att köra frågan och få de avsedda resultaten, till exempel:

# 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 svarstexten skickas till anroparen i JSON-format, vilket är standarden.