跳到主要内容

HTTP 调用参考与错误排查

请优先使用 API 服务 文档与测试 中生成的地址。以下示例的服务编码为 erp,请将主机、数据集 ID、字段路径和值替换为实际配置。

路径与方法​

示例基础路径为 /api/data/erp。

操作方法基础路径后的内容
通过 URL 参数查询GET/{datasetId}
通过 JSON 参数查询POST/{datasetId}
新增一条记录POST/{datasetId}/records
更新全部已授权可写字段PUT/{datasetId}
更新部分已授权字段PATCH/{datasetId}
删除一条记录DELETE/{datasetId}
读取已授权的数据集元数据GET/_schema
读取一个数据集的元数据GET/_schema/{datasetId}
读取当前角色的 OpenAPI 文档GET/_openapi

方法与路径共同确定操作。GET、POST 查询使用同一资源地址,POST 可在请求体中传递复杂 JSON;新增使用 /records,与 POST 查询区分。更新和删除通过 JSON 请求体提供完整记录主键,支持复合主键。

请求头​

每次请求都需要发送 X-API-Key。JSON 请求体还需发送 Content-Type: application/json。

export SOLN_API_KEY='replace-with-your-key'
curl 'https://runtime.example/api/data/erp/DATASET_ID?limit=20' \
-H "X-API-Key: $SOLN_API_KEY"

查询参数​

参数含义
fields已授权字段的完整路径;GET 使用逗号分隔,POST 使用数组。不填则返回角色授权的全部字段,最多 4096 个
filterGET 使用过滤表达式或 JSON,POST 使用结构化条件对象
order / sortGET 使用 order=account.name asc;POST 使用 sort: [{field, direction}],最多 5 个排序字段
limit每页 1~200 行,默认 50 行
cursor上一页响应返回的游标
direction下一页用 forward,上一页用 backward
timeoutMs查询超时,1000~15000 毫秒,默认 8000 毫秒
includeColumns是否在 meta.columns 中返回已授权的字段定义,默认 false
curl -X POST 'https://runtime.example/api/data/erp/DATASET_ID' \
-H "X-API-Key: $SOLN_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"fields":["account.name"],"filter":{"field":"account.active","op":"eq","value":true},"sort":[{"field":"account.name","direction":"asc"}],"limit":20}'

POST 查询通过 JSON 请求体传参,不同时使用 URL 查询参数。不要提交 SQL、数据库凭据、服务/角色替换参数或其他数据源。

过滤运算符包括 eq、ne、gt、gte、lt、lte、in、notIn、contains、notContains、startsWith、endsWith、isNull 和 isNotNull。通过 logic: "and" 或 logic: "or" 与 conditions 数组组合条件,最多支持 5 层嵌套分组、50 个叶子条件。

分页​

查询下一页时,将 meta.nextCursor 作为 cursor 传入。查询上一页时,传入 meta.previousCursor 并设置 direction=backward。字段、过滤、排序和每页行数保持不变。

每次遍历最多读取 10,000 行。traversalLimitReached 为 true 时,需要缩小过滤范围并开始新的遍历。分页读取实时来源数据,不是冻结的跨请求数据快照。

数据集或授权变更可能使旧游标失效,处理变更后需要移除旧游标重新开始。每页响应上限为 4 MiB,每个单元格最多 16,384 个字符。

字段路径与返回值​

选择字段时使用 account.name 这样的完整路径。响应按表单 API 名称组织;物理表则使用表名。

{
"resource": [
{
"account": {
"name": "示例客户",
"credit": "500000.0000000000",
"owner": {"_value": "MEMBER_ID", "name": "Alex"}
},
"computed": {"score": "12"}
}
],
"meta": {"hasMore": false, "nextCursor": null, "limit": 20}
}

有可识别的关联字段时,关联表单会放在该字段编码下。_value 用于在返回子字段的同时保留已授权的关联原值或 JSON/XML 父字段值。具体路径以生成的结构文档为准,不一定与数据集内部的 t0、t1 别名相同。

数据库数值字段和数值子字段以字符串返回,以保留精度;布尔值返回 JSON 布尔值。JSON 父字段解析为 JSON 值,XML 父字段仍返回 XML 字符串。空值返回 null,无效 JSON 父字段也返回 null。

单条记录写入​

更新请求通过 key 提供所有主键字段,通过 values 提供要修改的字段:

{
"key": {"account.id": "RECORD_ID"},
"values": {"account.name": "修改后的名称"}
}

PATCH 可只提交部分已授权可写字段,PUT 必须提交全部已授权可写字段。DELETE 只提交 key,不能包含 values。

新增请求包含 values,使用 POST 发送到 /{datasetId}/records。新增成功返回 HTTP 201 及生成或提交的主键,其他写入成功返回 HTTP 200、记录主键和影响行数。

开启写入前,请查看写入条件与授权。

错误响应​

{"error":{"code":"DATA_CONNECT_API_STRUCTURE_CHANGED"},"requestId":"REQUEST_ID"}
HTTP 状态常见原因处理方式
400字段、请求体、过滤条件或游标无效检查生成的接口定义和提交值
401Key 无效、过期、停用或已轮换检查 Key 及当前状态
403缺少授权、不满足数据范围、角色/服务停用,或执行中权限变化检查角色绑定、数据范围和数据库权限
404资源或记录不存在,或写入目标不在范围内确认资源、主键和数据范围
405路径不支持该方法使用文档规定的方法和路径
409结构、游标、约束或授权冲突查看日志,按需修复配置,再重新发起请求
413 / 415请求体过大或内容类型错误减少 JSON 请求体,或使用 application/json
429超过 Key 速率限制或租户查询容量遵守 Retry-After 并降低并发
502 / 504来源查询、连接失败或超时检查原始错误、数据库和超时设置
503写入提交结果未知先核对实际记录,再决定是否重试

DATA_CONNECT_API_STRUCTURE_CHANGED 表示当前数据集与读取授权规则无法一起使用。请在 调用日志 → 详情 查看原始原因,核对来源结构、字段路径、类型和剩余过滤条件。常规数据集修改会自动同步授权;不兼容的数据库变更或失效的过滤条件仍需修复。

日期值必须是 YYYY-MM-DD 格式的真实日历日期。日期时间还会校验月份天数、闰年、时分秒及 UTC 偏移;不存在的日期或时间会在查询或写入数据库前被拒绝。