Data Domain：如何将嵌入式 REST API 用于 DD 和 DDMC

可在 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 相同的端口提供服务，因此无法单独禁用它。这不会带来安全风险，因为对 API 的所有请求都需要进行身份验证，方式与对 UI 或 CLI 的请求相同。

开始使用 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 身份验证。需要两条信息：

• X-DD-AUTH-TOKEN：DD 在成功进行身份验证时提供的 Cookie，必须用作任何进一步请求的验证器。
• X-DD-UUID：用于对 API 的（大多数）请求的唯一 DD 标识符。请注意，对于单个 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 响应标记返回，而不是作为正文的一部分
• 将 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”选项用于将 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 的 ID，必须用于以后的请求

对于任何其他请求，我们必须使用这些值。例如，假设我们想要查找 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 格式发送给调用方，这是标准格式。