Skip to content

Latest commit

 

History

History
279 lines (200 loc) · 9.85 KB

storage.md

File metadata and controls

279 lines (200 loc) · 9.85 KB

Using the Rackspace Storage provider

Creating a client is straight-forward:

  var rackspace = pkgcloud.storage.createClient({
    provider: 'rackspace', // required
    username: 'your-user-name', // required
    apiKey: 'your-api-key', // required
    region: 'IAD', // required, regions can be found at
    // http://www.rackspace.com/knowledge_center/article/about-regions
    useInternal: false // optional, use to talk to serviceNet from a Rackspace machine
  });

Learn about more options for creating clients in the Openstack storage provider. region parameter can be any Rackspace Region.

Container Model

A Container for Rackspace has following properties:

{
  name: 'my-container',
  count: 1, // number of files in your container
  bytes: 12345, // size of the container in bytes
  metadata: { // key value pairs for the container
    // ...
  }
}

File Model

A File for Rackspace has the following properties:

{
  name: 'my-file',
  container:  'my-container', // may be an instance of container if provided
  size: 12345, // size of the file in bytes
  contentType: 'plain/text' // Mime type for the file
  lastModified: Fri Dec 14 2012 10:16:50 GMT-0800 (PST), // Last modified date of the file
  etag: '1234567890abcdef', // MD5 sum of the file
  metadata: {} // optional object metadata
}

Container APIs

Container API Details

For all of the container methods, you can pass either an instance of container or the container name as container. For example:

client.getContainer('my-container', function(err, container) { ... });

This call is functionally equivalent to:

var myContainer = new Container({ name: 'my-container' });

client.getContainer(myContainer, function(err, container) { ... });

client.getContainers(function(err, containers) { })

Retreives the containers for the current client instance as an array of container

client.getContainer(container, function(err, container) { })

Retrieves the specified container from the current client instance.

client.createContainer(container, function(err, container) { })

Creates a new container with the name from argument container. You can optionally provide metadata on the request:

client.createContainer({
 name: 'my-container',
 metadata: {
  brand: 'bmw',
  model: '335i'
  year: 2009
 }}, function(err, container) {
  // ...
 })

client.destroyContainer(container, function(err, result) { })

Removes the container from the storage account. If there are any files within the container, they will be deleted before removing the container on the client. result will be true on success.

client.updateContainerMetadata(container, function(err, container) { })

Updates the metadata on the provided container . Currently, the updateContainer method only adds new metadata fields. If you need to remove specific metadata properties, you should call client.removeContainerMetadata(...).

container.metadata.color = 'red';
client.updateContainerMetadata(container, function(err, container) {
  // ...
})

client.removeContainerMetadata(container, metadataToRemove, function(err, container) { })

Removes the keys in the metadataToRemove object from the stored container metadata.

client.removeContainerMetadata(container, { year: false }, function(err, c) {
  // ...
});

File APIs

File API Details

For all of the file methods, you can pass either an instance of container or the container name as container. For example:

client.getFile('my-container', 'my-file', function(err, file) { ... });

This call is functionally equivalent to:

var myContainer = new Container({ name: 'my-container' });

client.getFile(myContainer, 'my-file', function(err, file) { ... });

client.upload(options)

Returns a writableStream. Upload a new file to a container. writableStream will emit success on completion of the upload, and will emit error on any failure. Function for success is function(file) { ... } where file is a file model

To upload a file, you need to provide an options argument:

var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file
    contentType: 'application/json', // optional mime type for the file, will attempt to auto-detect based on remote name
    size: 1234 // size of the file
};
  var readStream = fs.createReadStream('a-file.txt');
  var writeStream = client.upload({
    container: 'a-container',
    remote: 'remote-file-name.txt'
  });

  writeStream.on('error', function(err) {
    // handle your error case
  });

  writeStream.on('success', function(file) {
    // success, file will be a File model
  });

  readStream.pipe(writeStream);

client.download(options, function(err, file) { })

Returns a readable stream. Download a file from a container.

To download a file, you need to provide an options argument:

var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file

    // optional, either stream or local
    stream: myStream, // any instance of a writeable stream
    local: '/path/to/local/file' // the path to a local file to write to
};

You need not provide either stream or local. client.download returns a readable stream, so you can simply pipe it into your writeable stream. For example:

var fs = require('fs'),
    pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

var myFile = fs.createWriteStream('/my/local/file');

client.download({
    container: 'my-container',
    remote: 'my-file'
}, function(err, result) {
    // handle the download result
})).pipe(myFile);

You could also download to a local file via the local property on options:

var pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

client.download({
    container: 'my-container',
    remote: 'my-file',
    local: '/path/to/my/file'
}, function(err, result) {
    // handle the download result
});

This is functionally equivalent to piping from an fs.createWriteStream, but has a simplified calling convention.

client.getFile(container, file, function(err, file) { })

Retrieves the specified file details in the specified container from the current client instance.

client.getFiles(container, [options], function(err, files) { })

Retrieves an array of file for the provided container in alphabetical order.

The following option properties are currently supported:

  • limit an integer which limits the number of returned files
  • marker a string used to specify the start of the listing

By default, without the limit option being specified, a single request is made and a maximum of 10,000 files will be returned.

If limit is set to a be greater than 10,000, requests will be made until the limit is reached or all files in the container have been retrieved.

Set limit to the global Infinity to ensure a complete listing of the container.

client.removeFile(container, file, function(err, result) { })

Removes the provided file from the provided container.

client.updateFileMetadata(container, file, function(err, file) { })

Updates the file metadata in the the provided container.

File metadata is completely replaced with each call to updateFileMetadata. This is different than container metadata. To delete a property, just remove it from the metadata attribute on the File and call updateFileMetadata.

file.metadata = {
 campaign = '2011 website'
};

client.updateFileMetadata(file.container, file, function(err, file) {
  // ...
});