Data Domain : Utilisation de l’API REST intégrée pour DD et DDMC

La documentation la plus récente est disponible sur https://developer.dell.com/apis/products/data-protection.

Par défaut, les DD et les DDMC étaient livrés avec une API REST Web activée. Une API REST permet d’interagir par programmation avec des DD et des DDMC. Cet article utilise des exemples pour les DD utilisant désormais un protocole client et serveur simple. Le protocole HTTP ne conserve aucun état et permet à un client de lire l’état à partir des DD et d’exécuter des commandes avec des appels HTTP spécialement conçus.

À partir de la ligne de commande, la commande suivante informe de l’état du service d’API REST basé sur le Web (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
-----------   -------   ---------------------
...

Notez que l’API REST est gérée à partir des mêmes ports que l’interface utilisateur, il n’est pas possible de la désactiver séparément. Cela ne pose aucun risque de sécurité, car toutes les demandes adressées à l’API doivent être authentifiées, au même titre que les demandes adressées à l’interface utilisateur ou à l’interface de ligne de commande.

La meilleure façon de démarrer avec l’API REST est d’utiliser le client fourni sur chaque DD et DDMC. Il est accessible à l’emplacement suivant :

https://DD_OR_DDMC_IP_ADDRESS/api/

Cette page présente des liens vers plusieurs ressources importantes, à savoir :

• Documentation de l’API : liste détaillée de tous les appels d’API disponibles pris en charge par DD ou DDMC
• REST Test Client : teste les appels d’API à partir de l’interface Web DD elle-même

La documentation de l’API est tout ce qu’un programmeur doit utiliser pour tirer parti de l’API REST DD afin de créer des applications sur DD. 

L’authentification DD est requise pour utiliser l’API. Deux informations sont nécessaires :

• X-DD-AUTH-TOKEN : cookie que DD fournit une fois l’authentification réussie et qui doit être utilisé en tant qu’authentificateur pour toute demande ultérieure.
• X-DD-UUID : identifiant DD unique à utiliser pour la (plupart) des demandes adressées à l’API. Remarque : Cela peut sembler superflu pour un DD individuel, mais c’est clairement nécessaire pour les DDMC, où un DD individuel peut être choisi.

Pour effectuer une authentification auprès du DD, utilisez la méthode « /rest/v1.0/auth ». Pour ce faire, à partir de n’importe quel hôte sur lequel « curl » est installé et qui dispose d’un accès réseau au DD, envoyez la demande comme suit :

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

Voici quelques commentaires sur la ligne de commande ci-dessus :

• L’option « --include » est nécessaire, car certaines des réponses à la requête sont renvoyées sous forme de balises de réponse HTTP, et non sous forme de partie du corps
• L’option « --insecure » est nécessaire lorsque curl est configuré pour vérifier le certificat d’autorité de certification du serveur par rapport à une liste d’autorités d’autorité de certification connues et approuvées. Étant donné que le client REST TEST fourni avec DD n’ajoute pas cette option, elle doit être utilisée pour vérifier les certificats d’autorité de certification, sinon toutes les commandes exécutées à partir du client test échouent (undefinedERROR Text Status : error). Si vous essayez d’exécuter un exemple « curl » à partir de la ligne de commande à la place, l’erreur est la suivante :

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.

• Nous utilisons la méthode HTTP « POST ». Chaque méthode d’API possède sa propre méthode, qui est clairement mise en évidence dans la documentation.
• Les options « --header » sont utilisées pour transmettre des en-têtes ou des options de niveau HTTP au DD appelé
• « -d » envoie le corps de la demande au DD, dans ce cas, le nom d’utilisateur et le mot de passe
• Enfin, l’URI appelant la méthode d’authentification spécifique est appelé en tant que dernier paramètre (https ://DD_OR_DDMC_IP_ADDRESS :3009/rest/v1.0/auth). Comme nous utilisons HTTPS, les informations d’identification voyagent chiffrées sur le réseau. Notez que les documents et le client de test intégré sont accessibles via le port 443, le point d’entrée du service API REST se trouve sur le port 3009 et doit utiliser HTTPS (et non HTTP) pour fonctionner

La réponse à la requête d’authentification ci-dessus est affichée ci-dessous :

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

Tout ce qui précède la ligne vide correspond aux en-têtes HTTP envoyés dans la réponse. Le contenu après est le corps de la réponse, qui dans ce cas informe de la réussite. Pour cette méthode, les données les plus importantes sont :

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Il s’agit d’un jeton d’authentification temporaire, qui peut être utilisé pendant un laps de temps donné pour authentifier d’autres opérations
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) l’ID du DD demandé, qui doit être utilisé pour les demandes ultérieures

Pour toute demande ultérieure, nous devons utiliser ces valeurs. Par exemple, imaginons que nous voulons obtenir des informations pour un système de fichiers DD. Accédez à la « Documentation API » pour localiser l’appel qui répond le mieux à nos besoins, comme dans la capture d’écran ci-dessous :




Après avoir vérifié les paramètres nécessaires, nous pouvons créer la demande comme ci-dessous.  Notez que dans ce cas, nous exécutons un type de requête « GET », au lieu d’un « POST », comme la méthode d’authentification :

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

Mais nous obtenons la réponse suivante, indiquant que le jeton d’authentification n’est pas valide ou a expiré :

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

Nous devons générer un nouveau jeton d’authentification pour exécuter la requête et obtenir les résultats escomptés, par exemple :

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

La sortie dans le corps de la réponse est envoyée à l’appelant au format JSON, qui est la norme.