Unstract FileManagement API面向组织的文件列表、下载与上传 REST 接口全解析【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract本文以仓库中的 FileManagement API 文档 为主体系统讲解 Unstract 后端中面向组织Organization的文件管理接口列出文件List File、下载文件Download、上传文件Upload。读完本文你不仅能掌握这三个 REST 接口的完整调用方式、参数与响应结构还能结合 backend/file_management/views.py 与 backend/file_management/file_management_helper.py 等源码理解接口背后如何通过 Connector 与UnstractFileSystem抽象对接不同的文件存储后端以及文件上传的格式与大小限制是如何在序列化器层被强制校验的。接口总览backend/file_management/api_doc.md 中定义了三个核心接口均挂载在组织作用域路径/unstract/org_id/之下功能方法路径说明List File列出文件GET/unstract/org_id/file按connector_id和path列出指定目录下的文件Download下载文件GET/unstract/org_id/file/download以流式响应返回指定文件内容Upload上传文件POST/unstract/org_id/file/upload向指定目录上传一个或多个文件三个接口都以connector_id为关键参数——Unstract 通过 Connector 实例抽象不同的文件存储后端本地存储、Google Drive、S3 等文件操作实际是委托给对应 Connector 的文件系统实现的。组织作用域路由URL 中的org_id如何生效接口路径中的org_id如示例中的org_KIYj2cJ9Yisdewi4并不由file_management应用自己解析。从源码结构看backend/middleware/organization_middleware.py 中的OrganizationMiddleware使用正则^/api/(?Pversionv[12])/unstract/(?Porg_id[^/])/匹配请求路径将org_id写入request.organization_id并把路径改写为/api/{version}/unstract/前缀后的相对路径。随后 backend/backend/urls_v2.py 第 29 行将file_management.urls挂载到根路径file/、file/download等子路由便自然衔接在后。因此api_doc.md 中的完整示例 URL 实际对应base_url/unstract/org_KIYj2cJ9Yisdewi4/file?connector_id11path/其中org_id是组织标识用于多租户隔离与鉴权上下文connector_id与path是业务查询参数。List File列出目录下的文件请求GET /unstract/org_id/file?connector_ididpathpathSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file?connector_id11path/查询参数由 backend/file_management/serializer.py 中的FileListRequestSerializer校验connector_idUUIDField必填对应数据库中ConnectorInstance主键pathCharField必填要列出的目录路径根目录可传/。响应结构返回的每个条目由FileInfoSerializer序列化字段固定为 5 个{ name: 文件/目录名, type: file 或 directory, modified_at: 最后修改时间, content_type: MIME 类型, size: 10240 }这些字段的取值逻辑可以在 backend/file_management/file_management_dto.py 的FileInformation数据类中确认name来自文件系统返回的条目名经os.path.normpath归一化modified_at解析LastModified字段content_type优先使用后端返回的ContentType缺失时由mimetypes.guess_type推断见 file_management_helper.py 中get_files方法。源码实现要点backend/file_management/views.py 中FileManagementViewSet.list的调用链为按connector_id查询ConnectorInstance不存在则抛出 404ConnectorInstanceNotFoundFileManagerHelper.get_file_system(connector_instance)根据 Connector 类型构造对应的UnstractFileSystem实例FileManagerHelper.list_files(file_system, path)内部通过fs.ls(file_path, detailTrue)递归读取一级目录条目并过滤掉与目录自身同名的条目。值得注意的是当path为空或为/时实现会回退使用file_system.pathConnector 元数据中配置的根路径因此对配置了固定根路径的 Connectorpath/实际列出的是该根路径下的内容。Download以流式响应下载文件请求GET /unstract/org_id/file/download?connector_ididpathpathSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file/download?connector_id12pathroot/MaskTwo-design查询参数与 List 相同由FileListRequestSerializer校验见 views.py 中get_serializer_class对downloadaction 的映射。流式下载的实现细节download_file位于 backend/file_management/file_management_helper.py其关键行为对调用方有三点实际影响类型校验先调用fs.info(file_path)获取元数据若type不是file例如传入了目录路径抛出InvalidFileType404即该接口只能下载单个文件Content-Type 推断优先取后端返回的ContentType若无先试mimetypes.guess_type仍无法确定时读取文件前 500 字节用python-magicmagic.from_buffer嗅探真实 MIME 类型再设置到响应的content_type流式返回使用 Django 的StreamingHttpResponse包装文件流并设置Content-Disposition: attachment; filenamebase_name使浏览器按附件下载文件名为路径中的 basename。对 Google Drive 一类后端若底层抛出ApiRequestError如 OAuth 凭证失效则转换为 400 的ConnectorApiRequestErrorFailed to stream file返回给客户端。Upload上传文件含格式与大小限制请求POST /unstract/org_id/file/uploadSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file/upload原文档给出的 Body 结构为{ file: multiple files, connector_id: Connector Id, path: File location }需要说明的是从序列化器定义看file字段是ListField(childFileField())见 backend/file_management/serializer.py因此实际请求应使用multipart/form-data编码file可重复传多个文件connector_id与path作为表单字段提交。上传限制PDF 与 200 MBFileUploadSerializer对file字段挂接了FileValidator其约束常量定义在 backend/file_management/constants.py约束项取值含义FILE_UPLOAD_ALLOWED_EXT[pdf]允许上传的文件扩展名当前仅 PDFFILE_UPLOAD_ALLOWED_MIME[application/pdf]允许的 MIME 类型FILE_UPLOAD_MAX_SIZE200 * 1024 * 1024约 200 MB单个文件最大字节数min_size0不设最小尺寸也就是说当前版本的上传接口面向 PDF 文件设计与 Unstract 以 PDF 为主要非结构化数据源的场景一致且单文件上限为 200 MB。校验不通过会在序列化器层面直接拒绝请求不会触达存储后端。上传的实现views.py 的uploadaction 遍历serializer.validated_data.get(file)中的每个上传文件逐个调用FileManagerHelper.upload_file。后者在 file_management_helper.py 中的行为与 List 相同的回退逻辑path为空或/时使用file_system.path作为实际目录拼接path / file_name通过fs.open(file_path, modewb)以二进制写入远程文件系统兼容bytes与文件对象两种输入。全部写入成功后接口返回{ message: Files are uploaded successfully! }错误码速查backend/file_management/exceptions.py 定义了该模块对外可见的错误语义调用方可以据此做分支处理异常状态码消息典型触发场景ConnectorInstanceNotFound404Connector instance does not existconnector_id在数据库中不存在ConnectorClassNotFound404Connector class does not existConnector 类型无对应文件系统实现ConnectorOAuthError401Unauthorized client during OAuthOAuth 访问令牌刷新失败List 场景ConnectorApiRequestError400Failed to stream file底层存储 API 请求失败如 Drive 的ApiRequestErrorInvalidFileType404Invalid file type下载路径指向的是目录而非文件FileListError500Error occured while listing files列目录时底层fs.ls抛错MissingConnectorParams400Missing params in connector metadataConnector 缺少必需的路径元数据其中 List 接口的异常映射在 views.py 中可以逐一对应DoesNotExist→ 404、HttpAccessTokenRefreshError→ 401、ConnectorError→ 500 的FileListError。底层抽象Connector 到文件系统的映射三个接口共同依赖FileManagerHelper.get_file_system其逻辑为读取ConnectorInstance.connector_metadata在unstract.connectors.filesystems的connectors注册表中按connector.connector_id查找找到后以元数据为配置实例化对应的UnstractFileSystem子类未找到则抛ConnectorClassNotFound。该注册表定义于 unstract/filesystem 包unstract/connectors/filesystems。从源码结构看这套抽象使得上层 API 对具体存储无感知——同一套/file端点既可以操作本地存储也可以操作云端文件服务差异被封装在 Connector 实例的元数据与对应的文件系统实现中。相关扩展端点除了原文档描述的三个接口backend/file_management/urls.py 中还注册了file/deleteGET按document_id删除 Prompt Studio 文档记录及对应文件并在prompt_studio相关 URL 模块中映射了upload_for_ide、fetch_contents_ide、list_ide等 IDE 场景端点见 views.py。这些端点服务于 Prompt Studio 的本地文档管理链路与面向 Connector 的通用文件接口在参数模型上不同删除接口使用FileInfoIdeSerializerdocument_id、tool_id路径由FileManagerHelper.handle_sub_directory_for_tenants按org_id / user_id / tool_id分层解析。理解这一分层路径结构有助于把握 Unstract 对多租户文件目录的隔离设计。小结三个接口的调用形态与参数约束以 backend/file_management/api_doc.md 为准List 与 Download 均为GETconnector_id/path查询参数Upload 为POSTmultipart 请求上传接口当前仅允许 PDF、单文件上限 200 MBconstants.py响应与错误语义可在 serializer.py、exceptions.py 中逐一对照若要在自定义集成中使用这些接口建议优先处理 401/404/400 三类状态码分别对应 OAuth 失效、资源不存在与请求/流式错误。【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Unstract FileManagement API：面向组织的文件列表、下载与上传 REST 接口全解析
Unstract FileManagement API面向组织的文件列表、下载与上传 REST 接口全解析【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract本文以仓库中的 FileManagement API 文档 为主体系统讲解 Unstract 后端中面向组织Organization的文件管理接口列出文件List File、下载文件Download、上传文件Upload。读完本文你不仅能掌握这三个 REST 接口的完整调用方式、参数与响应结构还能结合 backend/file_management/views.py 与 backend/file_management/file_management_helper.py 等源码理解接口背后如何通过 Connector 与UnstractFileSystem抽象对接不同的文件存储后端以及文件上传的格式与大小限制是如何在序列化器层被强制校验的。接口总览backend/file_management/api_doc.md 中定义了三个核心接口均挂载在组织作用域路径/unstract/org_id/之下功能方法路径说明List File列出文件GET/unstract/org_id/file按connector_id和path列出指定目录下的文件Download下载文件GET/unstract/org_id/file/download以流式响应返回指定文件内容Upload上传文件POST/unstract/org_id/file/upload向指定目录上传一个或多个文件三个接口都以connector_id为关键参数——Unstract 通过 Connector 实例抽象不同的文件存储后端本地存储、Google Drive、S3 等文件操作实际是委托给对应 Connector 的文件系统实现的。组织作用域路由URL 中的org_id如何生效接口路径中的org_id如示例中的org_KIYj2cJ9Yisdewi4并不由file_management应用自己解析。从源码结构看backend/middleware/organization_middleware.py 中的OrganizationMiddleware使用正则^/api/(?Pversionv[12])/unstract/(?Porg_id[^/])/匹配请求路径将org_id写入request.organization_id并把路径改写为/api/{version}/unstract/前缀后的相对路径。随后 backend/backend/urls_v2.py 第 29 行将file_management.urls挂载到根路径file/、file/download等子路由便自然衔接在后。因此api_doc.md 中的完整示例 URL 实际对应base_url/unstract/org_KIYj2cJ9Yisdewi4/file?connector_id11path/其中org_id是组织标识用于多租户隔离与鉴权上下文connector_id与path是业务查询参数。List File列出目录下的文件请求GET /unstract/org_id/file?connector_ididpathpathSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file?connector_id11path/查询参数由 backend/file_management/serializer.py 中的FileListRequestSerializer校验connector_idUUIDField必填对应数据库中ConnectorInstance主键pathCharField必填要列出的目录路径根目录可传/。响应结构返回的每个条目由FileInfoSerializer序列化字段固定为 5 个{ name: 文件/目录名, type: file 或 directory, modified_at: 最后修改时间, content_type: MIME 类型, size: 10240 }这些字段的取值逻辑可以在 backend/file_management/file_management_dto.py 的FileInformation数据类中确认name来自文件系统返回的条目名经os.path.normpath归一化modified_at解析LastModified字段content_type优先使用后端返回的ContentType缺失时由mimetypes.guess_type推断见 file_management_helper.py 中get_files方法。源码实现要点backend/file_management/views.py 中FileManagementViewSet.list的调用链为按connector_id查询ConnectorInstance不存在则抛出 404ConnectorInstanceNotFoundFileManagerHelper.get_file_system(connector_instance)根据 Connector 类型构造对应的UnstractFileSystem实例FileManagerHelper.list_files(file_system, path)内部通过fs.ls(file_path, detailTrue)递归读取一级目录条目并过滤掉与目录自身同名的条目。值得注意的是当path为空或为/时实现会回退使用file_system.pathConnector 元数据中配置的根路径因此对配置了固定根路径的 Connectorpath/实际列出的是该根路径下的内容。Download以流式响应下载文件请求GET /unstract/org_id/file/download?connector_ididpathpathSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file/download?connector_id12pathroot/MaskTwo-design查询参数与 List 相同由FileListRequestSerializer校验见 views.py 中get_serializer_class对downloadaction 的映射。流式下载的实现细节download_file位于 backend/file_management/file_management_helper.py其关键行为对调用方有三点实际影响类型校验先调用fs.info(file_path)获取元数据若type不是file例如传入了目录路径抛出InvalidFileType404即该接口只能下载单个文件Content-Type 推断优先取后端返回的ContentType若无先试mimetypes.guess_type仍无法确定时读取文件前 500 字节用python-magicmagic.from_buffer嗅探真实 MIME 类型再设置到响应的content_type流式返回使用 Django 的StreamingHttpResponse包装文件流并设置Content-Disposition: attachment; filenamebase_name使浏览器按附件下载文件名为路径中的 basename。对 Google Drive 一类后端若底层抛出ApiRequestError如 OAuth 凭证失效则转换为 400 的ConnectorApiRequestErrorFailed to stream file返回给客户端。Upload上传文件含格式与大小限制请求POST /unstract/org_id/file/uploadSample URL原文档示例base_url/unstract/org_KIYj2cJ9Yisdewi4/file/upload原文档给出的 Body 结构为{ file: multiple files, connector_id: Connector Id, path: File location }需要说明的是从序列化器定义看file字段是ListField(childFileField())见 backend/file_management/serializer.py因此实际请求应使用multipart/form-data编码file可重复传多个文件connector_id与path作为表单字段提交。上传限制PDF 与 200 MBFileUploadSerializer对file字段挂接了FileValidator其约束常量定义在 backend/file_management/constants.py约束项取值含义FILE_UPLOAD_ALLOWED_EXT[pdf]允许上传的文件扩展名当前仅 PDFFILE_UPLOAD_ALLOWED_MIME[application/pdf]允许的 MIME 类型FILE_UPLOAD_MAX_SIZE200 * 1024 * 1024约 200 MB单个文件最大字节数min_size0不设最小尺寸也就是说当前版本的上传接口面向 PDF 文件设计与 Unstract 以 PDF 为主要非结构化数据源的场景一致且单文件上限为 200 MB。校验不通过会在序列化器层面直接拒绝请求不会触达存储后端。上传的实现views.py 的uploadaction 遍历serializer.validated_data.get(file)中的每个上传文件逐个调用FileManagerHelper.upload_file。后者在 file_management_helper.py 中的行为与 List 相同的回退逻辑path为空或/时使用file_system.path作为实际目录拼接path / file_name通过fs.open(file_path, modewb)以二进制写入远程文件系统兼容bytes与文件对象两种输入。全部写入成功后接口返回{ message: Files are uploaded successfully! }错误码速查backend/file_management/exceptions.py 定义了该模块对外可见的错误语义调用方可以据此做分支处理异常状态码消息典型触发场景ConnectorInstanceNotFound404Connector instance does not existconnector_id在数据库中不存在ConnectorClassNotFound404Connector class does not existConnector 类型无对应文件系统实现ConnectorOAuthError401Unauthorized client during OAuthOAuth 访问令牌刷新失败List 场景ConnectorApiRequestError400Failed to stream file底层存储 API 请求失败如 Drive 的ApiRequestErrorInvalidFileType404Invalid file type下载路径指向的是目录而非文件FileListError500Error occured while listing files列目录时底层fs.ls抛错MissingConnectorParams400Missing params in connector metadataConnector 缺少必需的路径元数据其中 List 接口的异常映射在 views.py 中可以逐一对应DoesNotExist→ 404、HttpAccessTokenRefreshError→ 401、ConnectorError→ 500 的FileListError。底层抽象Connector 到文件系统的映射三个接口共同依赖FileManagerHelper.get_file_system其逻辑为读取ConnectorInstance.connector_metadata在unstract.connectors.filesystems的connectors注册表中按connector.connector_id查找找到后以元数据为配置实例化对应的UnstractFileSystem子类未找到则抛ConnectorClassNotFound。该注册表定义于 unstract/filesystem 包unstract/connectors/filesystems。从源码结构看这套抽象使得上层 API 对具体存储无感知——同一套/file端点既可以操作本地存储也可以操作云端文件服务差异被封装在 Connector 实例的元数据与对应的文件系统实现中。相关扩展端点除了原文档描述的三个接口backend/file_management/urls.py 中还注册了file/deleteGET按document_id删除 Prompt Studio 文档记录及对应文件并在prompt_studio相关 URL 模块中映射了upload_for_ide、fetch_contents_ide、list_ide等 IDE 场景端点见 views.py。这些端点服务于 Prompt Studio 的本地文档管理链路与面向 Connector 的通用文件接口在参数模型上不同删除接口使用FileInfoIdeSerializerdocument_id、tool_id路径由FileManagerHelper.handle_sub_directory_for_tenants按org_id / user_id / tool_id分层解析。理解这一分层路径结构有助于把握 Unstract 对多租户文件目录的隔离设计。小结三个接口的调用形态与参数约束以 backend/file_management/api_doc.md 为准List 与 Download 均为GETconnector_id/path查询参数Upload 为POSTmultipart 请求上传接口当前仅允许 PDF、单文件上限 200 MBconstants.py响应与错误语义可在 serializer.py、exceptions.py 中逐一对照若要在自定义集成中使用这些接口建议优先处理 401/404/400 三类状态码分别对应 OAuth 失效、资源不存在与请求/流式错误。【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考