# 使用预签名URL分块上传文件 #### 操作场景 工业数字模型驱动引擎-数据建模引擎（xDM Foundation，简称xDM-F）可以将待上传的文件分成多个分块分别上传，上传完成后再调用"file_mergeFiles"接口将这些分块合并成一个对象存储至某个数据模型中。完成文件的分块上传后，可在调用数据实例的创建/更新接口时，将文件与该数据实例进行关联，从而实现对象化管理文件。 本文仅指导您如何通过API接口，采用预签名URL的方式分块上传文件至对象存储（OBS/S3）服务。预签名URL上传通过后端生成临时访问凭证，客户端直接与对象存储服务交互，既保证了安全性又提高了上传效率。关于如何创建/更新数据实例的接口请参见[全量数据服务](https://support.huaweicloud.com/usermanual-idme/idme_clientog_0154.html)。 #### 操作流程 ![](https://support.huaweicloud.com/bestpractice-idme/figure/zh-cn_image_0000002278995429.png) 1. 使用分块上传文件之前，您必须先调用"文件管理"的"file_startBatchUpload"接口校验待上传的文件之前是否上传至某个数据模型中。如果您之前已经上传某个文件，现在需要重新上传，那么该文件具有闪传能力，会自动闪传至数据模型中，无需重新分块上传。如果您没有上传过该文件，调用"file_startBatchUpload"接口时，初始化分块上传，成功执行此请求后将返回"docId"和"fileId"，用于后续的分块请求。 2. 初始化分块上传后，调用"文件管理"的"upload_uploadLargeFile"接口根据指定的"docId"、"fileId"、"chunk"等参数值获取预签名URL。 3. 获取预签名URL后，使用PUT请求方式，将[2]返回的请求头设为本次请求头，以二进制文件形式上传预先切分好的文件分块。 4. 完成分块上传后，调用"文件管理"的"upload_v1_confirm"接口来确认分块上传的状态，用以确保所有分块都已成功上传，并且文件的完整性得到了验证。 5. 当使用"upload_uploadLargeFile"完成所有分块上传后，您必须调用"file_mergeFiles"来完成整个文件的分块上传。在使用该接口时，您必须在请求体中给出"docId"、"fileId"和"chunk"等参数值，用来校验每个分块的有效性。当所有的分块验证通过后，系统将把这些分块合并成一个完整的文件。 #### 操作步骤 1. 闪传文件。 如果您已上传某个文件，在上传该文件时，您只需执行本步骤即可完成文件上传。 - 接口相关信息 表1startBatchUpload接口 | 接口信息 | 说明 | |:---|:---| | URI格式 | ``` POST http://{Endpoint}/rdm_{appID}_app/services/rdm/basic/api/file/startBatchUpload ``` - Endpoint：必填，String类型，承载REST服务端点的服务器域名或IP地址。 - appID：必填，String类型，应用ID。 - applicationId：必填，String类型，应用ID。 - model_name：必填，String类型，数据模型的英文名称。 - model_number：选填，String类型，数据模型的编码。 - attribute_name：必填，String类型，数据模型的属性英文名称。 - file_name：选填，String类型，待上传文件的名称。本参数与fileName参数必须二选一。不能同时为空，且优先级低于fileName。 - file_size：必填，String类型，待上传文件的大小。 - chunks：必填，String类型，待上传文件的分块数量。您可以根据[构建数据模型](https://support.huaweicloud.com/bestpractice-idme/idme_bestpractice_0052.html)时创建属性的约束（分块大小）计算待上传文件的分块数量。 - check_code：必填，String类型，文件唯一校验码，即文件的哈希值。 - instance_id：必填，String类型，数据实例的唯一编码。 - username：必填，String类型，用户名称。 - fileId：选填，String类型，文件ID。 - encrypted：选填，Boolean类型，用户名称。 - exaAttr：选填，String类型，是否为扩展属性。 - 0：非扩展属性 - 1：扩展属性 - clsNodeId：选填，String类型，分类节点的ID，用于区分该类型属性是直接绑定到数据模型的扩展属性，还是绑定到分类节点的扩展属性。 如未设置此参数，默认表示该属性为绑定到数据模型的扩展属性。此参数仅在 "exaAttr"为"1"时生效。 - is_direct：选填，Boolean类型，是否为直链上传。 - true：表示通过后端服务直接上传文件流，即直链上传。默认为true。 - false：表示使用OBS/S3预签名URL进行上传，即预签名URL上传。 | | 请求参数 | - Header参数 X-Auth-Token：必填，String类型，用户的token。 - Body参数 fileName：选填，String类型，待上传文件的名称。本参数与file_name参数必须二选一。不能同时为空，且优先级高于file_name。 | | 响应参数 | - result：String类型，调用是否成功。 - SUCCESS：成功 - FAIL：失败 - data：List类型，调用的返回结果。 - isMergedFile：是否合并文件。 - true：合并文件。 - false：不合并文件。 - docId：文档ID。 - fileId：文件ID。 - errors：List类型，异常信息列表。 | - 请求示例 新上传一个101MB的文件"testFile.zip"，由于在添加"文件"类型属性时"分块大小"为默认值（5MB），文件需分为21个分块。 ``` POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/file/startBatchUpload?applicationId=fce01234567d41828cf3473b07fa7ae2&model_name=Craft_File&attribute_name=LargeFiles&file_name=testFile.zip&file_size=103424&chunks=21&check_code=1234567890&instance_id=1&username=XDM_User&is_direct=false X-Auth-Token: ABCDEFG.... ``` - 响应示例 ``` { "result": "SUCCESS", "data": [ { "isMergedFile": false, "docId": "0000018BB1E33DC685E9C0045DFC7291", "fileId": "564032141298503680" } ], "errors": [] } ``` 2. 获取预签名URL。 根据[调用startBatchUpload接口]设置的分块数量，依次执行uploadLargeFile接口。 - 接口相关信息 表2uploadLargeFile接口 | 接口信息 | 说明 | |:---|:---| | URI格式 | ``` POST http://{Endpoint}/rdm_{appID}_app/services/rdm/basic/api/upload/uploadLargeFile ``` - Endpoint：必填，String类型，承载REST服务端点的服务器域名或IP地址。 - appID：必填，String类型，应用ID。 - applicationId：必填，String类型，应用ID。 - modelNumber：必填，String类型，数据模型的编码。 - modelName：必填，String类型，数据模型的英文名称。 - attributeName：必填，String类型，数据模型的属性英文名称。 - docId：必填，String类型，文档ID，即[1]返回的docId。 - fileId：必填，String类型，文件ID，即[1]返回的fileId。 - fileName：必填，String类型，待上传文件的名称。 - checkCode：必填，String类型，文件的唯一校验码，即文件的哈希值。 - chunk：必填，Integer类型，待上传的分块位数。例如您上传第5块分块，填写5。 - storageType：选填，Integer类型，文件的存储类型。 - 0：对象存储。 - 1：BLOB。 - exaAttr：选填，String类型，是否为扩展属性。 - 0：非扩展属性。 - 1：扩展属性。 - clsNodeId：选填，String类型，分类节点的ID，用于区分该类型属性是直接绑定到数据模型的扩展属性，还是绑定到分类节点的扩展属性。 如未设置此参数，默认表示该属性为绑定到数据模型的扩展属性。此参数仅在 "exaAttr"为"1"时生效。 - username：选填，String类型，用户名。 - uploadType：选填，String类型，文件上传类型。 - DIRECT_LINK：直链上传。 - OUTBOUND_LINK：预签名URL上传。 | | 请求参数 | Header参数 X-Auth-Token：必填，String类型，用户的token。 | | 响应参数 | - result：String类型，调用是否成功。 - SUCCESS：成功。 - FAIL：失败。 - data：List类型，调用的返回结果。 - errors：List类型，异常信息列表。 | - 请求示例 根据[请求示例]的文件分块数量，依次执行如下接口。为篇幅起见，这里以上传第1个分块为例。 ``` POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/upload/uploadLargeFile?attributeName=LargeFiles&modelName=Craft_File&applicationId=fce01234567d41828cf3473b07fa7ae2&fileId=564032141298503680&fileName=testFile.zip&checkCode=1234567890&chunk=1&docId=0000018BB1E33DC685E9C0045DFC7291&modelNumber=DM00127285&uploadType=OUTBOUND_LINK X-Auth-Token: ABCDEFG.... ``` - 响应示例 ``` { "result": "SUCCESS", "data": [ { "actualSignedRequestHeaders": { "Host": "xdm-982f57b0e0964361a126cbdeff782c25-cnsouth4.obs.cn-south-4.myhuaweicloud.com:443", "Content-Type": "application/octet-stream;charset=UTF-8" }, "signedUrl": "https://xdm-982f57b0e0964361a126cbdeff782c25-cnsouth4.obs.cn-south-4.myhuaweicloud.com:443/c73f29f8ea664f66b6e0c5df5882ecb8/TestFileDE/Att1/0a16bf70-c018-4e9f-b7b2-1943846d17a4.xdmfl?AccessKeyId=xxx&Expires=1744685806&partNumber=1&uploadId=00000196371F8DFAA18400B4B91C75DB&x-obs-security-token=xxx&Signature=xxx" } ], "errors": [] } ``` 3. 分块上传文件。 - 接口相关信息 表3预签名URL | 接口信息 | 说明 | |:---|:---| | URI格式 | ``` PUT 2获取的预签名URL（即signedUrl参数对应值） ``` | | 请求参数 | Header参数 Content-Type：内容类型。 Body参数 binary（二进制文件流），必填项。 | | 响应参数 | Header参数 Etag：被请求变量的实体值。 | - 请求示例 ``` PUT https://xdm-982f57b0e0964361a126cbdeff782c25-cnsouth4.obs.cn-south-4.myhuaweicloud.com:443/c73f29f8ea664f66b6e0c5df5882ecb8/TestFileDE/Att1/0a16bf70-c018-4e9f-b7b2-1943846d17a4.xdmfl?AccessKeyId=xxx&Expires=1744685806&partNumber=1&uploadId=00000196371F8DFAA18400B4B91C75DB&x-obs-security-token=xxx&Signature=xxx Content-Type: application/octet-stream;charset=UTF-8 Binary File（二进制文件流） ``` - 响应示例 ``` Etag: "e316ff262e7ad4461101357703f30ed2" ``` 4. 确认分块文件上传已完成。 - 接口相关信息 表4confirm接口 | 接口信息 | 说明 | |:---|:---| | URI格式 | ``` POST http://{Endpoint}/rdm_{appID}_app/services/rdm/basic/api/upload/v1/confirm ``` - Endpoint：必填，String类型，承载REST服务端点的服务器域名或IP地址。 - appID：必填，String类型，应用ID。 | | 请求参数 | Header参数 X-Auth-Token：必填，String类型，用户的token。 Body参数 - chunk：必填，int类型，当前分段数。 - chunk_file_size：必填，int类型，分块文件大小。 - doc_id：必填，String类型，文档ID，即[1]返回的docId。 - e_tag：必填，String类型，被请求变量的实体值，即[3]返回的响应头Etag。 - file_id：必填，String类型，文件ID。 - file_name：必填，String类型，文件名称。 | | 响应参数 | - result：String类型，调用是否成功。 - SUCCESS：成功。 - FAIL：失败。 - data：List类型，调用的返回结果。 - fileSize：文件的大小。 - fileId：文件ID。 - errors：List类型，异常信息列表。 | - 请求示例 ``` POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/upload/v1/confirm X-Auth-Token: ABCDEFG.... { "doc_id": "ZTU3ODA2Y2ItN2VlYy00ZTQ4LWJmNDUtOGI1YTMxZGVjMzg4LjViYzBkMWUxLWZiMmMtNGJlNS1iZDhmLThkMzBkN2VmMDdmZA", "file_id": "753573461103742976", "chunk": 4, "file_name": "test.tar", "chunk_file_size": 6410240, "e_tag": "e316ff262e7ad4461101357703f30ed2" } ``` - 响应示例 ``` { "result": "SUCCESS", "data": [], "errors": [] } ``` 5. 分块合并。 - 接口相关信息 表5mergeFiles接口 | 接口信息 | 说明 | |:---|:---| | URI格式 | ``` POST http://{Endpoint}/rdm_{appID}_app/services/rdm/basic/api/file/mergeFiles ``` - Endpoint：必填，String类型，承载REST服务端点的服务器域名或IP地址。 - appID：必填，String类型，应用ID。 - applicationId：必填，String类型，应用ID。 - modelName：必填，String类型，数据模型的英文名称。 - attributeName：必填，String类型，数据模型的属性英文名称。 - docId：必填，String类型，文档ID，即[1]返回的docId。 - fileId：必填，String类型，文件ID，即[1]返回的fileId。 - fileName：必填，String类型，待上传文件的名称。 - checkCode：必填，String类型，文件的唯一校验码，即文件的哈希值。 - instanceId：选填，String类型，数据实例的唯一编码。 - exaAttr：选填，String类型，是否为扩展属性。 - 0：非扩展属性。 - 1：扩展属性。 - clsNodeId：选填，String类型，分类节点的ID，用于区分该类型属性是直接绑定到数据模型的扩展属性，还是绑定到分类节点的扩展属性。 如未设置此参数，默认表示该属性为绑定到数据模型的扩展属性。此参数仅在 "exaAttr"为"1"时生效。 | | 请求参数 | Header参数 X-Auth-Token：必填，String类型，用户的token。 | | 响应参数 | - result：String类型，调用是否成功。 - SUCCESS：成功。 - FAIL：失败。 - data：List类型，调用的返回结果。 - fileSize：文件的大小。 - fileId：文件ID。 - errors：List类型，异常信息列表。 | - 请求示例 ``` POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/file/mergeFiles?applicationId=fce01234567d41828cf3473b07fa7ae2&modelNumber=DM00127285&modelName=Craft_File&attributeName=LargeFiles&fileName=testFile.zip&checkCode=1234567890&docId=0000018BB1E33DC685E9C0045DFC7291&exaAttr=0&fileId=564032141298503680 X-Auth-Token: ABCDEFG.... ``` - 响应示例 ``` { "result": "SUCCESS", "data": [ { "fileSize": "103424", "fileId": "564032141298503680" } ], "errors": [] } ```