文档首页/ 云空间服务 KooDrive/ API参考/ API/ 文件管理/ 创建文件元数据
更新时间：2025-03-14 GMT+08:00
查看PDF
分享

创建文件元数据

功能介绍

上传文件第一步，该接口会创建文件的元数据。如果秒传未命中，需要走上传流程。如果秒传命中，则文件上传完成。

URI

POST /koodrive/ose/v1/files/create

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

Authorization

是

String

该字段存储的是Access Token。调用KooDrive的API使用Token认证，拥有Token就代表拥有某种权限，在调用API的时候将Token加到请求消息头中，从而通过身份认证，获得操作API的权限。Access Token的获取请参考对应的开发手册，格式参考：Bearer+{access_token}

X-User-Id

是

String

用户id，用于app鉴权

X-Date

是

String

日期，用于app鉴权

Host

是

String

地址，用于app鉴权

X-Traceid

否

String

消息日志跟踪标识（必须58位）

language

否

String

国际化语言标识，符合i18n规范，如zh-CN表示简体中文，en-US表示美式英语，不传默认美式英语
表2 请求Body参数

参数

是否必选

参数类型

描述

createdTime

否

String

文件创建时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，样例：2023-08-18T05:43:49Z

description

否

String

文件描述

mimeType

否

String

资源类型

fileName

是

String

文件名，不能包括'<>|:"*?/'，不能等于'..','.',''，最长250个字符

fileType

是

String

文件类型，业务自行定义

parentFolder

是

Array of strings

父目录标识列表，当目标为根目录时值为root

当前只支持一个父目录，如果传入多个父目录id，只会取第一个作为父目录id

sha256

否

String

用SHA256计算的文件完整摘要信息

length

是

Long

文件的长度，单位：字节

uploadMode=multipart时，取值应小于等于200GB

uploadMode

是

String

上传模式，枚举值：

  • multipart：分段上传

uploadType

是

Integer

上传类型，枚举值：

  • 0：普通上传（暂时不支持）

  • 1：分段上传

  • 2：多版本上传（暂时不支持）

autoRename

是

Integer

重名策略，枚举值：

  • 2：强制重命名，出现重名文件时，文件名末尾追加时间戳

  • 3：拒绝重命名，出现重名文件时，创建失败

  • 4：自动重命名，出现重名，且文件sha256值一样时，不会创建文件，否则按强制重命名逻辑执行

multiParts

否

Array of MultiPartInfo objects

分片信息列表

containerId

是

String

文件上传的目标空间的Id

preHash

否

String

用SHA256计算的文件前1KB的摘要信息

proofCode

否

String

存储签名，使用文件的二级制数据生成，防撞库

hidden

否

Boolean

文件是否隐藏（该功能目前只有白名单用户使用）
表3 MultiPartInfo

参数

是否必选

参数类型

描述

partNumber

是

Integer

分片编号

partSize

是

Long

分片长度，取值范围[5242880, 5368709120]，最后一个分片取值范围[0, 5368709120]

minimum: 0

maximum: 5368709120

partOffset

否

Long

到上一个数据块为止的总长度，单位为字节，该字段仅在分片并行上传时有效，分片并行上传时，除最后一个分片外，分片并行上传的其它分片大小，必须是 64字节的倍数

hashCtx

否

Array of longs

用于迭代计算SHA256的上下文，该字段仅在分片并行上传时有效。对于SHA1，取值为上一个数据块SHA1的第1-5个32位变量。对于SHA256，取值为上一个数据块SHA256的第1-8个32位变量。

注：分片并行上传时除第一个分片外其他分片必填。

uploadUrl

否

String

文件上传的URL，返回参数，上传文件需要使用PUT方法

partId

否

String

分片对象ID

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

fileId

String

文件id

rapidUpload

Boolean

是否秒传命中（true表示秒传命中）

containerId

String

文件所在空间id

fileName

String

上传后文件名，如果没有重命名则和请求参数的文件名保持一致

uploadId

String

文件上传Id

parentFolder

Array of strings

上传后文件所在父目录Id

exist

Boolean

文件是否存在，仅在入参autoRename=4时使用，当文件名一致，且文件的sha256一致，返回true

multiParts

Array of MultiPartInfo objects

分片信息，在分段上传时（uploadMode=multipart）返回

matchedPreHash

Boolean

存在匹配的preHash

code

String

返回码

msg

String

返回信息
表5 MultiPartInfo

参数

参数类型

描述

partNumber

Integer

分片编号

partSize

Long

分片长度，取值范围[5242880, 5368709120]，最后一个分片取值范围[0, 5368709120]

minimum: 0

maximum: 5368709120

partOffset

Long

到上一个数据块为止的总长度，单位为字节，该字段仅在分片并行上传时有效，分片并行上传时，除最后一个分片外，分片并行上传的其它分片大小，必须是 64字节的倍数

hashCtx

Array of longs

用于迭代计算SHA256的上下文，该字段仅在分片并行上传时有效。对于SHA1，取值为上一个数据块SHA1的第1-5个32位变量。对于SHA256，取值为上一个数据块SHA256的第1-8个32位变量。

注：分片并行上传时除第一个分片外其他分片必填。

uploadUrl

String

文件上传的URL，返回参数，上传文件需要使用PUT方法

partId

String

分片对象ID

请求示例

通过“分片上传”方式创建文件元数据，该示例指定了一个分片，后续响应会返回对应分片的上传地址，需要将对应分片通过PUT请求上传对应的分片。

POST /koodrive/ose/v1/files/create

Authorization:Bearer+10f88*********4791e9ff

{
    "containerId": "IAADfsBFCO6WtAtuA9add2fea594e4e75b8feb8474ef236",
    "parentFolder": [
        "root"
    ],
    "createdTime": "2020-05-18T01:43:49Z",
    "mimeType": "application/x-zip-compressed",
    "fileType": 35,
    "fileName": "demo.zip",
    "sha256": "08a784aeb181506391c20c6355f881dc363d8c3e0739d295e5d6f410d05dbc69",
    "length": 22106481,
    "uploadMode": "multipart",
    "uploadType": 1,
    "autoRename": 2,
    "multiParts": [
        {
            "partNumber": 1,
            "partOffset": 0,
            "partSize": 22106481
        }
    ],
    "description": ""
}

响应示例

状态码：200

上传文件第一步完成返回的信息

{
  "fileId" : "FnkL1QhXj8muHBuSWCHtFFY8Azue44Snr",
  "containerId" : "IAADfsBFCO6WtAtuA9add2fea594e4e75b8feb8474ef236",
  "fileName" : "test_20240104_105403.zip",
  "uploadId" : "0000018CD26464022026422966B8879A",
  "parentFolder" : [ "DEUI7pa0C24ArootIAADfsBFCO6WtAtuA9add2fea594e4e75b8feb8474ef236" ],
  "exist" : false,
  "multiParts" : [ {
    "partNumber" : 1,
    "partSize" : 22106481,
    "partOffset" : 0,
    "uploadUrl" : "https://b10-obs-ykj-uat-01.obs.cidc-rp-2006.joint.cmecloud.cn/ff6b221b4b474c829c1cd5037f1504ca086?partNumber=1&uploadId=0000018CD26464022026422966B8879A&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240104T025403Z&X-Amz-SignedHeaders=content-length%3Bhost&X-Amz-Expires=3600&X-Amz-Credential=MKRISPBZAJWFHNBJ5WLB%2F20240104%2Fcidc-rp-2006%2Fs3%2Faws4_request&X-Amz-Signature=39b9b620c8de901682675059cfcfa9902a13fb5c6ab38fe1451763feb6a8323c"
  } ],
  "code" : 0,
  "msg" : "Success."
}

状态码

状态码

描述

200

上传文件第一步完成返回的信息
父主题： 文件管理

相关文档