Skip to main content
简体中文版经机器翻译而成，仅供参考。如与英语版出现任何冲突，应以英语版为准。

请求和响应 API 事务

贡献者
PDF

每次 Deploy API 调用都会作为 HTTP 请求执行给 Deploy 虚拟机，此请求会向客户端生成关联的响应。此请求 / 响应对被视为 API 事务。在使用 Deploy API 之前，您应熟悉可用于控制请求的输入变量以及响应输出的内容。

控制 API 请求的输入变量

您可以控制如何通过 HTTP 请求中设置的参数处理 API 调用。

请求标题

您必须在 HTTP 请求中包含多个标头，包括：

  • content-type 如果请求正文包含 JSON ，则必须将此标头设置为 application/json 。

  • 接受如果响应正文包含 JSON ，则必须将此标头设置为 application/json 。

  • 授权基本身份验证必须设置为用户名和密码，并以 base64 字符串进行编码。

请求正文

请求正文的内容因具体调用而异。HTTP 请求正文包含以下内容之一：

  • 包含输入变量（例如新集群的名称）的 JSON 对象

  • 空

筛选对象

发出使用 GET 的 API 调用时，您可以根据任何属性限制或筛选返回的对象。例如，您可以指定一个要匹配的精确值：

<field>=<query value>

除了精确匹配之外，还有其他运算符可用于返回一组值范围内的对象。ONTAP Select 支持如下所示的筛选运算符。

运算符 说明

=

等于

<

小于

>

大于

&lt ； =

小于或等于

&gt ； =

大于或等于

或

！

不等于

*

贪婪的通配符

您还可以在查询中使用 null 关键字或其否定（！ null ）来根据是否设置了特定字段返回一组对象。

选择对象字段

默认情况下，使用 GET 发出 API 调用时，仅返回唯一标识一个或多个对象的属性。这组最小的字段可用作每个对象的密钥，并因对象类型而异。您可以通过以下方式使用 fields query 参数选择其他对象属性：

  • 低成本字段指定 `fields=*`检索在本地服务器内存中维护的对象字段或需要很少处理才能访问的对象字段。

  • 昂贵的字段指定 `fields=**`检索所有对象字段、包括需要额外服务器处理才能访问的字段。

  • 自定义字段选择 `fields=FIELDNAME`用于指定所需的确切字段。请求多个字段时，必须使用逗号分隔值，不能包含空格。

提示 作为最佳实践，您应始终确定所需的特定字段。您只能在需要时检索一组廉价或昂贵的字段。成本低且昂贵的分类由 NetApp 根据内部性能分析确定。给定字段的分类可以随时更改。

对输出集中的对象进行排序

资源收集中的记录将按对象定义的默认顺序返回。您可以使用order_by查询参数以及字段名称和排序方向更改顺序、如下所示：
order_by=<field name> asc|desc

例如、您可以按降序对类型字段进行排序、然后按升序对ID进行排序：
order_by=type desc, id asc

如果包含多个参数，则必须使用逗号分隔各个字段。

分页

使用 GET 发出 API 调用以访问同一类型的对象集合时，默认情况下会返回所有匹配的对象。如果需要，您可以在请求中使用 max_records 查询参数限制返回的记录数。例如：
max_records=20

如果需要，您可以将此参数与其他查询参数结合使用，以缩小结果集的范围。例如、以下命令最多返回在指定时间之后生成的10个系统事件：
time⇒ 2019-04-04T15:41:29.140265Z&max_records=10

您可以通过问题描述 发送多个请求来分页查看事件（或任何对象类型）。后续的每个 API 调用应根据最后一个结果集中的最新事件使用一个新的时间值。

解释 API 响应

每个 API 请求都会生成对客户端的响应。您可以检查响应以确定其是否成功，并根据需要检索其他数据。

HTTP 状态代码

下面介绍了 Deploy REST API 使用的 HTTP 状态代码。

代码 含义 说明

200

确定

表示未创建新对象的调用成功。

201

已创建

已成功创建对象；位置响应标头包含对象的唯一标识符。

202

已接受

已启动长时间运行的后台作业来执行请求，但操作尚未完成。

400

请求错误

此请求输入无法识别或不适当。

403

已禁止

由于授权错误，访问被拒绝。

404

未找到

请求中引用的资源不存在。

405

不允许使用此方法

此资源不支持请求中的 HTTP 动词。

409

冲突

尝试创建对象失败，因为此对象已存在。

500

内部错误

服务器发生一般内部错误。

501

未实施

此 URI 已知，但无法执行此请求。

响应标头

Deploy 服务器生成的 HTTP 响应包含多个标头，其中包括：

  • 每个成功的 API 请求的 request-id 都分配有一个唯一的请求标识符。

  • 位置创建对象时，位置标头包含新对象的完整 URL ，包括唯一对象标识符。

响应正文

与 API 请求关联的响应内容因对象，处理类型以及请求的成功或失败而异。响应正文将在 JSON 中呈现。

  • 单个对象可以根据请求使用一组字段返回单个对象。例如，您可以使用 GET 使用唯一标识符检索集群的选定属性。

  • 多个对象可以从一个资源收集返回多个对象。在所有情况下、都会使用一致的格式、其中会 num_records 指示包含对象实例数组的记录和记录的数量。例如，您可以检索特定集群中定义的所有节点。

  • 作业对象如果异步处理 API 调用，则返回作业对象，用于固定后台任务。例如，用于部署集群的 POST 请求会异步处理并返回作业对象。

  • Error 对象如果发生错误，则始终返回 Error 对象。例如，在尝试创建名称已存在的集群时，您将收到错误消息。

  • 空在某些情况下，不会返回任何数据，响应正文为空。例如，使用 delete 删除现有主机后，响应正文为空。