跳到主要内容

API 服务与授权

API 服务通过带身份验证的 HTTP 请求开放已保存的数据集。在 数据连接 → API 调用 中管理服务、API 角色、Key、文档与调用日志。

创建服务​

  1. 新建 API 服务,选择数据源。
  2. 填写名称、稳定的服务编码和可选描述。
  3. 启用服务并保存。
  4. 在资源列表中查看该数据源下已保存的数据集。

一个数据源可创建一个 API 服务。服务编码是 URL 的一部分,创建后不可修改。创建服务不会自动创建角色或发放 Key。

创建角色并绑定数据集​

  1. 在 API 角色 中新建角色。
  2. 填写名称和可选描述。
  3. 从带分页的列表中勾选一个或多个数据集。
  4. 按需配置每个已选数据集的 字段、数据范围 和 写入权限。
  5. 保存。

新绑定的数据集默认授权全部可用字段,只允许查询。新增、更新和删除需要单独授权。一个角色可绑定多个数据集,同一数据集也可被多个角色绑定并设置不同权限。没有绑定数据集的角色不具备数据集访问权限。

API 角色独立于内部成员角色。API 客户端使用所绑定的 API 角色,不继承登录成员的权限。

发放与维护 API Key​

创建 API Key 时,在服务内选择一个角色,配置名称、启用状态、可选的有效期及速率限制。

完整密钥仅在创建或轮换时显示。请复制到调用应用的受保护配置中。后续列表只显示密钥前缀,不显示完整内容。

请求通过 X-API-Key 请求头传递密钥。轮换后旧密钥失效;停用 Key、角色或服务都会阻止继续调用。角色被 Key 使用时,需要先更换绑定角色或移除 Key,才能删除角色。

字段和数据范围权限​

为每个数据集选择可读字段,配置固定数据范围。客户端过滤条件会与角色范围同时生效,不能扩大角色范围。纯应用 API 调用不支持成员、部门变量。

客户地址等文档字段在字段权限弹窗中按一个字段展示。API 元数据和字段选择器仍可展示已配置的 JSON/XML 子字段。只授权某个子字段,不代表授权整个父文档或其他子字段。

数据集变更与授权​

API 使用最新保存的数据集,保存后生效,无需额外检查与发布。

数据集变更角色绑定的处理方式
名称、描述、字段显示名称或字段顺序保留已有授权
新增字段自动添加读取权限,不增加写入权限
删除字段移除该字段的读取、写入、新增授权及相关数据范围条件,其他字段继续可用
同一字段修改类型、表达式、脚本来源或取值来源保留该字段授权
修改主来源、关联来源、关联方式或关联条件重置受影响的绑定:全部可用字段、仅查询、无固定数据范围
删除数据集从所有受影响角色中删除该数据集绑定

删除的字段用于嵌套数据范围时,对应条件和空分组也会移除。如果没有剩余条件,该绑定不再限制固定数据范围。此类修改后请检查最终可访问范围。

授权保留不代表旧过滤值或响应解析程序一定适用于新的字段类型。数据接口发生变化时,调用应用也需要相应调整。

写入权限​

写入仅适用于基于一张物理数据库表、具有可用主键的数据集。表单模型、视图和带关联的数据集不支持通过这些 API 写入。

需要明确授权方法和字段,数据库账号也必须具备对应权限。完整主键包含的所有字段都需要可读。

  • POST /records:新增一条记录并返回主键。需要提供必填值,数据库自动生成的字段无需提交。
  • PATCH:按完整主键更新部分已授权字段。
  • PUT:需要提供角色获准写入的全部字段,不替换未授权列或主键。
  • DELETE:按完整主键删除一条记录。

写入受固定数据范围约束,新增和更新后的记录也必须满足范围。不提供批量写入。测试中执行写入会修改真实来源数据库。

文档与测试​

打开 文档与测试,选择角色、数据集及用于测试的有效 API Key。配置过滤、排序、行数限制,以及是否返回字段元数据。

文档按调用方法展示请求、授权要求、示例和响应。可以复制、测试请求,或下载生成的 Word 文档。HTTP 调用参考介绍通用参数和嵌套响应路径。

调用日志与原始错误​

打开 调用日志,按关键词、HTTP 状态或时间筛选。查看详情可了解 API Key 名称、数据集、结果、行数、耗时、错误码和原始错误链。

请求详情还显示 HTTP 方法、Runtime 解析的 URL、请求 ID、连接 IP,以及转发、Host、User-Agent 和内容相关请求头。连接 IP 为 socket 对端地址;转发头是申报值,不能直接当作已验证的客户端身份。关键词还可匹配请求方法、URL、请求 ID 与连接 IP。凭据和敏感查询参数值会脱敏,不记录请求正文。

这些日志也会出现在 系统日志 → 数据连接 API 和 数据清理 → 日志。清理按创建时间筛选,保留服务、角色、密钥、授权与数据集。

错误码展示时会去掉下划线、使用小写。例如,DATA_CONNECT_API_STRUCTURE_CHANGED 显示为 data connect api structure changed。供程序处理的错误响应保留原始错误码。

原始错误可帮助定位数据库或规则校验问题。错误详情不附带 SQL、行数据转储,并会遮蔽可识别的凭据。开始记录错误详情之前的旧日志可能没有原始错误。已建立调用身份的请求才会进入此列表,身份验证阶段失败的请求不在其中。调用日志保留 30 天。