Files

You can use Kinvey to store and retrieve binary files of size up to 5TB. Files can be of any format.

The files are automatically enabled for download using a Content Delivery Network (CDN) for massive scale and performance.

The files API can be accessed via $kinvey.File, which is a $resource definition with extra methods.

Uploading

Uploading to Kinvey is a two-step process. First, you must create a $kinvey.File object and save it with $save(). You can use this object to store the filename, ACLs, and any other metadata having to do with the file you wish to upload. Then, you will upload your file directly to Google Cloud Storage using $upload().

First, create a $kinvey.File object and save it. You may specify any metadata including an _id and a _filename...

var file = new $kinvey.File({
    _filename: 'myFile.txt'
});
file.$save();
// or if you want to specify a MIME type
file.$save('text/plain');

If a filename is not specified, a UUID will be used to populate the _filename property.

Once saved the file object will contain the file's _id and _filename, any other metadata that you submitted, as well as an _uploadURL property containing a URL to which you will upload your file and an _expiresAt property containing the time at which the upload link will expire.

Provided that the upload link is still valid you can now upload the file using $upload(filedata). If you specified a MIME type when you $saveed the file object you must also specify it again now: $upload(filedata, mimeType).

var file = new $kinvey.File({
    _filename: 'myFile.txt'
});
file.$save('text/plain');
file.$promise.then(function() {
    var upload = file.$upload('this is the file contents\r\n', 'text/plain');
    upload.$promise.then(function() {
        $window.alert('file upload complete');
    });
);

Creating publicly-readable files

By default, files uploaded to Google Cloud Storage through $kinvey.File are private. This means that every time you wish to download a file, you must first request it via $kinvey.File, which will generate a signed URL that allows download access only for a limited time.

However, using the $kinvey.File, you may optionally create a publicly-readable file. The download link to this file will be a regular non-signed URL, which will not expire until you delete the file through $kinvey.File or change the file's status to be private again. To create a publicly-readable file, set the _public flag to true.

var file = new $kinvey.File({
    _filename: 'myFile.txt',
    _public: true
});
file.$save('text/plain');
file.$promise.then(function() {
    var upload = file.$upload('this is the file contents\r\n', 'text/plain');
    upload.$promise.then(function() {
        $window.alert('file upload complete');
    });
);

Once you have uploaded or updated a file in this way, follow the normal instructions to download the file. The _downloadURL property will contain a non-signed, publicly-accessible URL, which will not expire until you delete the file through Kinvey.

Fetching file records

Kinvey's records of the files you have uploaded can be fetched and queried like any other collection. You can use $kinvey.File.get and $kinvey.File.query` to access the collection. Please refer to the documentation for Get and Query in the Data Store for more information.

Downloading

Downloading from Kinvey is again a two-step process. First, you must use $kinvey.File.get in order to retrieve the File object, as well as any metadata you stored when creating the file. Then, you will download your file directly using $download().

First, use get or query to fetch your file record(s). The file API supports complex queries; for more information, please refer to the querying guide.

The response from $kinvey will contain the file _id and _filename, any other metadata that you submitted, as well as an _downloadURL property containing a URL from which you will download your file, and if the file is not public, an _expiresAt property containing the time at which the download link will expire.

Next, call $download() on the File object to retrieve the file data.

var file = $kinvey.File.get({_id: 'fileId'});
file.$promise.then(function() {
    var download = file.$download();
    download.$promise.then(function(filedata) {
        $window.alert('file download complete');
        console.log('filedata: '+filedata);
    });
});

Deleting

Hosted files can be deleted by calling $kinvey.File.delete.

$kinvey.File.delete({_id: 'fileId'});

// or

var file = $kinvey.File.get({_id: 'fileId'});
file.$promise.then(function() {
    file.$delete();
});