文件检查 API：一次 REST 调用获得 SHA-256、真实 MIME、防病毒信号和元数据

文件检查 API：一次 REST 调用获得 SHA-256、真实 MIME、防病毒信号和元数据

接收上传文件的应用，通常需要在把文件交给解析器、工作流或存储管道之前增加一个技术检查点。市场平台可能收到卖家文档，SaaS产品可能接受客户附件，共享平台也可能需要记录进入系统的内容。团队可以分别实现哈希、MIME检测、元数据提取和初步恶意软件分流，但长期保持这些检查一致并不轻松。FileInspection通过异步REST契约集中提供这些检查，并返回一份JSON报告。

Multipart请求

经过身份验证的客户端向POST /api/files/start-process发送multipart请求，使用actionName=FileInspection，在file字段中放入一个文件，并发送parameters=[]和async=true。每次调用只接受一个非空文件，大小上限50 MB，不按扩展名设置白名单。服务端会自行验证实际请求和大小；前端的accept属性、文件名或浏览器声明的MIME都不是安全边界。

初始响应表示任务已经排队，并不代表报告已经完成。保存返回的流程ID和trackingUrl，然后在已认证的上下文中轮询/api/actions/get-action-infos/{id}。这样，在MIME检测、防病毒引擎分流、元数据提取或媒体探测运行时，上传请求不必一直保持打开。

JSON报告包含什么

成功的FileInspection结果是一份JSON文件，其中记录原始文件名、大小、SHA-256哈希和真实检测到的MIME类型。MIME值来自文件内容，而不是把浏览器提供的值当作事实。这让应用可以更可靠地记录、路由文件，或决定是否应把文件交给后续解析器。

当文件格式支持时，ExifTool可以提供经过筛选的EXIF元数据。音频和视频可以通过FFprobe获得编解码器、分辨率、时长和比特率。图片和PDF可以获得最多500个字符的OCR预览。字段取决于格式，可能缺失、为空或不可用；不能因为某字段没有出现就认为上传失败。

分流信号及其限制

防病毒部分报告防病毒引擎状态clean、infected或error。这是初步的分流信号，绝不是防病毒保证。尤其要注意，clean只表示这次检查没有报告检测结果；界面或自动化策略绝不能把它改写成“已认证安全”。error必须与clean保持区别，以便集成方采取谨慎的后续措施。

检测规则集部分报告clean、matched或not_run。起始规则集有意保持最小，并不是完整的检测库。matched可以成为送人工复核的理由，而clean或not_run都不能证明不存在威胁。文档、日志和产品提示都应保留这一界限。

设计可靠的集成

把动作ID作为异步任务的持久引用。至少区分验证被拒绝、处理中、处理失败和成功完成四种状态。如果轮询超时，先读取现有动作，再考虑是否重新提交。仅仅因为某一次状态请求没有及时返回就重新发起检查，可能造成重复工作并额外消耗tokens。

成功后，使用服务端提供的结果引用和经过身份验证的下载流程取得JSON。不要只用整数ID拼接结果URL，也不要把客户端提供的动作ID视为授权证明。自己的应用在把报告关联到上传记录时，同样要检查所有权。哈希有助于去重和追踪，但不会授予底层文件的访问权。

价格和适用范围

成功检查一次收费12 tokens。空文件或超过50 MB等验证失败不会收费。因此，它适合作为解析或人工复核前一个有边界的技术检查点，而不是完整恶意软件分析平台或业务内容策略的替代品。

一次异步REST调用可以得到SHA-256、真实MIME、初步防病毒引擎信号、最小检测规则集状态、筛选后的元数据以及按格式提供的媒体或OCR信息。异步契约让调用方继续自己的队列处理，同时保留清晰、可审计的检查引用。