Data Domain: Verwendung der integrierten REST API für DD und DDMC

Die aktuelle Dokumentation finden Sie unter https://developer.dell.com/apis/products/data-protection.

Sowohl DDs als auch DDMCs waren standardmäßig mit aktivierter webbasierter REST API ausgestattet. Eine REST API ist ein Mittel zur programmgesteuerten Interaktion mit DDs und DDMCs. Dieser Artikel enthält Beispiele für DDs, die von nun an ein einfaches Client- und Serverprotokoll verwenden. Das HTTP-Protokoll behält keinen Status bei und ermöglicht es einem Client, den Status von den DDs zu lesen und Befehle mit speziell gestalteten HTTP-Aufrufen auszuführen.

Über die Befehlszeile informiert der folgende Befehl über den Status für den webbasierten REST API-Service (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
-----------   -------   ---------------------
...

Hinweis: Da die REST API von denselben Ports wie die Benutzeroberfläche gewartet wird, gibt es keine Möglichkeit, sie separat zu deaktivieren. Dies stellt kein Sicherheitsrisiko dar, da alle Anforderungen an die API auf die gleiche Weise authentifiziert werden müssen wie Anforderungen an die Benutzeroberfläche oder CLI.

Die beste Methode für die ersten Schritte mit der REST API ist die Verwendung des gebündelten Clients auf jeder DD und jedem DDMC. Sie kann von folgendem Speicherort aufgerufen werden:

https://DD_OR_DDMC_IP_ADDRESS/api/

Dadurch wird eine Seite mit Links zu mehreren wichtigen Ressourcen angezeigt, nämlich:

• API-Dokumentation: Detaillierte Liste aller verfügbaren API-Aufrufe, die von DD oder DDMC unterstützt werden
• REST Test Client: Testen Sie die API-Aufrufe über die DD-Webschnittstelle selbst.

Die API-Dokumentation ist alles, was ein Programmierer verwenden muss, um die DD REST API zu nutzen und Anwendungen auf der DD zu erstellen. 

DD-Authentifizierung ist erforderlich, um die API zu verwenden. Es werden zwei Informationen benötigt:

• X-DD-AUTH-TOKEN: Ein Cookie, das das DD nach erfolgreicher Authentifizierung bereitstellt und das als Authentifikator für alle weiteren Anfragen verwendet werden muss.
• X-DD-UUID: Die eindeutige DD-Kennung, die für (die meisten) Anforderungen an die API verwendet werden soll. Hinweis: Für eine einzelne DD mag dies überflüssig erscheinen, ist aber eindeutig für DDMCs erforderlich, für die eine individuelle DD ausgewählt werden kann.

Um sich bei DD zu authentifizieren, verwenden Sie die Methode "/rest/v1.0/auth". Um dies von einem beliebigen Host mit installiertem "curl" und Netzwerkzugriff auf die DD zu tun, geben Sie die Anforderung wie folgt aus:

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

Es folgen einige Kommentare zur oben ausgeführten Befehlszeile:

• Die Option "--include" ist erforderlich, da einige der Abfrageantworten als HTTP-Antwort-Tags und nicht als Teil des Textkörpers zurückgegeben werden
• Die Option "--insecure" ist erforderlich, wenn curl konfiguriert ist, um das Server-CA-Zertifikat anhand einer Liste bekannter und vertrauenswürdiger CA-Zertifizierungsstellen zu prüfen. Da der mit DD gebündelte REST TEST-Client diese Option nicht hinzufügt, sondern zur Überprüfung der CA-Zertifikate verwendet werden muss, schlagen alle Befehle fehl, die vom Testclient aus ausgeführt werden (undefinedERROR Text Status: error). Wenn Sie stattdessen versuchen, ein Beispiel für "curl" über die Befehlszeile auszuführen, tritt der Fehler wie folgt auf:

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.

• Wir verwenden die HTTP-Methode "POST". Jede API-Methode verfügt über eine eigene Methode, die in der Dokumentation deutlich hervorgehoben wird.
• Die Optionen "--header" werden verwendet, um Header oder Optionen auf HTTP-Ebene an die aufgerufene DD zu übergeben.
• "-d" sendet den Text der Anforderung an das DD, in diesem Fall den Nutzernamen und das Kennwort
• Schließlich wird der URI, der die spezifische Authentifizierungsmethode aufruft, als letzter Parameter aufgerufen (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Da wir HTTPS verwenden, werden Anmeldedaten verschlüsselt über die Verbindung übertragen. Hinweis: Während auf die Dokumente und den integrierten Testclient über Port 443 zugegriffen wird, befindet sich der REST API-Serviceeinstiegspunkt an Port 3009 und muss HTTPS (nicht HTTP) verwenden, um zu funktionieren

Die Antwort auf die obige Authentifizierungsabfrage ist unten aufgeführt:

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 vor der leeren Zeile sind HTTP-Header, die in der Antwort gesendet werden. Inhalt nach ist der Antworttext, der in diesem Fall über den Erfolg informiert. Für diese Methode sind die wichtigsten Daten:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Dies ist ein temporäres Authentifizierungstoken, das für einen bestimmten Zeitraum zur Authentifizierung weiterer Vorgänge verwendet werden kann
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) Die ID für das DD, nach der gefragt wird, die für spätere Anfragen verwendet werden muss

Für jede weitere Anfrage müssen wir diese Werte verwenden. Nehmen wir beispielsweise an, wir möchten Informationen für ein DD-Dateisystem herausfinden. Gehen Sie zur "API-Dokumentation", um den Aufruf zu finden, der unseren Anforderungen am besten entspricht, wie im folgenden Screenshot gezeigt:




Nach Überprüfung der erforderlichen Parameter können wir die Anfrage wie folgt erstellen.  Beachten Sie, dass in diesem Fall anstelle eines POST eine Anforderung vom Typ "GET" ausgeführt wird, z. B. die Authentifizierungsmethode:

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

Wir erhalten jedoch die folgende Antwort, die angibt, dass entweder das Authentifizierungstoken ungültig oder abgelaufen ist:

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

Wir müssten ein neues Authentifizierungstoken erzeugen, um die Abfrage auszuführen und die gewünschten Ergebnisse zu erhalten, z. B.:

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

Die Ausgabe im Antworttext wird im JSON-Format an den Aufrufer gesendet, was der Standard ist.