# 创建文件元数据 - createFile #### 功能介绍 上传文件第一步，该接口会创建文件的元数据。如果秒传未命中，需要走上传流程。如果秒传命中，则文件上传完成。 #### 授权信息 当前API调用无需身份策略权限。 #### 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鉴权 | | X-Traceid | 否 | String | 消息日志跟踪标识（必须58位） | | language | 否 | String | 国际化语言标识，符合i18n规范，如zh-CN表示简体中文，en-US表示美式英语，不传默认美式英语 | | x-hw-share-folder-id | 否 | String | 参数解释： 共享文件夹ID。如果传入了该请求头，则说明当前的操作是在共享文件夹内。 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 | 表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 | 存储签名，使用文件的二进制数据生成，用于防撞库。当传入sha256字段时，该值必传；生成算法参考附录-ProofCode生成步骤。 | | hidden | 否 | Boolean | 文件是否隐藏（该功能目前只有白名单用户使用） | | scene | 否 | String | 自定义属性 | 表3MultiPartInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | partNumber | 是 | Integer | 分片编号，取值1-10000 | | partSize | 是 | Long | 分片长度，取值范围\[5242880, 5368709120\]，最后一个分片取值范围\[0, 5368709120\] minimum: 0 maximum: 5368709120 | | partOffset | 否 | Long | 到上一个数据块为止的总长度，单位为字节，该字段仅在分片并行上传时有效，分片并行上传时，除最后一个分片外，分片并行上传的其它分片大小，必须是 64字节的倍数 | | hashCtx | 否 | Array of longs | 用于迭代计算SHA256的上下文，该字段仅在分片并行上传时有效。对于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 | 返回信息 | | existFileId | String | 已存在的文件id，当请求的重名策略为3时且出现同名文件时返回 | 表5MultiPartInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | partNumber | Integer | 分片编号，取值1-10000 | | partSize | Long | 分片长度，取值范围\[5242880, 5368709120\]，最后一个分片取值范围\[0, 5368709120\] minimum: 0 maximum: 5368709120 | | partOffset | Long | 到上一个数据块为止的总长度，单位为字节，该字段仅在分片并行上传时有效，分片并行上传时，除最后一个分片外，分片并行上传的其它分片大小，必须是 64字节的倍数 | | hashCtx | Array of longs | 用于迭代计算SHA256的上下文，该字段仅在分片并行上传时有效。对于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 | 上传文件第一步完成返回的信息 |