低代码后端前端协同办公【免费下载链接】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 官方 API 文档 BasicModuleAttachmentInterfaceApi.md 为主体系统讲解 APITable 基础模块附件接口服务端路径/base/attach的五个核心端点资源上传upload、图片 URL 上传urlUpload、空间附件引用计数变更cite、待人工审核图片分页查询readReviews与审核结果提交submitAuditResult。读完本文你将掌握每个接口的请求/响应模型、TypeScript SDK 调用方式、AssetType类型语义并能对照仓库源码AssetController.java理解其底层实现与适用场景。接口总览所有接口的相对地址基于http://backend/api/v1本组接口统一由后端控制器 AssetController.java 中的ApiResource(path /base/attach)声明暴露。客户端 SDK 对应类为BasicModuleAttachmentInterfaceApi实现位于 BasicModuleAttachmentInterfaceApi.ts。方法HTTP 请求说明citePOST/base/attach/cite空间附件资源引用数量变化同一附件需重复传 tokenreadReviewsGET/base/attach/readReviews分页查询需要人工审核的图片submitAuditResultPOST/base/attach/submitAuditResult提交图片审核结果提交时需填写审核人姓名uploadPOST/base/attach/upload上传资源文件不限制文件类型urlUploadPOST/base/attach/urlUpload图片 URL 上传接口所有端点均标注 No authorization required无需额外鉴权但源码层面readReviews与submitAuditResult会从会话中读取钉钉用户 IDSessionContext.getDingtalkUserId()并校验登录态upload在未登录时则会触发人机校验详见下文各节。1. cite —— 空间附件引用计数变更POST/base/attach/cite请求体为SpaceAssetOpRo返回ResponseDataVoid。当同一份附件需要被重复引用时例如表单匿名填写、多单元格引用同一文件调用本接口告诉服务端新增/删除了哪些附件引用从而保证空间附件表space_asset中的引用计数与实际使用一致。请求体模型SpaceAssetOpRo对应模型文件 SpaceAssetOpRo.ts包含三个字段字段类型是否必填说明addTokenArrayOpAssetRo否写入新增引用的 token 集合removeTokenArrayOpAssetRo否删除释放引用的 token 集合nodeIdstring是数据表Datasheet节点 Id示例dst10其中每个 token 项为 OpAssetRo.ts 模型token附件 token与name附件名称。TypeScript 调用示例来自官方文档import { } from ; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .BasicModuleAttachmentInterfaceApi(configuration); let body:.BasicModuleAttachmentInterfaceApiCiteRequest { // SpaceAssetOpRo spaceAssetOpRo: { addToken: [ { token: token_example, name: name_example, }, ], removeToken: [ { token: token_example, name: name_example, }, ], nodeId: dst10, }, }; apiInstance.cite(body).then((data:any) { console.log(API called successfully. Returned data: data); }).catch((error:any) console.error(error));请求与响应约定Content-Type:application/jsonAccept:*/*SDK 实际发送application/json, */*;q0.8见 BasicModuleAttachmentInterfaceApi.ts成功:200 OK失败:500 Internal Server Error源码实现印证控制器方法cite的逻辑AssetController.javaPostResource(path /cite, requiredLogin false) public ResponseDataVoid cite(RequestBody Valid SpaceAssetOpRo opRo) { // Fill out the form anonymously String spaceId iNodeService.getSpaceIdByNodeIdIncludeDeleted(opRo.getNodeId()); ExceptionUtil.isNotNull(spaceId, PermissionException.NODE_NOT_EXIST); iSpaceAssetService.datasheetAttachmentCite(spaceId, opRo); return ResponseData.success(); }从源码可以看出两点关键实现事实匿名表单填写场景接口注释明确为 Fill out the form anonymously匿名填写表单因此requiredLogin false未登录用户也可调用节点存在性校验服务端会先通过INodeService.getSpaceIdByNodeIdIncludeDeleted根据nodeId反查所属空间查不到节点则抛出NODE_NOT_EXIST权限异常随后才执行datasheetAttachmentCite更新引用计数。2. readReviews —— 分页查询待人工审核图片GET/base/attach/readReviews返回ResponseDataPageInfoAssetsAuditVo。当 OSS 云端图片内容审核结果为需人工复核时审核人员通过本接口分页拉取待审核图片列表。查询参数参数类型说明备注pagePage分页对象defaults to undefinedpageObjectParamsstring分页参数字符串如{pageNo:1,pageSize:20}defaults to undefined经PageObjectParam解析TypeScript 调用示例来自官方文档import { } from ; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .BasicModuleAttachmentInterfaceApi(configuration); let body:.BasicModuleAttachmentInterfaceApiReadReviewsRequest { // Page page: { records: [ {}, ], total: 1, size: 1, current: 1, orders: [ { column: column_example, asc: true, }, ], optimizeCountSql: true, searchCount: true, optimizeJoinOfCountSql: true, countId: countId_example, maxLimit: 1, pages: 1, }, // string | Page params pageObjectParams: {pageNo:1,pageSize:20}, }; apiInstance.readReviews(body).then((data:any) { console.log(API called successfully. Returned data: data); }).catch((error:any) console.error(error));请求与响应约定Content-Type: Not definedGET 请求无请求体Accept:*/*成功:200 OK返回ResponseDataPageInfoAssetsAuditVo分页数据记录类型为AssetsAuditVo失败:500 Internal Server Error源码实现印证GetResource(path /readReviews, requiredLogin false) public ResponseDataPageInfoAssetsAuditVo readReviews(PageObjectParam Page page) { String auditorUserId SessionContext.getDingtalkUserId(); ExceptionUtil.isNotNull(auditorUserId, AuthException.UNAUTHORIZED); return ResponseData.success(PageHelper.build(iAssetAuditService.readReviews(page))); }虽然声明requiredLogin false但实现中必须从会话中取到钉钉用户 IDSessionContext.getDingtalkUserId()取不到即抛出UNAUTHORIZED。也就是说本接口面向钉钉场景的审核人员开放。分页逻辑由 MyBatis-Plus 的Page承载并通过PageHelper.build统一转换为前端分页结构。3. submitAuditResult —— 提交图片审核结果POST/base/attach/submitAuditResult请求体为AssetsAuditRo返回ResponseDataVoid。人工审核完成后将每张图片的审核结论批量回传。文档特别强调提交时必须填写审核人姓名。请求体模型AssetsAuditRo对应模型文件 AssetsAuditRo.ts字段类型是否必填说明assetlistArrayAssetsAuditOpRo否附件人工审核结果列表auditorUserIdstring是审核用户 IdauditorNamestring是审核用户姓名列表项 AssetsAuditOpRo.ts 包含两个字段字段类型说明assetFileUrlstring存储路径如space/2020/03/27/1243592950910349313auditResultSuggestionstring审核结果建议如block拦截TypeScript 调用示例来自官方文档import { } from ; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .BasicModuleAttachmentInterfaceApi(configuration); let body:.BasicModuleAttachmentInterfaceApiSubmitAuditResultRequest { // AssetsAuditRo assetsAuditRo: { assetlist: [ { assetFileUrl: space/2020/03/27/1243592950910349313, auditResultSuggestion: block, }, ], auditorUserId: 0122454826077721, auditorName: name, }, }; apiInstance.submitAuditResult(body).then((data:any) { console.log(API called successfully. Returned data: data); }).catch((error:any) console.error(error));请求与响应约定Content-Type:application/jsonAccept:*/*成功:200 OK失败:500 Internal Server Error源码实现印证PostResource(path /submitAuditResult, requiredLogin false) public ResponseDataVoid submitAuditResult(RequestBody Valid AssetsAuditRo results) { // Query the DingTalk member information in the session String auditorUserId SessionContext.getDingtalkUserId(); ExceptionUtil.isNotNull(auditorUserId, AuthException.UNAUTHORIZED); iAssetAuditService.submitAuditResult(results); return ResponseData.success(); }与readReviews一致本接口同样依赖钉钉会话身份。审核落地逻辑在AssetAuditServiceImplAssetAuditServiceImpl.java中实现该服务类同时处理 OSS 审核结果回调auditCallback、非法图片的特殊处置服务内定义了非法资源占位图ASSETS_PUBLIC_PLACEHOLDER /public/placeholder.png以及审核结果入库。4. upload —— 上传资源文件POST/base/attach/upload请求体为AttachOpRo返回ResponseDataAssetUploadResult。通用资源上传入口不限制文件类型。前端通过 multipart 方式携带文件二进制流服务端根据type决定上传到用户目录还是空间目录。请求体模型AttachOpRo对应模型文件 AttachOpRo.ts字段类型是否必填说明fileHttpFile是二进制文件流type: binarytypenumber是附件类型见下方 AssetType 表nodeIdstring否节点 Id数据表附件、封面图、节点描述必须传datastring否密码登录人机校验值前端通过 NVC Val 函数获取未登录时执行人机校验AssetType 类型语义来自 AssetType.java值枚举含义0USER_AVATAR用户头像1SPACE_LOGO空间 Logo2DATASHEET数据表附件3COVER封面图4NODE_DESC节点描述5DOCUMENT文档其中AssetType.isSpaceAsset(type)判断逻辑为type.getValue() SPACE_LOGO.getValue()即值大于 1 的类型都属于空间资源需绑定nodeId会走空间上传分支0/1属于公开/用户级资源。TypeScript 调用示例来自官方文档import { } from ; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .BasicModuleAttachmentInterfaceApi(configuration); let body:.BasicModuleAttachmentInterfaceApiUploadRequest { // AttachOpRo (optional) attachOpRo: { file: { data: Buffer.from(fs.readFileSync(/path/to/file, utf-8)), name: /path/to/file }, type: 0, nodeId: dst10, data: FutureIsComing, }, }; apiInstance.upload(body).then((data:any) { console.log(API called successfully. Returned data: data); }).catch((error:any) console.error(error));请求与响应约定Content-Type:application/jsonAccept:*/*成功:200 OK返回ResponseDataAssetUploadResult外层为success/code/message/data标准响应包装见 ResponseDataAssetUploadResult.tsdata为 AssetUploadResult.ts 上传结果失败:500 Internal Server Error源码实现印证PostResource(path /upload, requiredLogin false) public ResponseDataAssetUploadResult upload(Valid AttachOpRo data) throws IOException { AssetType assetType AssetType.of(data.getType()); MultipartFile file data.getFile(); // When not logged in, perform human-machine verification Long userId SessionContext.getUserIdWithoutException(); if (userId null) { iAssetService.checkBeforeUpload(data.getNodeId(), data.getData()); } if (AssetType.isSpaceAsset(assetType)) { AssetUploadResult result iAssetService.uploadFileInSpace(data.getNodeId(), file.getInputStream(), file.getOriginalFilename(), file.getSize(), file.getContentType(), assetType); return ResponseData.success(result); } ExceptionUtil.isNotNull(userId, AuthException.UNAUTHORIZED); AssetUploadResult result iAssetService.uploadFile(file.getInputStream(), file.getSize(), file.getContentType()); return ResponseData.success(result); }从源码可提炼以下实现要点未登录人机校验SessionContext.getUserIdWithoutException()取不到用户时会先调用checkBeforeUpload(nodeId, data)执行人机验证对应AttachOpRo.data字段的用途空间资源分支type 1时调用uploadFileInSpace需要有效的nodeId才能把文件归入对应空间这也是模型注释要求数据表附件、封面图、节点描述必须传 nodeId的原因用户级资源分支type 1时走uploadFile但必须先登录否则抛UNAUTHORIZED。5. urlUpload —— 图片 URL 上传POST/base/attach/urlUpload请求体为AttachUrlOpRo返回ResponseDataAssetUploadResult。不直接上传文件流而是传一个图片 URL由服务端拉取该 URL 对应的图片并转存到对象存储适合粘贴外链图片自动转存的场景。请求体模型AttachUrlOpRo对应模型文件 AttachUrlOpRo.ts字段类型是否必填说明urlstring是待上传文件的 URLtypenumber是附件类型0用户头像、1空间 Logo、2数据表附件nodeIdstring否数据表节点 Id数据表附件必传注意与AttachOpRo的完整六种类型不同urlUpload模型注释仅覆盖0/1/2三种类型实际取值仍以服务端AssetType.of校验为准。TypeScript 调用示例来自官方文档import { } from ; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .BasicModuleAttachmentInterfaceApi(configuration); let body:.BasicModuleAttachmentInterfaceApiUrlUploadRequest { // AttachUrlOpRo (optional) attachUrlOpRo: { url: url_example, type: 0, nodeId: dst10, }, }; apiInstance.urlUpload(body).then((data:any) { console.log(API called successfully. Returned data: data); }).catch((error:any) console.error(error));请求与响应约定Content-Type:application/jsonAccept:*/*成功:200 OK返回ResponseDataAssetUploadResult失败:500 Internal Server Error源码实现印证PostResource(path /urlUpload, requiredPermission false) public ResponseDataAssetUploadResult urlUpload(Valid AttachUrlOpRo opRo) { AssetUploadResult result iAssetService.urlUpload(opRo); return ResponseData.success(result); }与其余四个端点不同urlUpload使用的是requiredPermission false注解而非requiredLogin false说明它面向已登录但无特定权限的常规用户开放实际转存逻辑封装在IAssetService.urlUpload(opRo)中由服务端完成 URL 拉取、落盘与 token 生成。补充客户端 SDK 的请求构造与响应解析以上五个方法在 BasicModuleAttachmentInterfaceApi.ts 中都有成对实现RequestFactory如cite/readReviews/submitAuditResult/upload/urlUpload负责拼装路径参数、序列化请求体ObjectSerializer.stringify(ObjectSerializer.serialize(...))、设置Accept: application/json, */*;q0.8与Content-Type并应用默认鉴权defaultAuth?.applySecurityAuthenticationResponseProcessor如citeWithHttpInfo/uploadWithHttpInfo负责反序列化响应200返回对应模型ResponseDataVoid或ResponseDataAssetUploadResult500抛出ApiExceptionResponseDataVoid。例如upload成功时uploadWithHttpInfo会把响应体解析为ResponseDataAssetUploadResult而cite、submitAuditResult则解析为ResponseDataVoid即仅需确认success状态。若需直接以 HTTP 方式调用可参考上文各接口的路径、请求体与状态码约定拼接请求例如curl -X POST http://backend/api/v1/base/attach/cite \ -H Content-Type: application/json \ -d {nodeId:dst10,addToken:[{token:token_example,name:name_example}]}常见问题与最佳实践匿名表单场景务必用 cite 维护引用计数同一附件被多个单元格/多次提交引用时通过addToken/removeToken保持space_asset引用数与实际一致避免附件被误回收空间类附件上传必须携带 nodeIdtype为2/3/4/5时upload走uploadFileInSpace分支缺少合法nodeId会导致上传失败readReviews / submitAuditResult 依赖钉钉身份这两个审核接口虽然声明requiredLogin false但会话中必须存在钉钉用户信息否则返回UNAUTHORIZED上传类型不可混淆AssetType以枚举值硬编码AssetType.java传未知类型会抛出BusinessException(unknown attachment type)响应统一包装所有接口均返回ResponseData包装结构success/code/message/data解析时建议先判断success再取data。参考资料API 文档BasicModuleAttachmentInterfaceApi.md客户端 SDK 实现BasicModuleAttachmentInterfaceApi.ts后端控制器AssetController.java附件类型枚举AssetType.java审核服务实现AssetAuditServiceImpl.java请求/响应模型SpaceAssetOpRo.ts、OpAssetRo.ts、AssetsAuditRo.ts、AssetsAuditOpRo.ts、AttachOpRo.ts、AttachUrlOpRo.ts、ResponseDataAssetUploadResult.ts赞分享低代码后端前端协同办公【免费下载链接】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 附件上传凭证与签名接口实战BasicsAttachmentUploadTokenInterfaceApi 完全解析APITable 附件上传凭证与签名接口实战BasicsAttachmentUploadTokenInterfaceApi 完全解析 导读 本文围绕 APIT低代码后端前端协同办公APITable 附件上传回调接口BasicModuleAccessoryCallbackInterfaceApi实战指南APITable 附件上传回调接口BasicModuleAccessoryCallbackInterfaceApi实战指南 导读 本文围绕 APITable低代码后端前端协同办公Headlamp 插件开发指南深入解析 PodAttachEvent 接口与 Pod 附加Attach事件机制Headlamp 插件开发指南深入解析 PodAttachEvent 接口与 Pod 附加Attach事件机制 PodAttachEvent 是 Head云原生开发工具上一篇karpenter-provider-aws 常见问题深度解析NodePool、实例选择与中断处理的 FAQ 及源码级解读下一篇从 Total Commander 到 Double Commander双面板文件管理器的日常高效使用上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考