控制 API 请求的输入变量
您可以通过 HTTP 请求中设置的参数和变量来控制如何处理 API 调用。
HTTP 方法
SnapCenter REST API 支持的 HTTP 方法如下表所示。
|
并非所有 HTTP 方法在每个 REST 端点上都可用。 |
HTTP 方法 | 描述 |
---|---|
GET |
检索资源实例或集合上的对象属性。 |
POST |
根据提供的输入创建一个新的资源实例。 |
DELETE |
删除现有的资源实例。 |
PUT |
修改现有的资源实例。 |
请求标头
您应该在 HTTP 请求中包含几个标头。
内容类型
如果请求主体包含 JSON,则此标头应设置为 application/json。
接受
此标头应设置为 application/json。
授权
应设置基本身份验证,将用户名和密码编码为 base64 字符串。
请求正文
请求主体的内容根据具体调用而有所不同。HTTP请求主体由以下之一组成:
-
带有输入变量的 JSON 对象
-
空
过滤对象
发出使用 GET 的 API 调用时,您可以根据任意属性限制或过滤返回的对象。例如,您可以指定要匹配的精确值:
<field>=<query value>
除了精确匹配之外,还可以使用其他运算符来返回一系列值上的对象。 SnapCenter REST API 支持下表所示的过滤运算符。
运算符 | 描述 |
---|---|
= |
等于 |
< |
少于 |
> |
大于 |
⇐ |
小于或等于 |
>= |
大于或等于 |
更新 |
或 |
! |
不等于 |
* |
贪婪通配符 |
您还可以通过使用 null 关键字或其否定 !null 作为查询的一部分,根据特定字段是否设置来返回对象集合。
|
任何未设置的字段通常都会被排除在匹配查询之外。 |
请求特定对象字段
默认情况下,使用 GET 发出 API 调用仅返回唯一标识一个或多个对象的属性。这组最小字段将充当每个对象的键,并根据对象类型而有所不同。您可以使用 `fields`查询参数有以下几种方式:
通用或标准字段
指定 fields=* 来检索最常用的对象字段。这些字段通常保存在本地服务器内存中或几乎不需要处理即可访问。这些是使用带有 URL 路径键(UUID)的 GET 后为对象返回的相同属性。
所有字段
指定 fields=** 来检索所有对象字段,包括那些需要额外的服务器处理才能访问的字段。
自定义字段选择
使用 fields=<field_name> 指定您想要的确切字段。请求多个字段时,必须使用逗号分隔值,且不能使用空格。
|
作为最佳实践,您应该始终识别所需的特定字段。您应该只在需要时检索公共字段集或所有字段。哪些字段被归类为常见字段并使用 fields=* 返回,由NetApp根据内部性能分析确定。字段的分类在未来的版本中可能会发生变化。 |
对输出集中的对象进行排序
资源集合中的记录将按照对象定义的默认顺序返回。您可以使用 `order_by`查询参数的字段名称和排序方向如下:
order_by=<field name> asc|desc
例如,您可以按降序对类型字段进行排序,然后按升序对 id 进行排序:
order_by=type desc, id asc
-
如果指定了排序字段但未提供方向,则值将按升序排序。
-
当包含多个参数时,必须用逗号分隔字段。
检索集合中的对象时进行分页
当使用 GET 发出 API 调用来访问同一类型的对象集合时, SnapCenter会尝试根据两个约束返回尽可能多的对象。您可以使用请求中的附加查询参数来控制每个约束。对于特定的 GET 请求,达到的第一个约束将终止该请求,从而限制返回的记录数。
|
如果请求在遍历所有对象之前结束,则响应包含检索下一批记录所需的链接。 |
限制对象的数量
默认情况下, SnapCenter对于 GET 请求最多返回 10,000 个对象。您可以使用 max_records 查询参数更改此限制。例如:
max_records=20
根据相关时间限制以及系统中的对象总数,实际返回的对象数量可能小于有效的最大值。
限制检索对象所用的时间
默认情况下, SnapCenter会在 GET 请求允许的时间内返回尽可能多的对象。默认超时时间为 15 秒。您可以使用 return_timeout 查询参数更改此限制。例如:
return_timeout=5
根据对象数量的相关限制以及系统中对象总数,实际返回的对象数量可能小于有效的最大值。
缩小结果集
如果需要,您可以将这两个参数与其他查询参数组合以缩小结果集。例如,以下内容返回指定时间之后生成的最多 10 个 EMS 事件:
time⇒ 2018-04-04T15:41:29.140265Z&max_records=10
您可以发出多个请求来翻阅对象。每个后续 API 调用都应根据最后一个结果集中的最新事件使用新的时间值。
尺寸属性
一些 API 调用以及某些查询参数使用的输入值是数字。您可以选择使用后缀,而不是提供以字节为单位的整数,如下表所示。
后缀 | 描述 |
---|---|
KB |
KB 千字节(1024 字节)或千比字节 |
MB |
MB 兆字节(KB x 1024 字节)或兆比字节 |
GB |
GB 千兆字节(MB x 1024 字节)或吉比字节 |
TB |
TB 太字节 (GB x 1024 字节) 或太比字节 |
铅 |
PB 拍字节 (TB x 1024 字节) 或 pebibytes |