配置 WPS 多维表格 数据源
WPS 多维表格数据源用于通过离线同步读取 WPS 多维表格中的数据,并写入平台预置仓。本文介绍 WPS 端的应用授权、数据源配置、同步方案创建和任务流挂载。
使用限制与准备事项
开始配置前,请确认以下限制和前置条件:
- WPS 多维表格仅支持作为数据来源,数据去向为平台预置仓,不支持回写 WPS 多维表格。
- 需准备 WPS 企业账号,并由有权限的人员创建企业自建应用、申请接口权限及提交版本审核。请联系企业管理员确认企业已具备所需的开放能力权益。
- 需准备目标 WPS 多维表格的文档链接,确认应用具备文件读权限,并确定要读取的数据表和视图。
- 平台运行环境需能访问 WPS 开放平台。若应用启用了 IP 白名单,请提前准备服务器实际出口 IP。
- 可读取的字段范围以所选数据表和视图为准,请先通过数据预览确认字段及内容。
| 环境配置方式 | 适用场景 | 配置要求 |
|---|---|---|
| 不区分环境 | 开发环境与生产环境共用一个 WPS 应用 | 填写一套 App ID、App Key 和接口签名设置 |
| 独立环境配置 | 开发环境与生产环境使用不同的 WPS 应用配置 | 分别配置;两套应用均需有权访问方案所选文档、数据表和视图 |
配置校验和数据预览使用开发环境配置,手动执行使用生产环境配置。独立环境配置下,请分别核对应用权限、文档读权限、接口签名和服务器出口 IP。
在 WPS 开放平台中完成授权
- 准备企业账号。登录 WPS 365,按页面提示创建企业,或联系企业管理员获取邀请并加入已有企业。随后使用同一账号登录 WPS 开发者后台,选择本次接入所属的企业。所需开放能力和权益由企业管理员向 WPS 确认。
- 创建企业自建应用。在开发者后台点击 创建应用,选择 企业自建应用,填写名称、描述等信息。创建后获取 App ID 和 App Key,交由接入负责人配置数据源。具体操作参见 创建企业自建应用。
- 申请读取权限并完成审核。在应用的 权限管理 中申请下表权限,选择 应用授权(app) 类型。随后创建应用版本并提交发布申请,由企业管理员审核通过后,权限才会生效。参见 配置应用能力信息。
| 功能名称 | 权限 scope | 权限类型 |
|---|---|---|
| 查询多维表格 | kso.dbsheet.read | 应用授权(app) |
- 准备文档读权限。由文档负责人核对目标多维表格的归属、访问范围和权限设置,确保应用有权读取文档。应用的接口权限与文件权限都需满足要求;个人能在浏览器中打开文档,不代表应用已经获得读取权限。文件读权限要求参见 WPS 多维表格读取说明。复制文档链接,供后续配置使用,例如
https://www.kdocs.cn/l/ExampleID。 - 配置安全设置。在应用的 安全设置 中,按企业安全要求配置 接口签名,并将状态告知接入负责人,确保 WPS 侧与数据源配置一致。若需启用 IP 白名单,请联系运维获取访问 WPS 的服务器实际出口 IP,并将所有需要的出口加入白名单。这里填写的是服务器出口 IP,而非操作人员电脑的 IP;多个环境或节点出口不同时,需要分别配置。参见 WPS 调用流程与安全配置。
请妥善保管 App Key,通过安全方式交接,避免在截图、日志或公开文档中暴露。修改已接入应用的接口签名或 IP 白名单前,请先与接入负责人确认,避免影响现有同步任务。
创建 WPS 多维表格数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 WPS 多维表格,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需要分别完成开发环境和生产环境的配置。
- 填写应用的 App ID、App Key,并根据 WPS 应用的安全设置配置 接口签名。
- 在 连通性测试 中点击 测试,确认应用认证通过后,点击 完成。
| 配置项 | 说明 |
|---|---|
| App ID | WPS 企业自建应用的 App ID |
| App Key | 对应应用的 App Key |
| 接口签名 | 与 WPS 应用的接口签名设置保持一致;按企业安全要求配置 |
连通性测试仅验证应用认证。文档访问权限和接口签名还需通过下一节的加载数据或数据预览验证。测试通过后,请继续完成来源配置与预览。
编辑已保存的数据源时,App Key 默认脱敏显示。如需更换凭证,请填写新的 App Key,重新测试连接,并验证文档访问。
创建离线同步方案
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 WPS 多维表格 及已创建的数据源。
- 在 WPS 多维表格 URL 中填写文档链接,例如
https://www.kdocs.cn/l/ExampleID,点击 检验 URL。 - URL 检验并加载成功后,选择要读取的 数据表,再选择其中的 视图。
- 点击 数据预览,核对字段和数据内容,确认当前应用能够读取所选文档。
请填写 WPS 多维表格的 HTTPS 文档链接。切换数据源、修改 URL 或切换数据表后,请重新核对数据表、视图和字段映射;切换数据表后需要重新选择视图。
如果找不到数据表、视图或无法预览,请先检查应用读取权限是否已审核生效、文档读权限以及接口签名和 IP 白名单设置。独立环境配置下,本步骤使用开发环境配置;生产环境也必须能够读取同一方案所选内容。
字段映射与同步验证
完成数据来源配置后,选择平台预置仓中的目标表,并建立字段映射。来源字段优先显示 WPS 中的字段名称。
支持的字段类型
WPS 多维表格支持读取所选视图中可见字段的内容,包括文本、数字、布尔值,以及接口返回的数组和对象内容。日期、时间及公式等字段也应通过数据预览确认实际返回内容,不能仅根据字段名称或 WPS 中的显示形式判断读取结果。
来源字段统一显示为字符串(string),不代表仅支持 WPS 的文本字段。
不支持的字段与限制
字段被删除、被所选视图隐藏,或当前应用没有读取权限时,不能继续按原字段配置同步。请刷新来源配置并重新确认字段范围。
配置与验证
- 在 数据去向 中选择或创建目标表,并按业务需要设置写入方式。
- 在 字段映射 中将来源字段映射到目标字段。
- 填写方案名称、负责人和备注后保存。
- 点击 手动执行,在执行记录中确认任务成功,再到目标表核对字段与数据内容。手动执行使用生产环境配置,请提前检查生产应用的凭证和权限。
图中字段仅用于展示映射界面,请根据实际业务选择需要同步的字段。
WPS 数据表、视图或字段发生变化后,请刷新来源配置和字段映射,确认所选视图及映射字段仍有效。字段被删除或隐藏时,需要重新核对映射后再保存、执行。
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 核对 App ID、App Key 是否正确、应用状态是否正常 |
| 连通性测试通过,但无法加载数据或预览 | 核对 kso.dbsheet.read 是否为应用授权类型且已审核生效、应用是否具有文档读权限,以及接口签名与 IP 白名单配置 |
| URL 检验失败 | 使用标准的 WPS 多维表格 HTTPS 文档链接,确认文档仍存在且应用有权读取 |
| 找不到数据表或视图 | 确认选项未被删除,刷新列表并重新选择;切换数据表后重新选择视图 |
| 提示映射字段已删除或隐藏 | 检查 WPS 端字段与视图设置,刷新字段映射并重新核对 |
| 开发环境预览正常,但手动执行失败 | 核对生产环境的应用凭证、文档权限、接口签名和服务器出口 IP |
| 同步后的字段内容不符合预期 | 核对来源数据预览及字段对应关系,调整后重新验证 |
挂载到任务流
手动验证成功后,可将离线同步方案挂载到任务流,按调度周期自动执行。
- 打开已保存的离线同步方案,点击 挂载到任务流。
- 选择目标任务流。
- 填写节点名,选择执行模式,并按需设置负责人和备注。节点类型和集成方案会自动带出。
- 点击 创建节点并挂载。挂载成功后,可点击 前往任务流 检查节点位置和上下游依赖。
- 保存任务流并完成发布;生产调度将使用生产环境的数据源配置。
如需更换同步方案或数据源,请先评估现有任务流依赖,并在修改后重新执行验证。

