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 个 |
filter | GET 使用过滤表达式或 JSON,POST 使用结构化条件对象 |
order / sort | GET 使用 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 | 字段、请求体、过滤条件或游标无效 | 检查生成的接口定义和提交值 |
| 401 | Key 无效、过期、停用或已轮换 | 检查 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 偏移;不存在的日期或时间会在查询或写入数据库前被拒绝。