📚 课程目录第2章 ONTAP REST API基础与认证

2. ONTAP REST API基础与认证

ONTAP 9.6 之后，REST API 成为与 CLI、ZAPI（ZAPI 是旧版私有 XML API）并列的一等管理接口。它的价值不只是“换一种调用方式”，而是把存储资源抽象成可被程序化读写的对象，让脚本、Ansible、Terraform、监控平台都能用同一套语义操作集群。理解 REST API，需要同时看清四件事：请求怎么走、方法表达什么意图、资源如何组织、身份如何被证明。

REST API 的请求架构

ONTAP 集群中每个节点都运行 REST 服务，管理 LIF 是入口。客户端把 HTTPS 请求发到管理 LIF 的 443 端口，请求先经过 Web 服务层，再进入 API 分发层，由它根据 URI 路径定位到对应的资源处理器，处理器调用底层管理框架完成实际操作，最后把结果序列化为 JSON 返回。整个过程是无状态的：每次请求都必须自带认证信息，服务端不保存会话上下文。

一个典型的请求由四部分组成：方法（GET/POST/PATCH/DELETE）、路径（如 /api/storage/volumes）、查询参数（如 ?fields=name,size&max_records=20）和请求体（JSON）。响应则包含状态码、响应头和 JSON 正文。状态码是最先要看的判断依据：200 表示成功，201 表示资源已创建，202 表示任务已接受但仍在后台执行，4xx 多为请求或权限问题，5xx 则指向服务端异常。

资源模型与 URI 组织

ONTAP REST API 的资源模型是层级化的。顶层按功能域划分，例如 /api/storage、/api/network、/api/svm、/api/cluster；每个域下再按资源类型细分，如 /api/storage/volumes、/api/storage/aggregates、/api/network/ip/interfaces。集合资源用复数表示，单个实例通过 UUID 定位，例如 /api/storage/volumes/8a4b...c2。

每个资源对象都带有一组标准字段：uuid 是全局唯一标识，name 是用户可读名称，_links 提供自链接和关联资源链接，_actions 描述该资源支持的特殊操作。查询时可以用 fields 控制返回字段、用 max_records 和 next 做分页、用 filter 做条件筛选。例如只取卷名和大小：

GET /api/storage/volumes?fields=name,size&max_records=50

响应中的 num_records 和 _links.next 是分页判断的关键：当 _links.next 存在时，说明还有下一页，应继续请求该链接直到取完。

三种认证方式

基本认证最简单：把用户名和密码用 Base64 编码后放进 Authorization: Basic 头。它适合临时调试，但每次请求都携带凭据，生产环境应配合 HTTPS 使用，且不建议长期使用。

OAuth 2.0 是推荐的自动化认证方式。客户端先用凭据向 /api/security/oauth2/token 换取访问令牌，之后每次请求在 Authorization: Bearer 头中携带令牌。令牌有有效期，过期后需重新获取或使用刷新令牌。这种方式避免了密码在每次请求中传输，也便于集中吊销。

证书认证基于 TLS 双向认证：客户端持有由集群信任的 CA 签发的证书，请求时出示证书，服务端校验通过后即完成身份确认。它适合无人值守的自动化场景，不需要在脚本中保存密码或令牌。

选择建议：交互调试用基本认证；脚本和平台集成优先用 OAuth 2.0；对安全性要求高、且能管理证书生命周期的场景用证书认证。

API 版本管理与调试

ONTAP REST API 通过 URI 中的版本号管理兼容性，如 /api/v1、/api/v2。不同 ONTAP 版本支持的 API 版本不同，调用前应确认目标集群的版本。可以用 GET /api/cluster 查看集群信息，用 GET /api/support/ontap/version 确认软件版本。当接口在新版本中变更时，旧版本路径通常仍保留一段时间，但不应长期依赖。

交互式调试最直接的工具是 ONTAP 自带的 API 文档页面：在浏览器访问 https://<管理LIF>/docs/api/，可以浏览所有资源、查看字段说明、直接发起请求并观察响应。调试时建议先用 GET 确认资源存在，再用 POST 创建，最后用 GET 验证结果。遇到 4xx 时，响应体会给出 error.code 和 error.message，这是定位问题的第一手依据。

注意：REST API 的写操作可能触发异步任务。返回 202 时并不代表操作已完成，应通过响应中的 job 链接轮询任务状态，确认 state 为 success 后再进行下一步。

一个完整的调用示例

假设要在 SVM svm_prod 上创建一个 100GB 的卷，先获取令牌，再提交创建请求：

# 1. 获取 OAuth 2.0 令牌
curl -k -X POST https://10.0.0.10/api/security/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=admin&password=NetApp123"

# 2. 使用令牌创建卷
curl -k -X POST https://10.0.0.10/api/storage/volumes \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"vol_app01","svm":{"name":"svm_prod"},"size":107374182400,"style":"flexvol"}'

创建成功后返回 201，响应体包含新卷的 uuid、name、size 等字段。随后用 GET /api/storage/volumes?name=vol_app01 验证卷已存在且状态为 online，即完成一次闭环调用。若返回 202，则需跟踪任务链接直到状态变为 success。

掌握这些基础后，后续的自动化配置、监控采集和故障排查都可以建立在同一套请求模型之上：明确方法语义、定位资源路径、选择合适认证、处理版本与异步任务，就能稳定地与 ONTAP 集群交互。