Домен даних: як використовувати вбудований REST API для 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
-----------   -------   ---------------------
...

Зверніть увагу, оскільки REST API обслуговується з тих самих портів, що й інтерфейс, немає способу вимкнути його окремо. Це не становить загрози безпеці, оскільки всі запити до API мають бути автентифіковані, так само, як і запити до UI або CLI.

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

https://DD_OR_DDMC_IP_ADDRESS/api/

Тут представлена сторінка з посиланнями на кілька важливих ресурсів, а саме:

• Документація API: Детальний перелік усіх доступних API-викликів, які підтримуються DD або DDMC
• Клієнт тестування REST: Перевірте виклики API безпосередньо з веб-інтерфейсу DD.

Документація API — це все, що програміст повинен використовувати, щоб використовувати DD REST API для створення додатків на основі 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 TEST, що йде в комплекті з DD, не додає цієї опції, але її потрібно використовувати для перевірки сертифікатів CA, інакше всі команди, що виконуються з тестового клієнта, не працюють (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" надсилає тіло запиту DD, у цьому випадку — ім'я користувача та пароль
• Нарешті, 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-заголовки, які надсилаються у відповіді. Контент після — це тіло відповіді, яке в цьому випадку інформує про успіх. Для цього методу найважливішими даними:

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

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




Після перевірки необхідних параметрів ми можемо побудувати запит, як зазначено нижче.  Зверніть увагу, що в цьому випадку ми виконуємо запит типу «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, який є стандартом.