更新时间:2025-06-23 GMT+08:00
分享

使用预签名URL分块上传文件

操作场景

工业数字模型驱动引擎-数据建模引擎(xDM Foundation,简称xDM-F)可以将待上传的文件分成多个分块分别上传,上传完成后再调用“file_mergeFiles”接口将这些分块合并成一个对象存储至某个数据模型中。完成文件的分块上传后,可在调用数据实例的创建/更新接口时,将文件与该数据实例进行关联,从而实现对象化管理文件。

本文仅指导您如何通过API接口,采用预签名URL的方式分块上传文件至对象存储(OBS/S3)服务。预签名URL上传通过后端生成临时访问凭证,客户端直接与对象存储服务交互,既保证了安全性又提高了上传效率。关于如何创建/更新数据实例的接口请参见全量数据服务

操作流程

  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. 闪传文件。

    如果您已上传某个文件,在上传该文件时,您只需执行本步骤即可完成文件上传。

    • 接口相关信息
      表1 startBatchUpload接口

      接口信息

      说明

      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类型,待上传文件的分块数量。您可以根据构建数据模型时创建属性的约束(分块大小)计算待上传文件的分块数量。
      • 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接口。
    • 接口相关信息
      表2 uploadLargeFile接口

      接口信息

      说明

      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. 确认分块文件上传已完成。

    • 接口相关信息
      表4 confirm接口

      接口信息

      说明

      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/apiupload/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. 分块合并。

    • 接口相关信息
      表5 mergeFiles接口

      接口信息

      说明

      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": []
      }

相关文档