APITable 内部服务节点接口 InternalServiceNodeInterfaceApi 实战指南表格节点创建、删除与过滤查询【免费下载链接】apitable APITable, an API-oriented low-code platform for building collaborative apps and better than all other Airtable open-source alternatives.项目地址: https://gitcode.com/apitable/apitable本指南聚焦 APITable 开源仓库中packages/api-client客户端包提供的内部服务节点接口InternalServiceNodeInterfaceApi它面向服务端内部集成场景封装了三个底层能力创建数据表节点createDatasheet、删除节点deleteNode以及按类型、权限和名称过滤查询节点filter。读完本文你将掌握这三个接口的 HTTP 语义、TypeScript 客户端调用方式、参数细节、返回结构以及它们在 Java 后端InternalNodeController中的实现原理与权限校验逻辑可直接用于二次开发与内部系统对接。接口总览与定位InternalServiceNodeInterfaceApi属于 APITable 的Internal内部服务接口族前缀internal表示这些接口面向服务端内部调用场景而非对外公开的终端用户 API。当前仓库中的 API 文档InternalServiceNodeInterfaceApi.md与生成代码InternalServiceNodeInterfaceApi.ts均由 OpenAPI Generator 根据后端 OpenAPI 定义自动生成因此接口签名、路径与后端 Controller 一一对应。所有请求的基准地址Base URL为http://backend/api/v1而客户端默认服务器地址在 servers.ts 中定义为http://127.0.0.1:8081/api/v1本地开发默认后端端口。接口汇总表如下方法HTTP 请求描述createDatasheetPOST/internal/spaces/{spaceId}/datasheets创建数据表节点deleteNodePOST/internal/spaces/{spaceId}/nodes/{nodeId}/delete删除节点filterGET/internal/spaces/{spaceId}/nodes按类型、权限和节点名称过滤查询节点三个接口都无需额外的 Authorization 认证头No authorization required其身份与权限判定发生在后端会话Session层面。后端对应实现位于 InternalNodeController.java类上标注了ApiResource(path /internal)即所有路径都以/internal为前缀。环境准备构建并使用 API 客户端InternalServiceNodeInterfaceApi的 TypeScript 客户端由apitable/api-client包提供package.json依赖whatwg-fetch、es6-promise、url-parse基于 fetch 实现 HTTP 调用。使用方式如下# 在 packages/api-client 目录下安装依赖并编译 TypeScript 产物 npm install npm run build编译产物输出到dist/目录main: ./dist/index.js。在消费项目中安装npm install apitable/api-client0.0.1 --save客户端采用“配置对象 API 实例”的调用模型。创建配置的核心逻辑在 configuration.tsimport { createConfiguration, InternalServiceNodeInterfaceApi, } from apitable/api-client; const configuration createConfiguration({ // 默认 baseServer 即 http://127.0.0.1:8081/api/v1 // 如需修改可传入自定义 baseServer baseServer: ..., // 可通过 promiseMiddleware 在请求前后做统一拦截、加日志或注入会话凭证 promiseMiddleware: [...], }); const apiInstance new InternalServiceNodeInterfaceApi(configuration);createConfiguration的默认值包括baseServer使用server1、HTTP 库使用IsomorphicFetchHttpLibrary、中间件为空、认证方法为空。若你的内部服务运行在与前端不同的主机上请通过自定义baseServerServerConfiguration见 servers.ts指向实际的后端地址。创建数据表节点createDatasheet请求语义createDatasheet在指定空间spaceId下创建一个数据表Datasheet节点请求体为CreateDatasheetRo返回ResponseDataCreateDatasheetVo。Content-Type:application/jsonAccept:*/*状态码200成功、500服务端错误请求参数CreateDatasheetRo的字段定义在后端 CreateDatasheetRo.java 与客户端模型 CreateDatasheetRo.ts 中保持一致字段类型必填说明namestring是节点名称长度不能超过 100 字符后端校验Size(max 100)folderIdstring是父节点文件夹ID不能为空NotBlankpreNodeIdstring否目标位置的前一个节点 ID为空时新节点插入到首位descriptionstring否节点描述文本调用示例文档给出的 TypeScript 调用示例基于body参数形式import * as fs from fs; import { createConfiguration, InternalServiceNodeInterfaceApi, } from apitable/api-client; const configuration createConfiguration(); const apiInstance new InternalServiceNodeInterfaceApi(configuration); let body { // CreateDatasheetRo createDatasheetRo: { name: This is a node, folderId: nod10, preNodeId: nod10, description: This is a table, }, // 空间 ID spaceId: spaceId_example, }; apiInstance.createDatasheet(body).then((data: any) { console.log(API called successfully. Returned data: data); }).catch((error: any) console.error(error));生成的代码还提供了createDatasheetWithHttpInfo返回含状态码、响应头的HttpInfo与createDatasheet直接返回反序列化后的数据两种调用方式见 InternalServiceNodeInterfaceApi.ts 与 ObjectParamAPI.ts。返回结构成功时返回ResponseDataCreateDatasheetVo通用响应包装success、code、message、data其中data为CreateDatasheetVo字段类型说明datasheetIdstring数据表 ID与nodeId相同即dst开头folderIdstring所属文件夹 IDpreNodeIdstring前一个节点 IDcreatedAtnumber创建时间戳毫秒nodeIdstring节点 IDparentIdstring父节点 ID后端实现与权限校验从源码看createDatasheet的完整处理链路为InternalNodeController.java通过SessionContext.getUserId()获取当前登录用户通过LoginContext.me().getMemberId(userId, spaceId)获取成员 ID该方法同时会校验用户是否属于该空间若请求未指定folderId则默认取空间根节点nodeService.getRootNodeIdBySpaceId(spaceId)通过controlTemplate.fetchNodeRole(memberId, parentId)校验父节点权限要求具备NodePermission.CREATE_NODE权限否则抛出NODE_OPERATION_DENIED调用nodeService.createDatasheetWithDesc(spaceId, userId, ro)创建节点。其中createDatasheetWithDesc的实现位于 NodeServiceImpl.java标注Transactional将CreateDatasheetRo转换为NodeOpRotranferToNodeOpRo()会固定设置type 2即数据表类型见 CreateDatasheetRo.java调用createNode创建节点实体若description非空则额外插入一条NodeDescEntity描述记录。创建成功后Controller 还会通过Notification(templateId NotificationTemplateId.NODE_CREATE)触发节点创建通知。删除节点deleteNode请求语义deleteNode删除指定空间spaceId下的节点nodeIdPOST/internal/spaces/{spaceId}/nodes/{nodeId}/deleteContent-Type: Not defined无请求体Accept:*/*状态码200成功、500服务端错误请求参数参数类型必填说明spaceIdstring是空间 IDnodeIdstring是待删除节点 ID调用示例import { createConfiguration, InternalServiceNodeInterfaceApi, } from apitable/api-client; const configuration createConfiguration(); const apiInstance new InternalServiceNodeInterfaceApi(configuration); let body { spaceId: spaceId_example, nodeId: nodeId_example, }; apiInstance.deleteNode(body).then((data: any) { console.log(API called successfully. Returned data: data); }).catch((error: any) console.error(error));成功时返回ResponseDataVoid仅包含success/code/messagedata为空。后端实现与权限校验删除逻辑位于 InternalNodeController.java关键步骤获取当前用户成员 ID 并校验其属于该空间通过controlTemplate.checkNodePermission(memberId, nodeId, NodePermission.REMOVE_NODE, ...)校验删除权限无权限则抛出NODE_OPERATION_DENIED根节点不可删除校验nodeId不等于空间根节点 IDgetRootNodeIdBySpaceId调用nodeService.deleteById(spaceId, memberId, nodeId)执行删除删除成功后调用spaceCapacityCacheService.del(spaceId)清理该空间容量缓存保证空间容量统计及时刷新。同样地该方法带有Notification(templateId NotificationTemplateId.NODE_DELETE)通知注解。过滤查询节点filter请求语义filter接口用于按节点类型、节点权限、节点名称关键词过滤查询空间内的节点官方场景描述为“查询一个已存在的只读仪表板”scenario: query an existing read-only dashboard适合需要按条件筛选节点列表的内部集成场景GET/internal/spaces/{spaceId}/nodesContent-Type: Not definedAccept:*/*状态码200成功、500服务端错误请求参数参数类型必填说明spaceIdstring是空间 ID路径参数typenumber是节点类型查询参数nodePermissionsArraynumber否节点权限过滤查询参数默认[0,1,2,3]keywordstring否节点名称关键词默认type节点类型取值对应后端 NodeType.java 与客户端模型 NodeInfo.ts 的注释值类型说明0ROOT根节点1FOLDER文件夹2FILE / DATASHEET数据表nodePermissions权限取值对应后端 NodePermissionEnum.java值权限后端角色映射0MANAGER管理员Node.MANAGER1EDITOR可编辑Node.EDITOR2UPDATE_ONLY仅可更新Node.UPDATER3READ_ONLY只读Node.READER权限与角色的映射关系见 NodeRoleServiceImpl.java 的getMinimumRequiredRole方法。调用示例import { createConfiguration, InternalServiceNodeInterfaceApi, } from apitable/api-client; const configuration createConfiguration(); const apiInstance new InternalServiceNodeInterfaceApi(configuration); let body { spaceId: spaceId_example, // 节点类型1 文件夹、2 数据表等 type: 1, // 权限过滤可选 nodePermissions: [0, 1, 2, 3], // 名称关键词可选 keyword: , }; apiInstance.filter(body).then((data: any) { console.log(API called successfully. Returned data: data); }).catch((error: any) console.error(error));返回结构与权限过滤原理成功时返回ResponseDataListNodeInfodata为NodeInfo[]。NodeInfo的关键字段见 NodeInfo.ts字段类型说明nodeIdstring节点 IDnodeNamestring节点名称typenumber节点类型0 根节点 / 1 文件夹 / 2 数据表iconstring节点图标parentIdstring父节点 IDrolestring当前用户在该节点上的角色nodeFavoriteboolean是否收藏后端过滤逻辑InternalNodeController.java值得深入理解先通过nodeService.getNodeIdBySpaceIdAndTypeAndKeyword(spaceId, type, keyword)按空间、类型、关键词粗筛出候选节点 ID 列表SQL 实现见 NodeServiceImpl.java再通过controlTemplate.fetchNodeRole(memberId, nodeIds)批量获取当前成员在这些节点上的角色字典调用iNodeRoleService.getMinimumRequiredRole(nodePermissions)将传入的权限枚举值映射为后端角色并按角色高低排序只保留角色满足传入权限要求的节点过滤后如果为空直接返回空列表最后调用nodeService.getNodeInfo(spaceId, filterNodeIds, memberId)组装节点详情并把当前用户的角色标签写回每个NodeInfo.role字段。这意味着filter天然具备“仅返回调用者有权限访问的节点”的安全语义即使候选节点命中类型和关键词若当前成员没有匹配的角色也会被过滤掉。文档中“query an existing read-only dashboard”的场景即利用这一机制内部服务可列出当前用户只读可访问的仪表板节点集合。接口调用注意事项路径与权限前缀三个接口都属于/internal内部服务命名空间后端ApiResource(path /internal)统一管理虽然声明“无需 Authorization”但身份校验依赖已登录的会话上下文调用方需要保证会话有效性如通过网关透传 Cookie 或内部鉴权头。空间归属校验createDatasheet与deleteNode均通过LoginContext.me().getMemberId(userId, spaceId)强制校验用户属于该空间跨空间操作会被拒绝。根节点保护deleteNode明确禁止删除空间根节点内部服务在批量清理节点时需先排除根节点。权限过滤语义filter的nodePermissions是“最低要求”语义——返回的节点角色不低于传入的权限级别例如传入[0]只返回具备管理员角色的节点这一点从getMinimumRequiredRole与parseAndSortNodeRole的排序比较逻辑可以看出。默认值nodePermissions默认0,1,2,3即不过滤权限、keyword默认空字符串后端通过RequestParam(defaultValue ...)设置客户端调用时可省略。小结InternalServiceNodeInterfaceApi是 APITable 后端工作台Workbench节点体系对内暴露的轻量服务接口createDatasheet承担“建表”入口deleteNode承担“删节点”入口filter承担“按条件筛选可访问节点”的能力。三者共享同一套节点权限控制模板ControlTemplate与节点服务INodeService因此在内部系统如自动化机器人、模板中心、运营后台集成时可以直接复用这套接口获得与工作台一致的角色权限语义。本文涉及的客户端实现见 packages/api-client后端实现见 InternalNodeController.java更多相关模型CreateDatasheetRo、CreateDatasheetVo、NodeInfo等均可在这两个目录下继续查阅。【免费下载链接】apitable APITable, an API-oriented low-code platform for building collaborative apps and better than all other Airtable open-source alternatives.项目地址: https://gitcode.com/apitable/apitable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考