Upload and download a large data
If a device collects large amounts of data, the data can be uploaded into the Tracking Backend via the Tracking API as a large data blob. The user can later download the uploaded data from the Tracking API. The data upload is done by a device, and the data download is done by the user.
Prerequisites
Log in device
Log in the device. This will return a deviceToken
required for the data upload requests.
Log in user
Log in the user. This will return a user access token: userToken
required for the subsequent requests.
Upload a large data
Upload process has three phases: creating a new upload, uploading parts of the data and, once all the data parts have been uploaded, completing the data upload.
Create a new large data upload
curl -X POST \
'https://tracking.api.here.com/largedata/v4' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {deviceToken}' \
-d '{
"name":"My large data",
"description":"Description for my large data"
}'
This will return dataId
which is the identifier for the large data.
{
"dataId": "DATA-dummyDataId"
}
Check the status of the large data upload creation
When the first large data upload for a project was created, it will take some time to setup the data storage. Make the following request to get metadata for the large data and check the upload creation status:
curl -X GET \
'https://tracking.api.here.com/largedata/v4/{dataId}/metadata' \
-H 'Authorization: Bearer {userToken}'
The metadata contains information such as a status of the upload, number of parts and a size of the whole large data:
{
"dataId": "DATA-dummyDataId",
"trackingId": "HERE-dummyHereId",
"name": "My large data",
"description": "Description for my large data",
"numberOfParts": 2,
"size": 6,
"status": "completed",
"createdAt": "2021-06-24T08:27:53.933Z",
"completedAt": "2021-06-24T08:29:08.966Z"
}
Only when the status is no longer preparing
, the user can continue with uploading the data parts. Otherwise, in case the data storage for the upload is still being created, an upload data part request will return 409 error code.
Upload a part of a large data
In the example below a data file called mylargedata1.bin
is uploaded as part 1, and then another file called mylargedata2.bin
is uploaded as part 2. This can be done in parallel. If the user uses the same part number in a subsequent request, the new upload will override the old one.
curl -X PUT \
'https://tracking.api.here.com/largedata/v4/{dataId}/parts/1' \
-H 'Content-Type: application/octet-stream' \
-H 'Authorization: Bearer {deviceToken}' \
--data-binary '@mylargedata1.bin'
curl -X PUT \
'https://tracking.api.here.com/largedata/v4/{dataId}/parts/2' \
-H 'Content-Type: application/octet-stream' \
-H 'Authorization: Bearer {deviceToken}' \
--data-binary '@mylargedata2.bin'
Complete a large data upload
Once the user has successfully uploaded all the parts of the large data, the upload must be completed. Once the upload has been completed, it is no longer possible to override parts or upload new parts of the large data.
curl -X POST \
'https://tracking.api.here.com/largedata/v4/{dataId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {deviceToken}'
Download large data
Suppose that the first part of our example contained a word my
and the second part contained a word data
.
curl -X GET \
'https://tracking.api.here.com/largedata/v4/{dataId}/data' \
-H 'Accept: application/json, application/octet-stream' \
-H 'Authorization: Bearer {userToken}'
This will return a word mydata
, as the part 1 my
and the part 2 data
have been concatenated.
curl -X GET \
'https://tracking.api.here.com/largedata/v4/{dataId}/data?offset=1&count=3' \
-H 'Accept: application/json, application/octet-stream' \
-H 'Authorization: Bearer {userToken}'
This will return a word yda
as the offset
is 1 and the count
is 3. The offset
moves the starting point forward by the specified number of bytes and the count
tells how many bytes of data to get from the offset
onwards.
Delete a large data
curl -X DELETE \
'https://tracking.api.here.com/largedata/v4/{dataId}' \
-H 'Authorization: Bearer {userToken}'
The user can get a detailed information and the upload status on each of the large data parts.
curl -X GET \
'https://tracking.api.here.com/largedata/v4/{dataId}/parts' \
-H 'Authorization: Bearer {userToken}'
{
"limit": 100,
"count": 2,
"items": [
{
"partNumber": 1,
"size": 2,
"md5": "6864f389d9876436bc8778ff071d1b6c",
"status": "completed"
},
{
"partNumber": 2,
"size": 4,
"md5": "8d777f385d3dfec8815d20f7496026dc",
"status": "completed"
}
]
}
The device trackingId
needs to be specified in the request path to get metadata for all the large data objects for a given device.
curl -X \
GET 'https://tracking.api.here.com/largedata/v4/devices/{trackingId}/metadata' \
-H 'Authorization: Bearer {userToken}'
{
"limit": 100,
"count": 1,
"items": [
{
"dataId": "DATA-dummyDataId",
"trackingId": "HERE-dummyHereId",
"name": "My large data",
"description": "Description for my large data",
"numberOfParts": 2,
"size": 6,
"status": "completed",
"createdAt": "2021-06-24T08:27:53.933Z",
"completedAt": "2021-06-24T08:29:08.966Z"
}
]
}