Storage Virtualize RESTful API

Storage Virtualize 具象状态传输 (REST) 模型应用程序编程接口 (API) 由用于创建，读取，更新和删除系统资源的命令目标组成。这些命令目标允许命令参数通过未编辑的命令传递到 Storage Virtualize 命令行界面，该命令行界面处理针对有效性和错误报告的解析参数规范。使用安全超文本传输协议 (HTTPS) 与 RESTful API 服务器成功通信。

RESTful API 服务器不考虑传输安全（例如，SSL），而是假设请求是从本地安全服务器发起的。 HTTPS 协议通过数据加密提供隐私。 RESTful API 通过要求使用令牌进行命令认证来提供安全性。令牌超时是用户可配置的选项，缺省值为 60 分钟。但是，可以使用 lssecurity 或 chsecurity 命令来查看和更改令牌超时值。

统一资源定位器 (URL) 针对系统上的不同节点对象。 HTTPS POST 方法作用于 URL 中指定的命令目标。要更改或查看系统上不同对象的信息，您必须创建请求并向系统发送请求。您需要为 RESTful API 服务器提供某些元素以接收请求并将其转换为命令，如下一节所述。

发出 HTTPS 请求

要使用 RESTful API 与系统交互，请使用有效的配置节点 URL 目标发出 HTTPS 命令请求。打开 TCP 端口 7433 并包含关键字 rest。对于AWS 上的 IBM Storage Virtualize for Public Cloud ，在使用RESTful API之前，您必须在 AWS中手动打开TCP端口7443。以下 URL 格式用于所有请求：

https://system_ip:7443/rest/v1/target/ID

其中：

system_ip 是将请求发送到的 IP 地址。
对于 Storage Virtualize RESTful API ，端口号始终为 7443。
rest 是关键字。
v1 是 API V 1。
target 是命令的目标对象，其中包含任意对象标识、名称和参数。
ID 是对象标识。

https://system_ip:7443/rest/v1/command

其中：

system_ip 是系统 IP 地址，是系统的配置节点所采用的地址。
对于 Storage Virtualize RESTful API ，端口号始终为 7443 。
rest 是关键字。
v1 是 API 的版本 1。
command 是目标命令对象（例如，带有任何参数的 auth 或 lseventlog）。
command 规范遵循以下格式：
```
command_name,method="POST",headers={'parameter_name': 'parameter_value',
'parameter_name': 'parameter_value',...}
```

为何仅使用 POST: 所有 Storage Virtualize RESTful API 命令目标都以 Storage Virtualize 命令命名，其名称已反映 "创建" ， "读取" ， "更新" 和 "删除" 操作。 MK 命令创建 (create) 资源，LS 命令列出 (read) 资源，CH 命令更改 (update) 资源，RM 命令删除 (delete) 资源。在此类命令上使用 HTTP 方法是多余的。

所有命令 (包括 LS 命令) 都至少接受一个指定参数，因为 Storage Virtualize RESTful API 仅为 POST 方法。它实现了将位置参数追加到 URI 的约定，并将指定的参数作为 JavaScript 对象表示法 (JSON) 字符串打包到请求主体中。

为什么我们不使用GET ：大多数 HTTP拒绝带有正文数据的GET请求。要支持 GET，意味着将命名参数作为查询字符串附加到 URI。查询字符串不支持任意数据。有效 URI 不能包含数据中可能存在的任何空格和其他保留字符。因此，在将命名参数数据附加到 URI 之前，您必须对其进行 URL 编码。除了这种不便之外，命名参数数据的键值结构必须以某种方式传达。查询字符串可能是 URL 编码的 JSON 对象。支持 GET 方法意味着在数据作为 HTTP 请求的一部分发送之前，以您选择的编程语言表示的参数数据必须通过两个单独的编码器。

命令目标的更优雅的方法是专门采用 POST。

如上文所述，除了命令目标的 URL 和名称之外，请求行和 HTTP 请求正文中还需要其他信息，这些信息与对指定对象执行的操作有关。在请求行中，包含 POST HTTP 方法。在请求正文中包含任何必需的参数（例如，RAID 级别或 IP 地址）。如需了解更多信息，请参考 https://<system-ip>:7443/rest/explorer/ 获取 OpenApi 浏览器指南。

在 HTTP 主体中提供任何必需的参数作为有效的 JSON，如以下示例所示：

{'X-Auth-Username': 'superuser'}

请求被路由到指定目的地（必须是系统的配置节点）的 7443 端口，RESTful API 服务器在此接收请求。服务器运行命令，收集任何结果输出，然后创建一个 HTTP 响应，如下例所示：

响应头

 content-length: 273 
 content-type: application/json;  charset=UTF-8 
 date: Mon,21 Jun 2021 10:47:18 GMT 
 server: nginx 
 strict-transport-security:  max-age=31536000; includeSubDomains

响应主体

{
  "key": "value"
}

API 限制

为了处理来自客户端的传入请求，Web 服务器配置了一些速率限制，以使 API 不会失败。如果达到该限制，API 会向客户端返回 429 HTTP 错误代码。下表列出了在 Web 服务器上配置的速率限制。

表 1.
速率限制	类型	请求数
每个集群的最大活动连接数	RESTful API	4
针对认证端点的最大请求数/秒	RESTful API	3
针对命令端点的最大请求数/秒	RESTful API	10
同时进行的 CLI 数	系统	1

认证概述

除了数据加密之外，HTTPS 服务器还要求对每个 API 会话的有效用户名和密码进行认证。使用两个认证头字段指定凭证：X-Auth-Username 和 X-Auth-Password。

/auth 端点使用 POST 方法来处理认证请求。 /auth 端点返回 JWT（JSON Web 令牌）认证令牌，该令牌对用户运行的每个命令进行认证。 JWT 令牌具有编码到其中的令牌到期时间。

初始身份验证要求您使用用户名和密码对认证目标 (/auth) 执行 POST。 RESTful API 服务器返回 JWT 令牌。系统支持配置 10 分钟到 2 小时之间的会话。但是，缺省单个会话最多持续 1 小时。如果达到最大分配时间，则会出现错误代码 403，指示授权丢失。另外，令牌到期是可配置项，可以设置为 10 到 120 分钟。使用 /auth 命令目标再次使用用户名和密码进行授权。

例如，以下命令将身份验证命令传递到端口 7443 处的目标节点 IP 192.168.10.109：

https://192.168.10.109:7443/rest/v1/auth, method="POST", 
   headers={'X-Auth-Username': 'superuser', 'X-Auth-Password': 'passw0rd'}

发送到 API 服务器的 HTTP 请求如下所示：


:authority: 192.168.10.109:7443
:method: POST
:path: /rest/v1/auth
:scheme: https
accept: application/json
content-length: 0
x-auth-password: passw0rd
x-auth-username: superuser

其中：

主机将 HTTP 请求定向到系统上的端口 (7443) 和 IP 地址 (192.168.10.109)。
POST是 Storage Virtualize 支持的唯一 HTTPS 方法
rest 是关键字。
v1 是 API 的版本 1。
/auth 是认证请求命令。
accept 指定内容类型 (application/json)。
内容长度指定消息大小。
x-auth-password 和 x-auth-username 字段用于认证和检索令牌。

成功的 auth 命令会返回类似于以下示例的令牌：

{"token":
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MTg4NDc4ODAsImV4cCI6MTYxODg1
MTQ4MCwianRpIjoiYTMzY2VlYmRkZGM3YmFhOTUwMmZmNGQ5ZmEwMzBhZTIiLCJzdiI6eyJ1c2VyI
joic3VwZXJ1c2VyIn19.1SXD8DoUYY-BO_cjGL9XZSnjTyBSRfp25YSWbr0Y9k5UaQrmz8xtp2XU
TR5l0PZKhqii4eU2AYf7gaTd3kfxWw}

可以使用网络上免费提供的任何 JWT 解码库对返回的令牌字符串进行解码。以下是解码后的 JWT 令牌字符串示例：

HEADER:ALGORITHM & TOKEN TYPE
{
  "typ": "JWT",
  "alg": "HS512"
}
PAYLOAD:DATA
{
  "iat": 1618847880,
  "exp": 1618851480,
  "jti": "a33ceebdddc7baa9502ff4d9fa030ae2",
  "sv": {
    "user": "superuser"
  }

}

API 认证管理

要进行认证，请使用用户标识和认证 (auth) 目标。

使用认证命令目标 (auth) 通过 POST 方法进行认证。在此过程中，通过 X-Auth-Username 和 X-AuthPassword 头字段提供用户名和密码。会话的开始是您必须输入用户名和密码的唯一实例。成功输入用户名和密码后，将显示身份验证 JWT 令牌，其中包含已编码的到期时间。令牌是一个 base64 编码的字符串，您可以使用 X-Auth-Token 头将其包含在以后的命令中。 X-Auth-Token 头与 JWT 认证令牌的组合会替换每个操作的用户名和密码。 JWT 令牌授权小时数是用户可配置的。即使令牌未使用，令牌也仅在配置的时间内保持授权。 JWT 令牌的缺省授权时间为一小时。到达配置时间后，出现403错误代码，表示授权丢失。使用 /auth 命令目标以使用用户名和密码进行重新认证。

系统支持配置 10 分钟到 2 小时之间的会话。但是，缺省单个会话最多持续 1 小时。如果达到最大分配时间，则会出现错误代码 403，指示授权丢失。

REST 响应

以下示例显示 lsuser 命令的 REST 响应：

[
    {
        "id": "0",
        "name": "superuser",
        "password": "yes",
        "ssh_key": "no",
        "remote": "no",
        "usergrp_id": "0",
        "usergrp_name": "SecurityAdmin",
        "owner_id": "",
        "owner_name": "",
        "locked": "no",
        "password_change_required": "no"
    }
]

以下示例显示使用 SSH 协议的 lsuser 命令：

lsuser

生成的输出：


id name password ssh_key remote usergrp_id usergrp_name owner_id owner_name locked password_change_required
0 superuser yes   no      no     0          SecurityAdmin                    no        no

命令目标参数

请参阅 https://<system_ip>:7443/rest/explorer/ 以获取命令目标参数的 OpenApi 资源管理器。