IoT File Service – Multi Part Operations¶

Multi Part Upload¶

Multi part upload is performed by the following steps:

1. Initiate multi part upload
2. Upload file parts
3. Complete multi part upload

Initiate the File Upload¶

Initiate a multi part upload by providing the upload=start query parameter to the upload request. This initiation request and does not accept any file part. The example request below initiates a multi part upload for a file exampleFile in the sub directory optionalDirectory:

{{gatewayUrl}}/api/iotfile/v3/files/{{entityId}}/optionalDirectory/exampleFile?upload=start

Upload File Parts¶

Specify the part number as a query parameter when uploading file parts. The following rules apply for file parts:

• Part numbers from 1 to 1,000 are accepted and can be uploaded asynchronously.
• When all parts are uploaded, their part numbers must be sequential.
• Each part must have a minimum size of 5 MB.
• Parts belonging to incomplete file uploads are automatically deleted after 2 days.
• If a part number is used twice, the existing part is overwritten.

{{gatewayUrl}}/api/iotfile/v3/files/{{entityId}}/optionalDirectory/exampleFile?part=1

Complete the Upload¶

Provide the request parameter upload=complete to complete a multi part upload. The example below completes a multi part upload for a file exampleFile in the sub directory optionalDirectory. The complete request accepts a file part that is smaller than the minimum allowed part size and treats it as the final part.

{{gatewayUrl}}/api/iotfile/v3/files/{{entityId}}/optionalDirectory/exampleFile?upload=complete

Abort a Multi Part Upload¶

Abort a multi part upload using the upload=abort parameter. All information for the selected multi part upload is physically deleted.

{{gatewayUrl}}/api/iotfile/v3/files/{{entityId}}/optionalDirectory/exampleFile?upload=abort

Multi Part Update¶

Specify the If-Match header parameter in each request of the Multi Part Upload to update an existing file using multi part upload.

List Current Multi Part Uploads¶

List the current file parts for a specified file using a GET request to the filelist endpoint.

Each item in the file part list contains:

• objectKey: The file key consisting of {tenant storage prefix}/{entityId}/{filepath}
• partNo: The specified multi part number
• created: UTC time the part was uploaded displayed in milliseconds

Sample request:

{{gatewayUrl}}/api/iotfile/v3/fileslist/{{entityId}}/optionalDirectory/exampleFile

Sample response:

[
    {
        "objectKey": "iotteni/00189ab4c65243bb9d77f17332dd570a/optionalDirectory/exampleFile",
        "partNo": 1,
        "created": 1540509915000
    },
    {
        "objectKey": "iotteni/00189ab4c65243bb9d77f17332dd570a/optionalDirectory/exampleFile",
        "partNo": 2,
        "created": 1540509931000
    }
]

Multi Part Download¶

Sample Request:

  gatewayUrl/api/iotfile/v3/files/entityId/optionalDirectory/exampleFile

You need to specify 'range' in the header with value as 'bytes=200-400'.

Sample Response:

  206 Partial content of the file

Download a portion of an existing file by using the Range parameter and specifying the byte range to download, e.g.: bytes=1-100

Bulk Delete¶

Delete multiple files within the file storage for any specified asset. In one request, a maximum of 3 months of file data can be deleted.

Request to delete file¶

Sample Request:

{
  "assets": [
    {
      "id": "089336872ce342aba1a847f53d515dc7",
      "path": "/logs",
      "timeFrom": "2020-03-01T09:12:28.110Z",
      "timeTo": "2020-06-01T09:12:28.110Z"
    }
  ]
}

The id is a mandatory field and cannot be null or empty. The timeFrom and timeTo parameters are optional. The range from timeFrom and timeTo should not exceed 3 months. If these parameters are not provided then, the files created before 90 days of the submission of this request, will be deleted.

Sample Response:

{
  "id": "a87d8d68-9d6d-42f8-9eb9-8899fa90bb3f",
  "timestamp": "2020-06-08T09:12:28Z",
  "status": "IN_PROGRESS"
}

In addition, it is possible to view the status of the bulk delete operation.

Sample Response:

{
  "id": "a87d8d68-9d6d-42f8-9eb9-8899fa90bb3f",
  "timestamp": "2020-06-08T09:12:28Z",
  "status": "COMPLETED_WITH_ERRORS",
  "assets": [
    {
      "id": "089336872ce342aba1a847f53d515dc7",
      "path": "/",
      "timeFrom": "2020-03-01T09:12:28.110Z",
      "timeTo": "2020-06-01T09:12:28.110Z",
      "status": "FAILED",
      "filesToBeDeleted": 500,
      "filesDeleted": 400,
      "filesRemaining": 100,
      "error": "Something went wrong while deleting some files"
    }
  ]
}

It is also possible to get all the bulk delete operations performed by an environment.

Sample response:

{
  "deleteJobs": [
    {
      "id": "a87d8d68-9d6d-42f8-9eb9-8899fa90bb3f",
      "timestamp": "2020-06-08T09:12:28Z",
      "status": "IN_PROGRESS"
    }
  ]
}