Data Domain: Cómo usar la API REST integrada para DD y DDMC

La documentación más reciente se puede encontrar en https://developer.dell.com/apis/products/data-protection.

Tanto los DD como los DDMC vienen de manera predeterminada con una API REST basada en la web habilitada. Una API REST es un medio para interactuar mediante programación con DD y DDMC. En este artículo, se usarán ejemplos para DD a partir de ahora mediante un protocolo de cliente y servidor simple. El protocolo HTTP no mantiene ningún estado y permite que un cliente lea el estado de los DD y ejecute comandos con llamadas HTTP especialmente diseñadas.

Desde la línea de comandos, el siguiente comando informa sobre el estado del servicio de API REST basada en web (servicio web):

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

Tenga en cuenta que, dado que la API REST se realiza desde los mismos puertos que la interfaz de usuario, no hay manera de deshabilitarla por separado. Esto no representa un riesgo de seguridad, ya que todas las solicitudes a la API se deben autenticar de la misma manera que las solicitudes a la interfaz de usuario o la CLI.

La mejor manera de comenzar con la API REST es usar el cliente incluido en cada DD y DDMC. Puede acceder a la herramienta en la siguiente ubicación:

https://DD_OR_DDMC_IP_ADDRESS/api/

Esto presenta una página con enlaces a varios recursos importantes, a saber:

• Documentación de la API: lista detallada de todas las llamadas de API disponibles compatibles con DD o DDMC
• Cliente de prueba REST: pruebe las llamadas a la API desde la propia interfaz web de DD

La documentación de la API es todo lo que un programador debe usar para aprovechar la API REST de DD con el fin de crear aplicaciones sobre DD. 

Se requiere autenticación de DD para usar la API. Se necesitan dos datos:

• X-DD-AUTH-TOKEN: una cookie que DD proporciona tras una autenticación correcta y que se debe usar como autenticador para cualquier solicitud adicional.
• X-DD-UUID: el identificador único de DD que se usará para (la mayoría) de las solicitudes a la API. Tenga en cuenta que esto puede parecer superfluo para un DD individual, pero es claramente necesario para DDMC, donde se puede elegir un DD individual.

Para autenticarse en DD, utilice el método "/rest/v1.0/auth". Para hacerlo desde cualquier host con "curl" instalado y acceso de red a DD, emita la solicitud de la siguiente manera:

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

A continuación, se muestran algunos comentarios sobre la línea de comandos ejecutada anteriormente:

• Se necesita la opción "--include", ya que algunas de las respuestas de consulta se devuelven como etiquetas de respuesta HTTP, no como parte del cuerpo
• La opción "--insecure" es necesaria cuando curl está configurado para comprobar el certificado de CA del servidor con una lista de autoridades de CA conocidas y de confianza. Como el cliente de REST TEST incluido con DD no agrega esta opción, pero se debe usar para verificar los certificados de CA, o todos los comandos ejecutados desde dentro del cliente de prueba fallarán (estado del texto undefinedERROR: error). Si, en cambio, se intenta ejecutar un "curl" de ejemplo desde la línea de comandos, el error sería:

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.

• Utilizamos el método "POST" de HTTP. Cada método de API tiene su propio método, que se destaca claramente en la documentación.
• Las opciones "--header" se utilizan para pasar encabezados u opciones de nivel HTTP al DD llamado
• "-d" envía el cuerpo de la solicitud a DD, en este caso, el nombre de usuario y la contraseña
• Por último, el URI que llama al método de autenticación específico se llama como el último parámetro (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Como usamos HTTPS, las credenciales viajan encriptadas por cable. Tenga en cuenta que se accede a los documentos y al cliente de prueba integrado a través del puerto 443, el punto de entrada del servicio de API REST se encuentra en el puerto 3009 y debe usar HTTPS (no HTTP) para funcionar

A continuación, se muestra la respuesta a la consulta de autenticación anterior:

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

Todo lo que está antes de la línea en blanco son encabezados HTTP enviados en la respuesta. Content after es el cuerpo de la respuesta, que en este caso informa del éxito. Para este método, los datos más importantes son:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Este es un token de autenticación temporal, que se puede utilizar durante un período de tiempo determinado para autenticar otras operaciones
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) el ID del DD que se solicita, que se debe utilizar para solicitudes posteriores

Para cualquier solicitud adicional, debemos usar esos valores. Por ejemplo, supongamos que queremos encontrar información para un sistema de archivos DD. Vaya a la "Documentación de la API" para localizar la llamada que mejor se adapte a nuestras necesidades, como en la captura de pantalla a continuación:




Después de verificar los parámetros necesarios, podemos construir la solicitud como se muestra a continuación.  Tenga en cuenta que, en este caso, ejecutamos una solicitud de tipo "GET", en lugar de una "POST", como el método de autenticación:

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

Sin embargo, obtenemos la siguiente respuesta, que indica que el token de autenticación no es válido o ha caducado:

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

Tendríamos que generar un nuevo token de autenticación para ejecutar la consulta y obtener los resultados deseados, por ejemplo:

# 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 salida en el cuerpo de la respuesta se envía al autor de la llamada en formato JSON, que es el estándar.