Data Domain: jak korzystać z wbudowanego interfejsu API REST dla DD i DDMC

Najnowszą dokumentację można znaleźć na stronie https://developer.dell.com/apis/products/data-protection.

Zarówno DD, jak i DDMC są domyślnie dostarczane z włączonym internetowym interfejsem API REST. Interfejs API REST to sposób programowej interakcji z DD i DDMC. W tym artykule użyto przykładów dla DD od teraz przy użyciu prostego protokołu klienta i serwera. Protokół HTTP nie przechowuje stanu i umożliwia klientowi odczytywanie stanu z DD i uruchamianie poleceń ze specjalnie spreparowanymi wywołaniami HTTP.

W wierszu polecenia następujące polecenie informuje o stanie internetowej usługi interfejsu API REST (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
-----------   -------   ---------------------
...

Uwaga: ponieważ interfejs API REST jest obsługiwany z tych samych portów co interfejs użytkownika, nie ma możliwości wyłączenia go oddzielnie. Nie stwarza to zagrożenia dla bezpieczeństwa, ponieważ wszystkie żądania do interfejsu API muszą być uwierzytelniane, w taki sam sposób, jak żądania do interfejsu użytkownika lub interfejsu wiersza poleceń.

Najlepszym sposobem na rozpoczęcie pracy z interfejsem API REST jest użycie klienta w pakiecie na każdym DD i DDMC. Dostęp do niego można uzyskać w następującej lokalizacji:

https://DD_OR_DDMC_IP_ADDRESS/api/

Przedstawia ona stronę z linkami do kilku ważnych zasobów, a mianowicie:

• Dokumentacja API: Szczegółowa lista wszystkich dostępnych wywołań API obsługiwanych przez DD lub DDMC
• Klient testowy REST: testowanie wywołań interfejsu API z samego interfejsu internetowego DD

Dokumentacja interfejsu API to wszystko, czego programista musi użyć, aby wykorzystać interfejs DD REST API do tworzenia aplikacji na podstawie DD. 

Do korzystania z interfejsu API wymagane jest uwierzytelnienie DD. Potrzebne są dwie informacje:

• X-DD-AUTH-TOKEN: Plik cookie, który DD dostarcza po pomyślnym uwierzytelnieniu i musi być używany jako uwierzytelniacz dla wszelkich dalszych żądań.
• X-DD-UUID: unikatowy identyfikator DD, który ma być używany dla (większości) żądań do interfejsu API. Uwaga w przypadku pojedynczego DD może to wydawać się zbędne, ale jest to wyraźnie konieczne w przypadku DDMC, gdzie można wybrać indywidualny DD.

Aby uwierzytelnić się w DD, użyj metody "/rest/v1.0/auth". Aby to zrobić z dowolnego hosta z zainstalowanym "curl" i dostępem do sieci do DD, i wyślij żądanie w następujący sposób:

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

Oto kilka komentarzy na temat wiersza poleceń uruchomionego powyżej:

• Opcja "--include" jest potrzebna, ponieważ niektóre odpowiedzi na zapytanie wracają jako tagi odpowiedzi HTTP, a nie jako część treści
• Opcja "--insecure" jest wymagana, gdy curl jest skonfigurowany do sprawdzania certyfikatu urzędu certyfikacji serwera z listą znanych i zaufanych urzędów certyfikacji. Ponieważ klient REST TEST w pakiecie z DD nie dodaje tej opcji, ale musi być używany do weryfikacji certyfikatów CA, w przeciwnym razie wszystkie polecenia uruchamiane z poziomu klienta testowego kończą się niepowodzeniem (undefinedERROR Text Status: error). Jeśli zamiast tego spróbujesz uruchomić przykładowy "curl" z wiersza poleceń, błąd będzie następujący:

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.

• Używamy metody HTTP "POST". Każda metoda API ma swoją własną metodę, która jest wyraźnie zaznaczona w dokumentacji.
• Opcje "--header" służą do przekazywania nagłówków lub opcji na poziomie HTTP do wywoływanego DD
• "-d" wysyła treść żądania do DD, w tym przypadku nazwę użytkownika i hasło
• Na koniec identyfikator URI wywołujący określoną metodę uwierzytelniania jest wywoływany jako ostatni parametr (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Ponieważ korzystamy z protokołu HTTPS, poświadczenia są szyfrowane przez sieć. Należy pamiętać, że chociaż dostęp do dokumentacji i wbudowanego klienta testowego jest uzyskiwany za pośrednictwem portu 443, punkt wejścia usługi interfejsu API REST znajduje się na porcie 3009 i do działania musi używać protokołu HTTPS (nie HTTP)

Odpowiedź na powyższe zapytanie uwierzytelniające jest pokazana poniżej:

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

Wszystko przed pustym wierszem to nagłówki HTTP wysłane w odpowiedzi. Zawartość po to treść odpowiedzi, która w tym przypadku informuje o powodzeniu. W przypadku tej metody najważniejszymi danymi są:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Jest to tymczasowy token uwierzytelniający, który może być używany przez określony czas do uwierzytelniania dalszych operacji
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) identyfikator DD, o który należy wnioskować, którego należy użyć w późniejszych żądaniach

W przypadku każdego dalszego żądania musimy użyć tych wartości. Załóżmy na przykład, że chcemy znaleźć informacje na temat systemu plików DD. Przejdź do "Dokumentacji API", aby zlokalizować wywołanie, które najlepiej odpowiada naszym potrzebom, jak na poniższym zrzucie ekranu:




Po sprawdzeniu niezbędnych parametrów możemy zbudować żądanie jak poniżej.  Uwaga: w tym przypadku uruchamiamy żądanie typu "GET" zamiast żądania "POST", takiego jak metoda uwierzytelniania:

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

Otrzymujemy jednak następującą odpowiedź wskazującą, że token uwierzytelniania jest nieprawidłowy lub wygasł:

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

Musielibyśmy wygenerować nowy token uwierzytelniania, aby uruchomić zapytanie i uzyskać zamierzone wyniki, na przykład:

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

Dane wyjściowe w treści odpowiedzi są wysyłane do obiektu wywołującego w formacie JSON, który jest standardem.