雨云 RainYun API 实操：认证、分页 options 坑与产品线地图
最近把雨云（RainYun）的 OpenAPI 跑通了，把云服务器、游戏云、裸金属、对象存储、域名、SSL 几条产品线的端点都摸了一遍。最大的坑不在认证，而在一个所有列表接口都强制要求、却很容易传错的 options 参数。这篇把实操经验记下来。
一、认证：一个 x-api-key 走天下
雨云 API 用 API Key 认证，没有复杂的 OAuth 签名流程。
- 获取位置：雨云后台 → 账户设置 → API 密钥
- Base URL：
https://api.v2.rainyun.com - 请求头带上：
x-api-key: 你的密钥
Content-Type: application/json
返回统一是 {"code": 200, "data": ...} 结构，code 不是 200 就是失败。实测踩过的错误码：
| code | 含义 |
|---|---|
| 30002 | 需要登录（请求没带 key） |
| 30039 | 密钥错误或已失效 |
| 10002 | 参数无效 |
| 10006 | 过滤器格式错误（options 的 JSON 不对） |
密钥这种东西不要写进代码或脚本仓库，存到环境变量文件里、权限收紧到 600。
二、最大的坑：options 参数必填
所有列表/分页接口都要求一个 query 参数 options，它的值是一个 JSON 字符串，而且必须做 URL encode。标准结构长这样：
{"columnFilters":{},"sort":[],"page":1,"perPage":20}
刚开始我手拼 URL，要么忘了 encode 导致花括号和引号被转义出问题（返回 10006），要么干脆没传这个参数。最稳的写法是用 curl 的 -G --data-urlencode，让 curl 帮你编码：
. /opt/data/.env
curl -sS -G \
-H "x-api-key: $RAINYUN_API_KEY" \
'https://api.v2.rainyun.com/product/rcs/' \
--data-urlencode 'options={"columnFilters":{},"sort":[],"page":1,"perPage":20}'
分页返回的结构是：
{"data": {"TotalRecords": 100, "Records": [ ... ]}}
翻页就是改 options 里的 page，每页条数改 perPage。columnFilters 做过滤、sort 做排序，结构对齐后基本通用。
三、产品线 → API 前缀地图
雨云把不同产品拆成了不同前缀，摸清前缀之后，端点命名相当规整。
| 产品 | 前缀 | 端点数 | 典型操作 |
|---|---|---|---|
| RCS 云服务器 | /product/rcs/ |
53 | 开关机/重启、changeos 重装、renew 续费、upgrade 升降配、vnc、重置密码、free 释放、防火墙、弹性 IP、NAT、备份、流量、监控 |
| RGS 游戏云 | /product/rgs/ |
76 | 同 RCS，外加 MCSM 面板、翼龙面板用户、帕鲁配置、egg 切换、日付模式、CPU 计费、弹性伸缩 |
| RBM 裸金属 | /product/rbm |
24 | poweron/off、changeos、KVM、rescue 救援、IPMI 重置密码、弹性 IP、BIOS 刷写、清点 |
| ROS 对象存储 | /product/ros/ |
36 | bucket/instance 增删改查、重新生成密钥、生命周期、离线下载、主动同步、访问日志、公开访问开关 |
| 域名 | /product/domain/ |
38 | 注册、续费、过户、DNS 解析、DNSSEC、NS 管理、免费二级域名、whois、模板 |
| SSL 证书 | /product/sslcenter/ |
21 | 下单、申请、验证、续期、吊销、上传/替换 |
可以看到命名高度一致：开机是 poweron、重装是 changeos、续费是 renew……记住一个产品的套路，其他产品能直接套用。
四、危险操作要收口
下面这些操作要么不可逆、要么直接扣费，做自动化时必须单独拦截、拿到明确确认再执行：
POST **/free：释放实例，数据全删POST **/renew：续费，扣费POST /product/domain/register：注册域名，扣费POST **/scale、/upgrade：升降配，可能补差价POST **/cert/.../revoke：吊销证书
我的做法是把这些端点列进脚本的"危险清单"，默认只做查询，写操作必须显式传确认参数。
五、查端点别靠猜
雨云官方有一个很好用的东西：OpenAPI spec 直接可下载。
- 文档站：https://api.rainyun.com/（SPA）
- OpenAPI spec：
https://api.rainyun.com/openapi.json
我把 spec 拉到本地缓存，需要某个操作的确切参数时直接读 JSON，比在文档页面里翻快得多，也避免凭名字猜参数。当前这份 spec 是 v2.4，覆盖 215 个路径，六条产品线全在里面。
小结
雨云 API 的整体体验是规整的：统一认证头、统一返回结构、产品线前缀 + 动词化端点。真正要注意的就两点——列表接口的 options 是必填 JSON 字符串，用 --data-urlencode 传；释放/续费/注册类端点会删数据或扣钱，自动化里要单独收口。剩下的交给那份 openapi.json 就行。