跳到主要内容

HAP 平台 API 概览

API（Application Programming Interface，应用程序编程接口）是一组预先定义的接口。开发者可以按照约定的请求方式调用接口，获取或操作平台中的数据，而无需了解系统内部实现。

平台目前提供两类 API：组织相关接口 与 应用接口。

组织相关的接口​

组织相关接口用于获取和操作组织层面的数据，包括人员、部门、汇报关系、日志、待办等。

操作路径：进入【组织管理】 > 【集成】 > 【其他】 > 【开放接口】，可查看组织密钥(AppKey、SecretKey)和接口文档。

  • 组织授权开放接口文档地址(SaaS)：https://apidoc.mingdao.com

  • 私有部署：组织管理员按上述路径进入文档，调试地址将自动显示为私有部署域名。

应用接口​

应用接口用于获取或操作单个应用内的数据和配置，例如工作表、行记录、视图、工作流、角色、统计图等。

文档入口​

操作入口：点击应用名称右侧按钮，然后点选「API开发文档」。

应用授权​

调用应用接口前，需要先创建应用授权。进入【授权管理】页面，点击【新建授权密钥】即可创建。

一个应用可以创建多个授权密钥。每个授权密钥包含 AppKey、Sign 和接口权限范围，可用于不同系统或不同业务场景下的接口调用。

API V2 和 API V3​

应用接口有API V2 和 API V3两个版本。

  • API V2

    API V2 会基于当前应用和工作表自动生成可直接调用的接口。接口请求示例中会自动写入 appKey、Sign、worksheetId 等参数，适合快速查看当前应用下具体工作表的接口调用方式。

  • API V3

    API V3 在 V2 基础上重构了整体 API 路径，参数命名更友好，也更便于 AI 识别和调用。同时，V3 提供了更多接口能力，例如新建、编辑、删除工作表，调用工作流，工作表数据聚合，以及公共查询接口（查询人员、部门等）。

    API V3 采用统一接口规范，不同应用使用相同的接口路径和参数结构。开发者可直接参考 API V3 接口文档：https://apidoc.mingdao.com/application

字段和视图对照表​

在应用 API 开发文档中，每个工作表下都会展示字段对照表和视图对照表，便于开发者获取字段 ID、视图 ID 等接口调用所需参数。

  • 字段对照表包括：字段ID、字段名称、类型、控件类型编号、说明。

  • 视图对照表包括：视图ID、视图名称、类型

接口分享和调试​

在接口文档右上角，可以对接口进行调试和分享。

  • API V3接口可直接分享地址：https://apidoc.mingdao.com/application

  • API V2接口分享

    • 在分享的API接口页面中，所有有关密钥信息不会显示，用到密钥信息的示例中会展示为YOUR_APP_KEY、YOUR_SIGN。

    • 分享时可以设置链接有效期和密码访问

筛选条件生成器​

筛选条件生成器用于通过可视化配置生成筛选代码，帮助开发者快速构造接口查询条件。

操作路径：进入应用 API 开发文档，依次选择 【应用授权】 > 【工作表】 > 目标工作表 > 【字段对照表】 > 【筛选条件生成器】

API调用限流与限制​

目前仅按同一IP限制调用频率，不按应用或用户维度限流。超过调用频率或请求体大小限制的请求将被拒绝。

接口单个IP的QPS（每秒请求数）请求体大小限制
新建行记录（addRow）5016MB
批量新增行记录（addRows）5016MB
编辑行记录（editRow）5016MB
批量编辑行记录（editRows）5016MB
删除行记录（deleteRow）5016MB
获取记录数量（getFilterRowsTotalNum）50/
获取记录列表（getFilterRows）50/
其他接口不限制/
私有部署不限制25MB
⚠️⚠️⚠️

1.同一个IP超过调用频率限制，API网关层返回HTTP状态码 503：同时返回结构：{"error_code":90001,"success":false,"error_msg":"调用接口超出限制"}.

如果遇到这个错误，可以考虑以下方法：

  • 为了业务健壮性，加入针对此类错误码的处理，可以加入重试机制
  • 可以在请求里面加入时间间隔，特别是循环请求体里面，如Sleep(200ms)

2.超过请求体大小的限制，将直接拒绝服务，API网关层返回HTTP状态码 413：Request Entity Too Large.

如果您需要处理更大的数据负载，可以考虑以下方法：

  • 数据拆分：​将大的数据集拆分成多个较小的部分，分别发送
  • 优化数据结构：​移除不必要的字段，压缩数据结构，以减少请求体的大小

这篇文档对你有帮助吗？