module-storage.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Module: storage</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Module: storage</h1>

    



<section>

<header>
    <h2>
    storage
    </h2>
    
</header>

<article>
    <div class="container-overview">
    
        
<dt>
    <h4 class="name" id="module:storage"><span class="type-signature"></span>(require("storage"))<span class="signature">(options)</span><span class="type-signature"></span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Google Cloud Storage allows you to store data on Google infrastructure. See
the guide on <a href="https://developers.google.com/storage">https://developers.google.com/storage</a> to create a
bucket.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>options</code></td>
            

            <td class="type">
            
                
<span class="param-type">object</span>


            
            </td>

            

            

            <td class="description last"><p>Configuration options.</p>
                <h6>Properties</h6>
                

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>bucketName</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            

            

            <td class="description last"><p>Name of the bucket.</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>keyFilename</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            

            

            <td class="description last"><p>Full path to the JSON key downloaded
    from the Google Developers Console.</p></td>
        </tr>

    
    </tbody>
</table>
            </td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="index.js__.html">storage/index.js</a>, <a href="index.js__.html#line113">line 113</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    
    <h5>Throws:</h5>
    
            

    <div class="param-desc">
    
        if a bucket name isn't provided.
    
    </div>


        

    

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var gcloud = require('gcloud');
var storage = gcloud.storage;
var bucket;

// From Google Compute Engine
bucket = new storage.Bucket({
  bucketName: YOUR_BUCKET_NAME
});

// From elsewhere
bucket = new storage.Bucket({
  bucketName: YOUR_BUCKET_NAME,
  keyFilename: '/path/to/the/key.json'
});</code></pre>

    
</dd>

    

    
        

        
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="index.js__.html">storage/index.js</a>, <a href="index.js__.html#line17">line 17</a>
    </li></ul></dd>
    

    

    

    
</dl>


        
    
    </div>

    

    

    

    

     

    

    

    
        <h3 class="subsection-title">Methods</h3>

        <dl>
            
<dt>
    <h4 class="name" id="copy"><span class="type-signature"></span>copy<span class="signature">(name, metadata, callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Copy an existing file. If no bucket name is provided for the destination
file, the current bucket name will be used.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        
        <th>Attributes</th>
        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>name</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            
                <td class="attributes">
                

                

                
                </td>
            

            

            <td class="description last"><p>Name of the existing file.</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>metadata</code></td>
            

            <td class="type">
            
                
<span class="param-type">object</span>


            
            </td>

            
                <td class="attributes">
                

                

                
                </td>
            

            

            <td class="description last"><p>Destination file metadata object.</p>
                <h6>Properties</h6>
                

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        
        <th>Attributes</th>
        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>name</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            
                <td class="attributes">
                

                

                
                </td>
            

            

            <td class="description last"><p>Name of the destination file.</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>bucket</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            
                <td class="attributes">
                
                    &lt;optional><br>
                

                

                
                </td>
            

            

            <td class="description last"><p>Destination bucket for the file. If none
    is provided, the source's bucket name is used.</p></td>
        </tr>

    
    </tbody>
</table>
            </td>
        </tr>

    

        <tr>
            
                <td class="name"><code>callback</code></td>
            

            <td class="type">
            
                
<span class="param-type">function</span>


            
            </td>

            
                <td class="attributes">
                
                    &lt;optional><br>
                

                

                
                </td>
            

            

            <td class="description last"><p>The callback function.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="index.js__.html">storage/index.js</a>, <a href="index.js__.html#line203">line 203</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    
    <h5>Throws:</h5>
    
            

    <div class="param-desc">
    
        if the destination filename is not provided.
    
    </div>


        

    

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>bucket.copy('filename', {
   bucket: 'destination-bucket',
   name: 'destination-filename'
}, function(err) {});</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="createReadStream"><span class="type-signature"></span>createReadStream<span class="signature">(name)</span><span class="type-signature"> &rarr; {ReadStream}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Create a readable stream to read contents of the provided remote file. It
can be piped to a write stream, or listened to for 'data' events to read a
file's contents.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>name</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            

            

            <td class="description last"><p>Name of the remote file.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="index.js__.html">storage/index.js</a>, <a href="index.js__.html#line251">line 251</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type">ReadStream</span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Create a readable stream and write the file contents to "local-file-path".
var fs = require('fs');

bucket.createReadStream('remote-file-name')
   .pipe(fs.createWriteStream('local-file-path'))
   .on('error', function(err) {});</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="createWriteStream"><span class="type-signature"></span>createWriteStream<span class="signature">(name, metadata<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {stream}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Create a Duplex to handle the upload of a file.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        
        <th>Attributes</th>
        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>name</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            
                <td class="attributes">
                

                

                
                </td>
            

            

            <td class="description last"><p>Name of the remote file to create.</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>metadata</code></td>
            

            <td class="type">
            
                
<span class="param-type">object</span>


            
            </td>

            
                <td class="attributes">
                
                    &lt;optional><br>
                

                

                
                </td>
            

            

            <td class="description last"><p>Optional metadata.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="index.js__.html">storage/index.js</a>, <a href="index.js__.html#line287">line 287</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type">stream</span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Read from a local file and pipe to your bucket.
var fs = require('fs');

fs.createReadStream('local-file-path')
    .pipe(bucket.createWriteStream('remote-file-name'))
    .on('error', function(err) {})
    .on('complete', function(fileObject) {});</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="list"><span class="type-signature"></span>list<span class="signature">(query<span class="signature-attributes">opt</span>, callback)</span><span class="type-signature"></span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>List files from the current bucket.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        
        <th>Attributes</th>