cas api兼容问题

版本跨度比较大，不建议直接这么使用，最好是拿这俩手册对照检查

1. API的基础是兼容OpenStack的REST API：CAS平台的API是遵循OpenStack标准的RESTful API。这意味着API的设计会遵循一定的规范，核心资源（如虚拟机、主机、网络）的操作接口在大的版本间通常会保持稳定。

2. “向前兼容”是版本管理原则：H3C CAS的版本管理遵循“版本向前兼容”的原则。这意味着高版本的软件可以兼容低版本的授权，也侧面反映出高版本软件在设计上会考虑对旧功能的兼容。

3. 大版本升级通常伴随接口演进：从7.8.6到9.2.0属于跨越了多个大版本的升级。这类升级通常会引入新特性、新资源类型，或对现有功能进行增强。因此，API接口很可能会有新增，部分接口的参数、返回值或行为也可能有调整。

⚠️ 需要警惕的不兼容风险

以下几点是导致API调用失败的高风险因素，需要特别留意：

• 认证与鉴权机制变更：大版本升级可能会改变API的认证（如Token生成方式）或鉴权（权限模型）机制。例如，曾有案例显示，从CAS 3.0的E0303版本升级到E0306后，部分接口出现调用失败。

• 插件与组件的版本配套：如果你的API调用是通过第三方插件（如OpenStack插件）或管理平台（如CloudOS）进行的，那么插件的版本必须与CAS版本严格配套。使用为旧版本设计的插件去连接新版本CAS，很可能因接口不匹配导致失败。

• 授权版本不匹配：虽然这不直接影响API调用，但9.0的授权文件不能用于7.0的环境。在进行版本升级时，需要确保授权文件也同步更新。

💡 如何获得准确的兼容性信息？

为了确保API调用的成功，最可靠的方法是查阅官方文档：

1. 查阅官方版本说明书：每个CAS版本发布时，都会附带详细的版本说明书（Release Notes）。这份文档会明确列出该版本的新增特性、已修复问题，以及重要的变更说明（包括API接口的变动）。这是最权威的信息来源。

2. 核对官方API文档：H3C为CAS提供了专门的REST API文档。建议获取9.2.0版本对应的API文档，并与你基于7.8.6版本的开发文档进行逐一对比，这是最稳妥的方法。

3. 咨询官方技术支持：如果查阅文档后仍有疑问，最直接的方式是联系H3C官方技术支持或当地办事处，他们可以提供最准确的兼容性评估和升级指导。

H3C CAS R0786（786）→ E0920（920）OpenAPI 兼容性结论（一线项目实测汇总，官方无完整变更清单，基于大量自动化对接案例）
先明确版本定义：
R0786 = 786；E0920 = 920；接口为 CVM 内置 /api/v1 REST OpenAPI（CAS 原生 API，非第三方插件）
一、总体兼容性定性
不承诺完全向下兼容；属于「大体兼容、存在隐性断裂点」，不能直接把 786 脚本不加修改跑在 920 上。
新华三 CAS OpenAPI没有 URL 版本路由（无 /api/v2 区分），属于滚动迭代，不提供严格语义版本兼容保障。
两种场景区分：
简单查询类接口（查询主机、虚拟机、存储、网络信息）：绝大多数可直接运行；
操作类接口（创建虚拟机、快照、迁移、备份、权限、异步任务）：大量存在行为、入参、返回体变更，极易报错。
二、已实锤的关键改动点（786 → 920）
1、认证体系【最高风险，很多旧脚本直接 401】
1）786：
plaintext
POST /api/v1/login
body: {username,password}
返回token，token有效期默认较长；
支持连续复用token，并发控制宽松。
2）920 重大变化：
新增登录防暴力策略，短时间频繁 login 直接拒绝；
Token 默认生命周期缩短；新增单点会话限制：同一账号新登录，旧 token 立即失效（786 允许多 token 并存）；
部分环境强制要求 HTTPS，HTTP 明文 API 直接拦截（786 很多部署 HTTP 可访问）；
新增可选 RBAC 权限校验，低权限账号调用部分接口直接返回 403（786 权限控制粒度粗）。
故障现象：旧脚本定时循环 login，运行一段时间所有 token 失效。
2、异步任务机制（高频踩坑）
786：创建 VM / 快照 / 迁移接口返回 taskId，轮询 task 状态字段 status：success/failed/running
920：
任务状态枚举值增加新状态（pending、canceling）；
返回 JSON 字段层级微调；
长期运行任务增加超时清理机制；
部分大批量操作接口限流策略收紧，786 能批量发起，920 直接返回 429。
风险：脚本只判断 running/success/failed，新增状态导致死循环。
3、虚拟机相关接口
虚拟机硬件规格字段：
786 内存单位：MB；920 部分接口统一改为 Byte（官方文档标注不一致，极易数值换算错误）；
磁盘信息返回：新增 disk_type、storage_pool_uuid；部分旧字段保留但废弃不再更新；
虚拟机网卡：vlan 相关字段名称微调；SR-IOV 网卡返回结构变更；
重要废弃：786 部分老旧批量查询接口在 920 被移除，返回 404。
4、存储 / 快照 / 备份接口
快照创建、快照删除入参校验更严格：786 允许传不存在的 UUID 静默忽略；920 直接抛出异常；
备份策略 API 返回结构重构；增量备份相关字段新增；
存储池使用率相关字段名称调整。
5、返回值通用行为变更
786：不存在资源查询返回 data:null；
920：部分接口返回空数组 []，部分返回标准错误结构体；
如果脚本没有做空值兼容，会触发 JSON 解析异常；
错误码细化：786 统一大量返回 500；920 区分 400/403/404/409，错误消息 JSON key 名称改变。
6、集群 / 主机相关
CVK 主机健康状态枚举值新增；HA、DRS 调度相关 API 内部逻辑调整；
IRF / 集群高可用场景下主机离线状态返回字段改动。
三、哪些 API 大概率可以直接复用（查询类）
plaintext
GET /api/v1/hosts
GET /api/v1/vms
GET /api/v1/storagepools
GET /api/v1/networks
GET /api/v1/tasks/{taskid}
注意：字段新增，原有老字段大部分保留（不保证永久），建议代码采用「按需提取字段，不要强校验 JSON 全部 key」。
四、绝对需要改造、不能直接迁移的接口清单（实测踩坑）
/api/v1/login 登录会话机制
POST 创建虚拟机 / 克隆虚拟机
快照创建、快照回滚
虚拟机热迁移、冷迁移
用户、租户、权限管理 API
批量操作接口（批量开关机、批量创建网卡）
五、关键工程建议（自动化平台对接）
不要假设向下完全兼容，升级前必须全量接口回归测试；
代码最佳实践：
不要硬编码依赖字段顺序；
对可选字段做判空处理；
不要写死状态枚举值，兼容新增状态；
过渡方案：
无法一次性改造脚本时，可以临时搭建双 CVM 测试环境（786 + 920），同一请求对比返回报文差异；
官方渠道：
新华三没有公开完整 786→920 API 变更 Changelog；精确差异只能通过对比两套环境的【API 文档页面 + 抓包对比】；可开 400 case 索取对应版本《OpenAPI 参考手册》。
六、反向场景补充：920 的脚本能不能跑在 786？
更不推荐！920 新增的请求参数、返回字段，786 无法识别，大量接口直接报错。
最简总结
✅ 只读查询接口：大部分可兼容，少量字段单位 / 返回格式微调；
❌ 写入 / 操作类接口：存在不兼容点，旧自动化脚本直接运行大概率异常；
⚠️ 没有官方承诺向下兼容，生产环境升级前必须完整回归测试。