AdmiralCloud offers several ways to import media items.

General

Our modern upload approach works with temporary credentials that allow you a time limit upload to a given S3 location/key. The credentials are only valid for the key and bucket provided with those credentials.

Calculation of the expire time

The temporary credentials’ expire time is calculated based on the expected file size. They are at least 15 minutes and at max 12 hours valid.

If your upload is not finished at the time of the expiration time and you are using multi-part uploads, uploading further parts will fail. Make sure your app handles expiration time and requests new credentials in this case.

Upload methods

File Upload

If you want to upload a file via browser or directly from an application (NodeJS, Swift, PHP, Java) you have to use a 3-step process

Step 1 – Prepare the upload

Use the S3.createDocument call to prepare the AdmiralCloud API to be ready to receive files. A simple call might look like this

// REQUEST
POST /v5/s3/createUpload
{
        "uploadId": "587acf71-20b3-43aa-9fe3-0d792236ee00",
	"payload": [{
		"type": "image",
		"fileName": "file1-20200824-1347",
		"originalFileExtension": "jpg"
                "fileSize": 7217440
	}]
}

// RESPONSE
{
    "uploadId": "587acf71-20b3-43aa-9fe3-0d792236ee00",
    "processed": [
        {
             "type": "image",
	    "fileName": "file1-20200824-1347",
            "originalFileExtension": "jpg"
            "fileSize": 7217440
            "bucket": "s3-bucket-for-upload",
            "region": "eu-central-1",
            "s3Key": "s3-key-for-upload",
            "credentials": {
                "AccessKeyId": "ABC",
                "SecretAccessKey": "secret-for-upload",
                "SessionToken": "session token",
                "Expiration": "2021-07-04T09:15:14.000Z"
            }
        }
    ],
    "error": [],
    "transferAcceleration": false
}

Create an UUIDv4 as uploadId to identify upload batches later and send it with the request. If you don’t send an uploadId, one it automatically created and assigned to this request.

The response contains the information for your upload in the same order as you have sent it with your request.

For more infos of properties, parameters and options please visit S3 Controller

Step 2 – Upload your files

Now, use the AWS SDK for your programming language to upload your files to AWS S3 file storage. Use the credentials given in our API response to upload that file. Please note that credentials might be the same for more than one or even all files, depending on type and size. Make sure to always use the correct credentials for every file.

Step 3 – Upload complete

If all files from the batch you requested in step 1 are uploaded, make sure to inform the API that the upload (batch) has been completed. If you forget to make this call, the files will still be available on AdmiralCloud, however notifications and other automated events might not be created.

To make the call simply use the the uploadId from the response in step 1:

POST /v5/s3/uploadComplete
{
    "uploadId": "587acf71-20b3-43aa-9fe3-0d792236ee00"
}

URL Upload

TBC

Dropsite Upload

How to upload via Dropsite

LiveStream uploads

TBC

Additional Information

Transfer Acceleration

You can accelerate the upload process “typically in the range of 50% to 500% for cross-country transfer of larger objects, but can go ever higher under certain conditions” (source AWS).

In order to activate transfer acceleration you have to use a custom media bucket with your AdmiralCloud account. Please contact our sales department for further information on pricing of this feature.

Did you know? You can also use your own AWS account and just provide IAM credentials. This way the data is under your control and AdmiralCloud only gets access to it.

In order to use a custom media bucket with S3 transfer acceleration we will then update your internalConfiguration configuration with a providerConfiguration:

[{
    accessKeyId: 'AWS-IAM-ACCESSKEY',
    provider: 'aws123',
    bucket: 'my-accelerated-bucket',
    region: 'eu-central-1',
    type: 'upload',
    transferAcceleration': true
}]

You must then activate this providerConfig for a given user by updating the user’s settings with the name of the provider configuration (in this case ‘aws123’

{
  settings: {
    providerConfig: 'aws1123'
  }
}