Skip to main content

导入可信设备接口

通过 CSV 或 XLSX 文件批量导入可信设备，单个文件最大 10 MiB、1000 行。请求需携带 Idempotency-Key 避免重复导入。

  • Scope: admin.v1.trusted-devices.manage
  • 权限项: 可信设备管理
  • 权限类型: manage
  • 接口: POST/api/openapi/v1/trusted-devices/imports
使用 Authorization: Bearer <API_KEY>。应用必须配置“全部用户”范围（subject_scope={"mode":"all"}）；受限或无效范围在业务执行前返回 403 openapi_subject_scope_denied。各 Scope 独立授权，互不隐含。组织及应用操作主体取自可信鉴权，不接受请求参数指定。 支持 CSV/XLSX，最大 10 MiB、1,000 数据行，至少填写 SN 或 MAC；沿用现有用户标识解析、冲突校验和逐行成功/失败结果。

请求参数

名称位置类型必填说明
Idempotency-KeyheaderstringTrue幂等键，创建和导入必填
filebodystringTrueCSV 或 XLSX 文件，最大 10 MiB、1,000 行

请求示例

curl --request POST 'https://example.invalid/api/openapi/v1/trusted-devices/imports' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: device-operation-001' \
  --form 'file=@devices.xlsx'

响应字段

名称类型说明
failed_rowsinteger失败行数
rowsarray逐行导入结果
rows[].device_idstring设备标识
rows[].reasonstring申请或任务原因
rows[].row_numberinteger文件原始行号
rows[].successboolean该行是否成功
success_rowsinteger成功行数
total_rowsinteger导入总行数

错误处理

沿用 {error, detail, code} 错误结构。身份校验失败为 401/403；缺少 Scope 或非全部用户范围为 403；资源不存在为 404；冲突或旧版本为 409；参数不合法为 400/422；依赖不可用为 503。业务错误沿用控制台语义。

接口语义与安全边界

文件安全边界：上传仍最多 10 MiB、1,000 数据行；XLSX 解压后总量最多 64 MiB，工作表及共享字符串 XML 超过 8 MiB 时由解析库使用临时文件。这是文件解析防护，不改变用户解析、信任状态和逐行结果规则。超限或无法解析返回 422。解析库固定到经安全修复的提交版本；不执行工作簿公式。