2. Pure Storage REST API基础

Pure Storage 的 FlashArray 与 FlashBlade 都提供了一套基于 HTTPS 的 REST API，管理界面（GUI）、命令行工具（purity、pureadm）以及第三方自动化平台最终都通过这套接口与阵列交互。要把它用起来，第一步不是急着发请求，而是先弄清三件事：怎么证明“我是谁”（认证）、请求和响应长什么样（格式）、怎么在大量对象中精准取数（分页与过滤）。本节围绕这三点展开，并用 curl 与 Postman 完成第一次真实调用。

一、认证机制：API Token 与 OAuth

Pure Storage REST API 的认证方式随版本演进，目前主流有两种：

• API Token（API 令牌）：这是 FlashArray 长期支持、也是最常用的方式。管理员在 GUI 的 Settings → Users → API Tokens 中为某个用户创建令牌，或通过 pureadmin 命令生成。令牌是一串长字符串，调用时放在 HTTP 请求头 x-auth-token 中。它的生命周期由创建时设定，可设置过期时间，也可随时撤销。
• OAuth 2.0：较新版本（Purity 6.x 及 FlashBlade 新版）支持 OAuth。客户端先用 client_id 与 client_secret 向 /oauth2/1.0/token 换取一个短期 access token，再在后续请求头 Authorization: Bearer <token> 中使用。OAuth 更适合多用户、多应用、需要细粒度授权的场景。

两者的核心区别在于：API Token 是“长期凭证直接使用”，OAuth 是“短期凭证换取后使用”。对于脚本化运维，API Token 更简单；对于平台级集成，OAuth 更规范。无论哪种方式，令牌都等同于密码，绝不能硬编码在脚本里或提交到代码仓库，应通过环境变量或密钥管理服务注入。

二、请求与响应格式

Pure Storage REST API 遵循 RESTful 风格，所有请求都通过 HTTPS，默认端口 443。请求方法语义清晰：GET 查询、POST 创建、PATCH 修改、DELETE 删除。请求体与响应体统一使用 JSON，请求头需带 Content-Type: application/json 与 Accept: application/json。

响应结构通常包含几个关键字段：items（对象数组）、continuation_token（分页游标）、total_item_count（总数）、more_items_remaining（是否还有更多）。例如查询卷列表时，返回的 items 中每个元素包含 name、size、serial、created 等属性。理解这个结构，是后续解析数据的基础。

三、分页与过滤

当对象数量很多时，API 不会一次性返回全部数据，而是分页返回。分页通过 limit 与 continuation_token 两个参数控制：limit 指定每页条数，响应中的 continuation_token 作为下一页请求的入参。循环调用直到 more_items_remaining 为 false，即可取完所有数据。

过滤则通过查询参数实现，常见的有 filter、sort、names。例如 ?filter=name='vol01' 精确匹配名称，?sort=name 按名称排序。合理使用过滤能显著减少传输量，也避免在客户端做二次筛选。

四、错误处理

API 通过 HTTP 状态码表达结果：200 成功、400 请求参数错误、401 认证失败、403 权限不足、404 对象不存在、500 服务端异常。响应体中通常包含 errors 数组，每项有 message 与 context，用于定位问题。脚本中应判断状态码，对 401 检查令牌是否过期，对 404 检查对象名，对 429（若出现）做退避重试。

五、用 curl 完成第一次调用

假设阵列管理地址为 10.20.30.40，已创建一个 API Token 并存入环境变量 PURE_TOKEN。查询卷列表的命令如下：

export PURE_TOKEN="你的API令牌"
curl -k -s -X GET \
  "https://10.20.30.40/api/2.19/volume?limit=5" \
  -H "x-auth-token: $PURE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

参数说明：-k 跳过自签名证书校验（生产环境应导入 CA 证书），-s 静默模式，-X GET 指定方法，limit=5 限制返回 5 条。若返回 401，说明令牌无效或过期；若返回 200 且 items 中有数据，说明调用成功。要取下一页，把响应中的 continuation_token 拼到 URL 上即可。

六、用 Postman 完成第一次调用

Postman 适合交互式调试。新建请求，方法选 GET，URL 填 https://10.20.30.40/api/2.19/volume。在 Headers 中添加 x-auth-token 与令牌值，Content-Type 与 Accept 均设为 application/json。若使用自签名证书，在 Settings → General 中关闭 SSL 证书验证。点击 Send 后，下方 Body 会以格式化 JSON 展示结果，可直观看到 items、continuation_token 等字段。建议把令牌存入 Postman 环境变量，避免每次手填。