agentic_huge_data_base / wiki
页面 Mayan EDMS · 7.3 接口参考·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mayan EDMS / 7.3

7.3 · 接口参考（API Reference）

企业电子文档治理 · 聚焦本章的模块关系、源码依据与实现要点。

项目Mayan EDMS 章节7.3 状态全文译文 模块文档对象与元数据、接口与服务契约、认证、权限与安全、系统架构
项目要点页2.5 参考项目 项目章节目录Mayan EDMS DeepWiki 原始章节API Reference 上一章7.2
源码线索
  • mayan/apps/cabinets/tests/test_wizard_steps.py
  • mayan/apps/cabinets/wizard_steps.py
  • mayan/apps/dependencies/dependencies.py
  • mayan/apps/documents/apps.py
  • mayan/apps/documents/icons.py
  • mayan/apps/documents/links/document_version_links.py
  • mayan/apps/documents/managers.py
  • mayan/apps/documents/permissions.py
  • mayan/apps/documents/tasks.py
  • mayan/apps/documents/urls.py
模块标签
  • 文档对象与元数据
  • 接口与服务契约
  • 认证、权限与安全
  • 系统架构
  • 测试、发布与运维

章节正文

接口参考

原始 DeepWiki 页面https://deepwiki.com/mayan-edms/Mayan-EDMS/7.3-api-reference

API 参考

相关源文件

本章引用的主要源码文件：

  • mayan/apps/cabinets/tests/test_wizard_steps.py
  • mayan/apps/cabinets/wizard_steps.py
  • mayan/apps/dependencies/dependencies.py
  • mayan/apps/documents/apps.py
  • mayan/apps/documents/icons.py
  • mayan/apps/documents/links/document_version_links.py
  • mayan/apps/documents/managers.py
  • mayan/apps/documents/permissions.py
  • mayan/apps/documents/tasks.py
  • mayan/apps/documents/urls.py
  • mayan/apps/documents/views/document_type_views.py
  • mayan/apps/documents/views/document_version_views.py
  • mayan/apps/documents/views/document_views.py
  • mayan/apps/metadata/api.py
  • mayan/apps/metadata/api_views.py
  • mayan/apps/metadata/forms.py
  • mayan/apps/metadata/models.py
  • mayan/apps/metadata/serializers.py
  • mayan/apps/metadata/tests/literals.py
  • mayan/apps/metadata/tests/mixins.py
  • mayan/apps/metadata/tests/test_forms.py
  • mayan/apps/metadata/tests/test_models.py
  • mayan/apps/metadata/tests/test_wizard_steps.py
  • mayan/apps/metadata/urls.py
  • mayan/apps/metadata/wizard_steps.py
  • mayan/apps/quotas/tests/test_hooks.py
  • mayan/apps/sources/admin.py
  • mayan/apps/sources/api_views.py
  • mayan/apps/sources/apps.py
  • mayan/apps/sources/classes.py
  • mayan/apps/sources/dependencies.py
  • mayan/apps/sources/forms.py
  • mayan/apps/sources/links.py
  • mayan/apps/sources/literals.py
  • mayan/apps/sources/migrations/0010_auto_20151001_0055.py
  • mayan/apps/sources/migrations/0027_auto_20201030_0259.py
  • mayan/apps/sources/models.py
  • mayan/apps/sources/serializers.py
  • mayan/apps/sources/source_backends/sane_scanner_backends.py
  • mayan/apps/sources/tasks.py
  • mayan/apps/sources/tests/test_api.py
  • mayan/apps/sources/tests/test_views.py
  • mayan/apps/sources/urls.py
  • mayan/apps/sources/wizards.py
  • mayan/apps/tags/tests/literals.py
  • mayan/apps/tags/tests/test_document_tag_api.py
  • mayan/apps/tags/tests/test_indexing.py
  • mayan/apps/tags/tests/test_tag_api.py
  • mayan/apps/tags/tests/test_tag_document_api.py
  • mayan/apps/tags/tests/test_wizard_steps.py
  • mayan/apps/tags/wizard_steps.py

目的与范围

本文档提供 Mayan EDMS REST API 的全面参考文档，包括端点规范、认证机制、请求/响应格式以及序列化模式。该 API 支持以编程方式访问文档管理、元数据处理、源配置和工作流操作。

有关底层数据模型和数据库模式的信息，请参阅数据模型参考。有关 API 相关配置设置和部署选项，请参阅配置参考。

API 架构总览

整体 API 结构
Mayan EDMS · 整体 API 结构 · 图 1
Mayan EDMS · 整体 API 结构 · 图 1

来源：mayan/apps/documents/urls.py:522-688, mayan/apps/sources/urls.py:73-86, mayan/apps/metadata/urls.py:100-129, mayan/apps/rest_api/fields.py:30, mayan/apps/documents/apps.py:285-287

URL 路由结构
Mayan EDMS · URL 路由结构 · 图 2
Mayan EDMS · URL 路由结构 · 图 2

来源：mayan/apps/documents/urls.py:522-688, mayan/apps/sources/urls.py:73-86, mayan/apps/metadata/urls.py:100-129

核心 API 端点

文档管理端点
HTTP 方法端点视图类用途
GET, POST/api/documents/APIDocumentListView列出/创建文档
POST/api/documents/upload/APIDocumentUploadView上传新文档
GET, PUT, PATCH, DELETE/api/documents/{id}/APIDocumentDetailView文档操作
POST/api/documents/{id}/type/change/APIDocumentChangeTypeView更改文档类型

来源：mayan/apps/documents/urls.py:522-564

文档文件管理
HTTP 方法端点视图类用途
GET/api/documents/{id}/files/APIDocumentFileListView列出文档文件
GET, PUT, PATCH, DELETE/api/documents/{id}/files/{file_id}/APIDocumentFileDetailView文件操作
GET/api/documents/{id}/files/{file_id}/download/APIDocumentFileDownloadView下载文件
GET/api/documents/{id}/files/{file_id}/pages/APIDocumentFilePageListView列出文件页面

来源：mayan/apps/documents/urls.py:566-596

源管理
HTTP 方法端点视图类用途
GET, POST/api/sources/APISourceListView列出/创建源
GET, PUT, PATCH, DELETE/api/sources/{id}/APISourceView源操作
GET, POST/api/sources/{id}/actions/{action}/APISourceActionDetailView执行源操作

来源：mayan/apps/sources/urls.py:73-86

元数据管理
HTTP 方法端点视图类用途
GET, POST/api/metadata_types/APIMetadataTypeListView列出/创建元数据类型
GET, PUT, PATCH, DELETE/api/metadata_types/{id}/APIMetadataTypeView元数据类型操作
GET, POST/api/documents/{id}/metadata/APIDocumentMetadataListView文档元数据
GET, PUT, PATCH, DELETE/api/documents/{id}/metadata/{meta_id}/APIDocumentMetadataView元数据操作

来源：mayan/apps/metadata/urls.py:100-129

认证与权限

权限系统集成
Mayan EDMS · 权限系统集成 · 图 3
Mayan EDMS · 权限系统集成 · 图 3

来源：mayan/apps/metadata/api_views.py:31-37, mayan/apps/sources/api_views.py:21-24, mayan/apps/documents/apps.py:437-486

权限模式

API 使用三种主要的权限模式：

  1. 对象权限（mayan_object_permissions）：应用于特定的模型实例
  2. 视图权限（mayan_view_permissions）：应用于整个视图/端点
  3. 外部对象权限（mayan_external_object_permissions）：应用于相关对象

来源：mayan/apps/metadata/api_views.py:31-37, mayan/apps/sources/api_views.py:105-109

序列化系统

动态字段选择
Mayan EDMS · 动态字段选择 · 图 4
Mayan EDMS · 动态字段选择 · 图 4

来源：mayan/apps/documents/apps.py:285-287, mayan/apps/sources/apps.py:72-74, mayan/apps/rest_api/fields.py:30

关键序列化器类
序列化器类模型用途文件位置
DocumentSerializerDocument文档表示documents.serializers
SourceSerializerSource源配置sources.serializers
MetadataTypeSerializerMetadataType元数据类型定义metadata.serializers
DocumentMetadataSerializerDocumentMetadata文档元数据值metadata.serializers

来源：mayan/apps/metadata/serializers.py:24-37, mayan/apps/sources/serializers.py:10-21

请求/响应模式

文档上传流程
Mayan EDMS · 文档上传流程 · 图 5
Mayan EDMS · 文档上传流程 · 图 5

来源：mayan/apps/documents/tasks.py:140-194, mayan/apps/sources/models.py:87-161

元数据管理流程
Mayan EDMS · 元数据管理流程 · 图 6
Mayan EDMS · 元数据管理流程 · 图 6

来源：mayan/apps/metadata/api_views.py:22-55, mayan/apps/metadata/serializers.py:88-144

源操作系统

源后端操作
Mayan EDMS · 源后端操作 · 图 7
Mayan EDMS · 源后端操作 · 图 7

来源：mayan/apps/sources/api_views.py:15-97, mayan/apps/sources/classes.py:91-232

操作配置

源操作使用 SourceBackendAction 命名元组定义，包含以下字段：

  • name：操作标识符
  • accept_files：操作是否接受文件上传
  • arguments：必需参数
  • confirmation：是否需要确认
  • method：要执行的后端方法

来源：mayan/apps/sources/classes.py:91-108

错误处理与状态码

标准 HTTP 状态码
状态码用途示例场景
200 OK成功的 GET、PUT、PATCH文档已检索、元数据已更新
201 Created成功的 POST文档已创建、元数据已添加
204 No Content成功的 DELETE文档已删除、元数据已移除
400 Bad Request校验错误无效的元数据值、缺少必填字段
401 Unauthorized需要认证未提供有效凭证
403 Forbidden权限被拒绝用户缺少所需权限
404 Not Found资源未找到文档 ID 不存在
校验错误格式

API 校验错误遵循 Django REST Framework 约定：

{
    "field_name": ["该字段的错误消息"],
    "non_field_errors": ["通用校验错误"]
}

来源：mayan/apps/metadata/serializers.py:118-144

集成示例

创建文档并附带元数据
POST /api/documents/upload/
Content-Type: multipart/form-data

{
    "document_type_id": 1,
    "file": "<文件数据>",
    "metadata": [
        {
            "metadata_type_id": 1,
            "value": "发票 #12345"
        }
    ]
}
执行源操作
POST /api/sources/1/actions/upload/
Content-Type: application/json

{
    "arguments": {
        "document_type_id": 1,
        "expand": false
    },
    "file": "<文件数据>"
}

来源：mayan/apps/sources/api_views.py:51-62, mayan/apps/metadata/api_views.py:50-54