Upload files
To upload files to File Service, an upload object needs to be created. The upload object includes the file name, parent id, and whether the file is a multipart file. The upload object will return an upload URL that can be used to upload the file content.
Files can be uploaded as a single part or in multiple parts.
- Singlepart - Files are uploaded in a single upload. This is a basic file upload.
- Multipart - Files are divided into chunks for resumable uploads and to allow faster uploads for low-bandwidth connections. After each part is loaded, the complete action merges the parts back into a single file.
Limitations
Section titled “Limitations”- The overall size of any file upload may not exceed 5 TB.
Name of the file has the following restrictions
- Name cannot begin with
/ - Length should be less than 255 characters
- Name should not be reserved keywords like
con,nul,prn,aux,?,<,>,*,|,. - Name also should not be
comorlptfollowed by digits 1 to 9 (e.g,com1tocom9andlpt1tolpt9)
Upload URLs
Section titled “Upload URLs”Each upload url should only be used once (except in the case of retrying failed uploads). If several successful uploads are executed against the same upload url, content from one of the uploads will be randomly selected for permanent storage.
By default, upload URLs are valid for 60 minutes. The validity period can be customized by setting the urlDuration query parameter. The url duration may be between five minutes(5m) and seven days(7d).
NOTE
The permissions check for uploads occurs during the create upload request. There is no check when the content is uploaded using the pre-signed url.
Prerequisites
Section titled “Prerequisites”- A space should be created. To know more about creating a space refer here
Singlepart
Section titled “Singlepart”Limitations
Section titled “Limitations”- The maximum file size for a singlepart upload is 5 GB.
1. Create a new upload file object
Section titled “1. Create a new upload file object”Request
Section titled “Request”POST {baseUrl}/spaces/{spaceId}/uploads-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
-
BODY:
name- Name of fileparentId- Parent id for the file where it needs to be created
Response
Section titled “Response”After the upload operation is completed, the JSON response includes the id value for the file and URLs for file upload.
2. Upload file content
Section titled “2. Upload file content”Perform a PUT operation with the upload URL from the POST call in the previous step.
Request
Section titled “Request”PUT {UPLOAD URL}- BODY:
{File Content}
3. Validate the upload
Section titled “3. Validate the upload”Run a GET upload API call to check the job status. The value should be COMPLETED.
Request
Section titled “Request”GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
Response
Section titled “Response”Multipart
Section titled “Multipart”Limitations
Section titled “Limitations”- The minimum size for a multipart upload part is 5 MB (except for the last part, which may be less than 5 MB).
- The maximum part size is 5 GB.
- The number of parts of a multipart upload cannot exceed 10,000.
Note
- If the cloud provider for the space is AWS, the multipart upload request will return an ETag value, which must be included, along with the corresponding part identifier, in the multipart upload completion request.
- If the cloud provider for the space is Azure, ETag value might be similar for the all part uploads and tags has no effect.
1. Create a new upload file object
Section titled “1. Create a new upload file object”Request
Section titled “Request”POST {baseUrl}/spaces/{spaceId}/uploads-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
-
BODY:
name- Name of fileparentId- Parent id for the file where it needs to be createdmultipart- Boolean value to indicate if the file needs to be created as a multipart file
Response
Section titled “Response”After the upload operation is completed, the JSON response includes the id value for the file and URLs for file upload.
2. Upload file parts
Section titled “2. Upload file parts”There is a query string parameter “partNumber=*” in the upload URL from the previous request. Substitute the “*” value with the number of the current part that needs to be uploaded.
Separate the file into parts, and upload each to the URL with parameter value substituted. Part numbering starts with "1" (not zero).
Request
Section titled “Request”PUT {UPLOAD URL}- BODY
{PART DATA}Response will include an ETag in the header. Keep track of the ETag responses for each upload.
3. Run complete multipart API call
Section titled “3. Run complete multipart API call”After all parts are uploaded, run the API call to complete the multipart upload. Use the upload id from the first step.
Request
Section titled “Request”PATCH /spaces/{spaceId}/uploads/{uploadId}-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
-
BODY:
etag- ETag generated from awspartNumber- Part number of the uploaded file
Response
Section titled “Response”4. Validate the upload
Section titled “4. Validate the upload”Run a GET upload API call to check the job status. The value should be COMPLETED.
Request
Section titled “Request”GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
Response
Section titled “Response”Package Upload
Section titled “Package Upload”Limitations
Section titled “Limitations”- Support files will always be single-part uploads. Multipart is not supported.
- Support files may not be filesets.
- Maximum of 10 support files can be linked to a parent file.
- Copy links is not supported for package upload
1. Create a new package upload object
Section titled “1. Create a new package upload object”Request
Section titled “Request”POST {baseUrl}/spaces/{spaceId}/uploads-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
-
BODY:
name- Name of fileparentId- Parent id for the file where it needs to be createdresources- List of support files resources that are part of the main file
Response
Section titled “Response”After the upload operation is completed, the JSON response includes the id value for the file and URLs for file upload for both main file and list of support files.
2. Upload file content
Section titled “2. Upload file content”Perform a PUT operation with the upload URL from the POST call in the previous step.
Request
Section titled “Request”PUT {UPLOAD URL}- BODY:
{File Content}
3. Validate the upload
Section titled “3. Validate the upload”Run a GET upload API call to check the job status. The value should be COMPLETED once main file and all support file contents are uploaded.
Request
Section titled “Request”GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}-
HEADER:
- Authorization:
Bearer {tid token}
- Authorization:
Response
Section titled “Response”To know more about the upload file API refer here.