Data Domain: использование встроенного API REST для DD и DDMC

Актуальную документацию можно найти на https://developer.dell.com/apis/products/data-protection.

DD и DDMC поставляются по умолчанию с включенным веб-интерфейсом REST API. REST API — это средство программного взаимодействия с DD и DDMC. В этой статье будут использоваться примеры для DD с использованием простого клиентско-серверного протокола. Протокол HTTP не сохраняет состояние и позволяет клиенту считывать состояние из DD и выполнять команды с помощью специально созданных HTTP-вызовов.

В командной строке следующая команда информирует о состоянии веб-службы REST API (веб-службы):

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

Обратите внимание, что API-интерфейс REST обслуживается с тех же портов, что и пользовательский интерфейс, отключить его отдельно невозможно. Это не представляет угрозы безопасности, так как все запросы к API должны проходить аутентификацию так же, как и запросы к пользовательскому интерфейсу или CLI.

Лучший способ начать работу с REST API — использовать клиент, входящий в комплект поставки на каждом DD и DDMC. Доступ к нему можно получить по следующим адресам:

https://DD_OR_DDMC_IP_ADDRESS/api/

При этом отображается страница со ссылками на несколько важных ресурсов, а именно:

• Документация по API: подробный список всех доступных вызовов API, поддерживаемых DD или DDMC.
• Тестовый клиент REST: проверьте вызовы API из самого веб-интерфейса DD

Документация по API — это все, что программист должен использовать для использования REST API DD для создания приложений на основе DD. 

Для использования API требуется аутентификация DD. Необходимы две части информации:

• X-DD-AUTH-TOKEN: файл cookie, который DD предоставляет после успешной аутентификации и должен использоваться в качестве аутентификатора для любых дальнейших запросов.
• X-DD-UUID: уникальный идентификатор DD, который будет использоваться для (большинства) запросов к API. Обратите внимание, что для отдельного DD это может выглядеть излишним, но это явно необходимо для DDMC, где можно выбрать индивидуальный DD.

Для аутентификации в DD используйте метод /rest/v1.0/auth. Чтобы сделать это с любого хоста с установленным "curl" и сетевым доступом к DD, и выполните запрос следующим образом:

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

Ниже приведено несколько комментариев по поводу выполнения командной строки выше:

• Опция "--include" необходима, так как некоторые ответы на запросы возвращаются в виде тегов ответов HTTP, а не как часть тела
• Опция "--insecure" необходима, если curl настроен для проверки сертификата CA сервера по списку известных и доверенных центров CA. Так как в клиенте тестирования REST, входящем в комплект поставки DD, эта функция не предусмотрена, но она должна использоваться для проверки сертификатов источника сертификатов, в противном случае все команды, выполняемые в тестовом клиенте, завершаются сбоем (undefinedERROR Text Status: error). При попытке выполнить пример «curl» из командной строки ошибка будет следующей:

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.

• Мы используем метод HTTP «POST». У каждого метода API есть свой метод, который четко выделен в документации.
• Опции "--header" используются для передачи заголовков уровня HTTP или опций в вызываемый DD
• "-d" отправляет тело запроса в ДД, в данном случае логин и пароль
• Наконец, в качестве последнего параметра вызывается URI, вызывающий конкретный метод проверки подлинности (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth). Поскольку мы используем HTTPS, учетные данные передаются по сети в зашифрованном виде. Примечание. В то время как доступ к документации и встроенному тестовому клиенту осуществляется через порт 443, точка входа сервиса REST API находится на порте 3009 и для работы должна использовать HTTPS (не HTTP)

Ответ на приведенный выше запрос проверки подлинности показан ниже:

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

Все, что находится перед пустой строкой, — это заголовки HTTP, отправленные в ответе. Content after — это тело ответа, которое в данном случае информирует об успешном выполнении. Для этого метода наиболее важными данными являются:

• X-DD-AUTH-TOKEN (434f1d6dc1528bb8d3ad66c70dc7f74f9) Это временный токен аутентификации, который можно использовать в течение определенного времени для аутентификации дальнейших операций
• X-DD-UUID (7850d7a24f93f502:1346d63c57821e38) идентификатор запрашиваемого DD, который необходимо использовать для последующих запросов

Для любого дальнейшего запроса мы должны использовать эти значения. Например, предположим, что мы хотим найти информацию для файловой системы DD. Перейдите в «Документацию API», чтобы найти вызов, который лучше всего соответствует нашим потребностям, как показано на скриншоте ниже:




Проверив необходимые параметры, мы можем построить запрос, как показано ниже.  Обратите внимание, что в этом случае мы запускаем запрос типа «GET» вместо «POST», например, метод аутентификации:

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

Но мы получаем следующий ответ, указывающий на то, что маркер проверки подлинности недействителен или срок его действия истек:

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

Нам нужно будет сгенерировать новый токен аутентификации, чтобы выполнить запрос и получить желаемые результаты, например:

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

Выходные данные в теле ответа отправляются вызывающей стороне в формате JSON, который является стандартным.