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.
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
// ...
}
}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
}client.getContainers(function(err, containers) { })client.getContainer(container, function(err, container) { })client.createContainer(container, function(err, container) { })client.destroyContainer(container, function(err, result) { })client.updateContainerMetadata(container, function(err, container) { })client.removeContainerMetadata(container, metadataToRemove, function(err, container) { })
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) { ... });Retreives the containers for the current client instance as an array of container
Retrieves the specified container from the current client instance.
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) {
// ...
})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.
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) {
// ...
})Removes the keys in the metadataToRemove object from the stored container metadata.
client.removeContainerMetadata(container, { year: false }, function(err, c) {
// ...
});client.upload(options)client.download(options, function(err, file) { })client.getFile(container, file, function(err, file) { })client.getFiles(container, [options], function(err, file) { })client.removeFile(container, file, function(err, result) { })client.updateFileMetadata(container, file, function(err, file) { })
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) { ... });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);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.
Retrieves the specified file details in the specified container from the current client instance.
Retrieves an array of file for the provided container in alphabetical order.
The following option properties are currently supported:
limitan integer which limits the number of returned filesmarkera 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.
Removes the provided file from the provided container.
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) {
// ...
});