用 API Key 调用接口

这一页帮你建一把 API Key，并用它从脚本里调用 nSIM。不要把登录口令交给脚本或 AI，给它们一把只带必要权限、随时能吊销的 API Key。

开始之前

• 想清楚这把 Key 要做什么，对照API 权限范围挑出需要的权限。
• 有一个能发 HTTP 请求的工具，下面的例子用 curl。

建一把 API Key

1. 打开「设置 › API 与监控」，点「新建 API Key」。
2. 在「名称」里填一个认得出用途的名字，例如 backup-script。审计日志用这个名字标明是哪把 Key 做的事。
3. 可选：在「有效天数」里填天数。留空表示不过期。
4. 在「权限」里展开要改的分组，勾选需要的权限。默认已勾选全部的「读」。用不到的「读」可以取消。
5. 点「创建」。页面显示新 Key 的明文，以 vpk_ 开头。
6. 点「复制」，把明文存好，再点「已保存」。

警告

明文只显示这一次。点了「已保存」或离开这一页后就再也看不到。丢了只能吊销后重建。

完成后，「API Key」列表里多出一行。行下写着 Key 的编号、它能做什么、最近使用时间和过期时间。

调用接口

把 Key 放在 X-API-Key 请求头里。下面的地址与 Key 都是占位值：

curl -fsS -H 'X-API-Key: vpk_xxxxxxxx.xxxxxxxx' \
     http://192.0.2.10:7575/api/devices

返回的是 JSON，业务数据在 data 字段里，出错时原因在 error 里。没有权限时返回 403，响应里写着需要哪个权限。

要查全部接口、参数和每个接口需要的权限，在「设置 › API 与监控」里点「API 文档」一行的「打开」。

调用会产生费用或不可撤销的接口

拨号、发短信、切换 eSIM、换 IP 这类接口，还要带两个请求头：

• X-NSIM-Confirm：填被操作对象的标识符，例如设备 ID。
• Idempotency-Key：每次操作生成一个新的唯一字符串，至少 8 个字符。

curl -fsS -X POST http://192.0.2.10:7575/api/devices/<设备ID>/actions/rotate-ip \
     -H 'X-API-Key: vpk_xxxxxxxx.xxxxxxxx' \
     -H 'X-NSIM-Confirm: <设备ID>' \
     -H "Idempotency-Key: $(uuidgen)"

哪些接口需要这两个头、填错时返回什么，见API 权限范围。

让 Prometheus 抓取指标

1. 按上面的步骤建一把 Key，只勾选「系统」的「读」。

2. 在 Prometheus 的配置里加一个抓取任务，用 X-API-Key 请求头带上这把 Key：

   scrape_configs:
     - job_name: nsim
       scheme: http
       metrics_path: /api/system/metrics
       http_headers:
         X-API-Key:
           values: ['vpk_xxxxxxxx.xxxxxxxx']
       static_configs:
         - targets: ['192.0.2.10:7575']

3. 重载 Prometheus。

警告

「监控指标」里「prometheus.yml」一行复制出的配置把 Key 放在 authorization 里。nSIM 目前只从 X-API-Key 头读取 API Key，照那份配置抓取会返回 401。按上面的写法改。http_headers 需要较新版本的 Prometheus。

完成后，在 Prometheus 的 Targets 页里，nsim 这个任务显示为 UP。想先看看有哪些指标，在「监控指标」的「当前指标」一行点「查看」。

吊销一把 Key

不再用或怀疑泄露时，在「API Key」列表里点那一行的「吊销 <名称>」按钮。在确认框里输入它的名字，再点「吊销 API Key」。用它的请求立即被拒绝，这一步不能撤销。