Skip to content
This repository has been archived by the owner on Oct 25, 2022. It is now read-only.

Latest commit

 

History

History
268 lines (193 loc) · 9.12 KB

storage.md

File metadata and controls

268 lines (193 loc) · 9.12 KB
Raw

Using the OpenStack Storage provider

Creating a client is straight-forward:

  var openstack = pkgcloud.storage.createClient({
    provider: 'openstack', // required
    username: 'your-user-name', // required
    password: 'your-password', // required
    authUrl: 'your identity service url' // required
  });

Note: Due to variances between OpenStack deployments, you may or may not need a region option.

Learn about more options for creating clients in the OpenStack storage provider.

Container Model

A Container for OpenStack 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 OpenStack 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.openstack.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.openstack.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, function(err, files) { })

Retreives an array of file for the provided 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) {
  // ...
});