/api/asset

upload

• 🔥 上传资源文件
• /api/asset/upload

---

请求

Types

/**
 * Upload assets
 */
export interface IPayload {
    /**
     * The folder path where assets are stored
     * with the data folder as the root path
     * @defaultValue "assets"
     *
     * @example "assets": workspace/data/assets/
     * @example "assets/": workspace/data/assets/
     * @example "/assets": workspace/data/assets/
     * @example "/assets/": workspace/data/assets/
     *
     * @example "assets/sub": workspace/data/assets/sub/
     * @example "assets/sub/": workspace/data/assets/sub/
     * @example "/assets/sub": workspace/data/assets/sub/
     * @example "/assets/sub/": workspace/data/assets/sub/
     */
    assetsDirPath?: string;
    /**
     * Uploaded file list
     */
    files: File[];
}

---

响应

Types

/**
 * Upload assets
 */
export interface IResponse {
    /**
     * status code
     */
    readonly code: number;
    readonly data: IData;
    /**
     * status message
     */
    readonly msg: string;
}

/**
 * the result of uploading assets
 */
export interface IData {
    readonly errFiles: string[] | null;
    readonly succMap: { [key: string]: string };
}

JSON Schema (json5)

/**
 * schemas/kernel/api/asset/upload/response.schema.json5
 * 上传资源文件
 * REF: https://github.com/siyuan-note/siyuan/blob/master/API.md#upload-assets
 * REF: https://github.com/siyuan-note/siyuan/blob/v2.9.3/kernel/model/upload.go#L110-L202
 * @pathname: /api/asset/upload
 * @version: 2.9.3
 */
{
    $schema: 'https://json-schema.org/draft/2020-12/schema',
    $id: 'https://github.com/siyuan-community/siyuan-sdk/raw/main/schemas/kernel/api/asset/upload/response.schema.json5',
    $comment: 'v2.9.3',
    $ref: '#/$defs/root',
    $defs: {
        root: {
            title: 'response body',
            description: 'Upload assets',

            type: 'object',
            additionalProperties: false,
            required: [
                'code',
                'msg',
                'data',
            ],
            properties: {
                code: {
                    type: 'integer',
                    description: 'status code',
                },
                msg: {
                    type: 'string',
                    description: 'status message',
                },
                data: {
                    $ref: '#/$defs/data',
                },
            },
        },
        data: {
            title: 'IData',
            description: 'the result of uploading assets',

            type: 'object',
            additionalProperties: false,
            required: [
                'errFiles',
                'succMap',
            ],
            properties: {
                errFiles: {
                    oneOf: [
                        {
                            // 所有文件成功上传
                            type: 'null',
                            description: 'all of assets are uploaded successfully',
                        },
                        {
                            // 存在上传失败的资源文件
                            type: 'array',
                            description: 'List of filenames with errors in upload processing',
                            items: {
                                // 上传失败的文件名
                                type: 'string',
                                description: 'the filename with errors in upload processing',
                            },
                        },
                    ],
                },
                succMap: {
                    $ref: '#/$defs/succMap',
                },
            },
        },
        succMap: {
            /**
             * 成功上传的资源文件映射
             * - key: 资源文件名
             * - value: 可引用该资源文件的链接地址
             * 若上传的文件已存在(名称一致), 则会覆盖对应的文件
             */
            title: 'ISuccMap',
            description: 'the map for successfully processed files\nthe key is the file name when uploading\nthe value is a reference link address of this asset',

            type: 'object',
            additionalProperties: {
                type: 'string',
            },
            propertyNames: {
                type: 'string',
            },
        },
    },
}

JSON Schema (json)

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://github.com/siyuan-community/siyuan-sdk/raw/main/schemas/kernel/api/asset/upload/response.schema.json",
    "$comment": "v2.9.3",
    "$ref": "#/$defs/root",
    "$defs": {
        "root": {
            "title": "response body",
            "description": "Upload assets",
            "type": "object",
            "additionalProperties": false,
            "required": [
                "code",
                "msg",
                "data"
            ],
            "properties": {
                "code": {
                    "type": "integer",
                    "description": "status code"
                },
                "msg": {
                    "type": "string",
                    "description": "status message"
                },
                "data": {
                    "$ref": "#/$defs/data"
                }
            }
        },
        "data": {
            "title": "IData",
            "description": "the result of uploading assets",
            "type": "object",
            "additionalProperties": false,
            "required": [
                "errFiles",
                "succMap"
            ],
            "properties": {
                "errFiles": {
                    "oneOf": [
                        {
                            "type": "null",
                            "description": "all of assets are uploaded successfully"
                        },
                        {
                            "type": "array",
                            "description": "List of filenames with errors in upload processing",
                            "items": {
                                "type": "string",
                                "description": "the filename with errors in upload processing"
                            }
                        }
                    ]
                },
                "succMap": {
                    "$ref": "#/$defs/succMap"
                }
            }
        },
        "succMap": {
            "title": "ISuccMap",
            "description": "the map for successfully processed files\nthe key is the file name when uploading\nthe value is a reference link address of this asset",
            "type": "object",
            "additionalProperties": {
                "type": "string"
            },
            "propertyNames": {
                "type": "string"
            }
        }
    }
}