Data Domain: como usar a API REST incorporada para DD e DDMC

A documentação mais recente pode ser encontrada em https://developer.dell.com/apis/products/data-protection.

Por padrão, os DDs e DDMCs vêm com uma API REST baseada na Web ativada. Uma API REST é um meio de interagir programaticamente com DDs e DDMCs. Este artigo usa exemplos para DDs a partir de agora usando um protocolo simples de client e servidor. O protocolo HTTP não mantém nenhum estado e permite que um client leia o estado dos DDs e execute comandos com chamadas HTTP especialmente criadas.

Na linha de comando, o seguinte comando informa o status do serviço de API REST baseado na Web (serviço 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
-----------   -------   ---------------------
...

Observe que, como a API REST é atendida nas mesmas portas que a interface do usuário, não há como desativá-la separadamente. Isso não representa nenhum risco de segurança, pois todas as solicitações para a API precisam ser autenticadas, da mesma forma que as solicitações para a interface do usuário ou CLI.

A melhor maneira de começar a usar a API REST é usando o client incluído em cada DD e DDMC. Ele pode ser acessado no seguinte local:

https://DD_OR_DDMC_IP_ADDRESS/api/

Isso apresenta uma página com links para vários recursos importantes, a saber:

• Documentação da API: lista detalhada de todas as chamadas API disponíveis compatíveis com o DD ou DDMC
• Client de teste REST: teste as chamadas de API a partir da própria interface Web do DD

A documentação da API é tudo o que um programador deve usar para aproveitar a API REST do DD e criar aplicativos sobre o DD. 

A autenticação do DD é necessária para usar a API. Duas informações são necessárias:

• X-DD-AUTH-TOKEN: Um cookie que o DD fornece após a autenticação bem-sucedida e deve ser usado como autenticador para quaisquer outras solicitações.
• X-DD-UUID: O identificador exclusivo do DD a ser usado para (a maioria) das solicitações à API. Observe que, para um DD individual, isso pode parecer supérfluo, mas é claramente necessário para DDMCs, em que um DD individual pode ser escolhido.

Para fazer a autenticação no DD, use o método "/rest/v1.0/auth". Para fazer isso a partir de qualquer host com "curl" instalado e acesso de rede ao DD, execute a solicitação da seguinte maneira:

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

Alguns comentários sobre a linha de comando executada acima seguem:

• A opção "--include" é necessária, pois algumas das respostas da consulta voltam como tags de resposta HTTP, não como parte do corpo
• A opção "--insecure" é necessária quando curl é configurado para verificar o certificado da CA do servidor em relação a uma lista de autoridades de CA conhecidas e confiáveis. Como o client REST TEST empacotado com o DD não adiciona essa opção, mas ela deve ser usada para verificar os certificados CA ou todos os comandos executados a partir do client de teste falham (undefinedERROR Text Status: error). Se você tentar executar um exemplo "curl" a partir da linha de comando, o erro seria:

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.

• Estamos usando um método HTTP "POST". Cada método de API tem seu próprio método, que é claramente destacado na documentação.
• As opções "--header" são usadas para passar cabeçalhos ou opções de nível HTTP para o DD chamado
• "-d" envia o corpo da solicitação para o DD, neste caso, o nome de usuário e a senha
• Finalmente, o URI que chama o método de autenticação específico é chamado como o último parâmetro (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Como estamos usando HTTPS, as credenciais viajam criptografadas pelo fio. Observe que, enquanto os documentos e o cliente de teste incorporado são acessados pela porta 443, o ponto de entrada do serviço da API REST está na porta 3009 e deve usar HTTPS (não HTTP) para funcionar

A resposta à consulta de autenticação acima é mostrada abaixo:

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

Tudo antes da linha em branco são cabeçalhos HTTP enviados na resposta. Conteúdo depois é o corpo de resposta, que neste caso informa o sucesso. Para este método, os dados mais importantes são:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) é um token de autenticação temporário, que pode ser usado por um determinado período para autenticar outras operações
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) o ID do DD solicitado, que deve ser usado para solicitações posteriores

Para qualquer solicitação adicional, devemos usar esses valores. Por exemplo, digamos que queremos encontrar informações para um file system do DD. Vá para a "Documentação da API" para localizar a chamada que melhor se adapta às nossas necessidades, como na captura de tela abaixo:




Depois de verificar os parâmetros necessários, podemos construir a solicitação conforme abaixo.  Observe que, nesse caso, executamos um tipo de solicitação "GET", em vez de "POST", como o método de autenticação:

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

Mas obtemos a seguinte resposta, indicando que o token de autenticação é inválido ou expirou:

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

Teríamos que gerar um novo token de autenticação para executar a consulta e obter os resultados pretendidos, por exemplo:

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

A saída no corpo da resposta é enviada ao chamador no formato JSON, que é o padrão.