Data Domain:DDおよびDDMCに組み込みREST APIを使用する方法

最新のドキュメントは 、https://developer.dell.com/apis/products/data-protection にあります。

DDとDDMCはどちらも、デフォルトでWebベースのREST APIが有効になっています。REST APIは、DDおよびDDMCとプログラムでやり取りするための手段です。この記事では、これからはシンプルなクライアントおよびサーバー プロトコルを使用するDDの例を使用します。HTTPプロトコルは状態を保持せず、クライアントはDDから状態を読み取り、特別に細工されたHTTPコールでコマンドを実行することができます

次のコマンドは、コマンド ラインからWebベースのREST APIサービス(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
-----------   -------   ---------------------
...

REST APIはUIと同じポートから処理されるため、個別に無効にすることはできません。UIやCLIへの要求と同様に、APIへのすべての要求を認証する必要があるため、セキュリティ リスクは発生しません

REST APIの使用を開始する最善の方法は、すべてのDDおよびDDMCでバンドルされたクライアントを使用することです。次の場所からアクセスできます。

https://DD_OR_DDMC_IP_ADDRESS/api/

これにより、いくつかの重要なリソースへのリンクを含むページが表示されます。次に例を示します。

• APIドキュメント:DDまたはDDMCでサポートされている使用可能なすべてのAPIコールの詳細なリスト
• RESTテスト クライアント:DD Webインターフェイス自体からのAPIコールをテストします

APIドキュメントは、DD REST APIを活用してDD上にアプリケーションを構築するためにプログラマーが使用する必要があるすべてです。

APIを使用するには、DD認証が必要です。次の 2 つの情報が必要です。

• X-DD-AUTH-TOKEN:認証が成功したときにDDから提供されるCookie。以降の要求に対しては、トークンとして使用する必要があります。
• X-DD-UUID:APIへの(ほとんどの)リクエストに使用する一意のDD識別子。個々のDDにとっては不必要に見えるかもしれませんが、個々のDDを選択できるDDMCでは明らかに必要です。

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'

上記のコマンドラインに関するいくつかのコメントは次のとおりです。

• 一部のクエリ応答は本文の一部としてではなく、HTTP応答タグとして返されるため、オプション「--include」が必要です
• curlが既知の信頼できるCA認証局のリストと照合してサーバーCA証明書をチェックするように設定されている場合は、オプション「--insecure」が必要です。DDにバンドルされているREST TESTクライアントはこのオプションを追加しませんが、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」オプションは、呼び出されたDDにHTTPレベルのヘッダーまたはオプションを渡すために使用されます
• 「-d」はリクエストの本文をDDに送信します。この場合は、ユーザー名とパスワードです
• 最後に、特定の認証方法を呼び出す URI が最後のパラメーター (https://DD_OR_DDMC_IP_ADDRESS:3009/rest/v1.0/auth) として呼び出されます。HTTPSを使用しているため、認証情報は暗号化されてネットワーク上を移動します。ドキュメントと組み込みテスト クライアントにはポート443からアクセスしますが、REST APIサービス エントリー ポイントはポート3009にあり、動作するには(HTTPではなく)HTTPSを使用する必要があります

上記の認証クエリーに対する応答を以下に示します。

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のID。後の要求に使用する必要があります

それ以上の要求には、これらの値を使用する必要があります。たとえば、DDファイルシステムの情報を検索するとします。「APIドキュメント」に移動して、以下のスクリーンショットのように、ニーズに最も適した呼び出しを見つけます:

 


必要なパラメーターを確認した後、次のようにリクエストを作成できます。この場合、次のような認証方法ではなく、「GET」タイプの要求を実行することに注意してください。

# 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 形式で呼び出し元に送信されます。