@google-cloud/storage 3.0.0

Properties

acl
Bucket

Channel
File

acl

Methods

bucket(name[, options])
channel(id, resourceId)

createBucket(name[, metadata][, callback])
getBuckets([query][, callback])

getServiceAccount([options][, callback])

new Storage([options])

Constructs the Storage client.

Examples

<caption>Create a client that uses Application Default Credentials
(ADC)</caption> const {Storage} = require('@google-cloud/storage'); const
storage = new Storage();

Create a client with explicit credentials

storage');/storage');
const storage = new Storage({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Parameter

Name	Type	Optional	Description
options		Yes	Configuration options.

See also: Cloud Storage overview; Access Control

Properties

static

acl object

Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share objects with other users and allow other users to access your buckets and objects.

This object provides constants to refer to the three permission levels that can be granted to an entity:

gcs.acl.OWNER_ROLE - ("OWNER")
gcs.acl.READER_ROLE - ("READER")
gcs.acl.WRITER_ROLE - ("WRITER")

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const albums = storage.bucket('albums');

//-
// Make all of the files currently in a bucket publicly readable.
//-
const options = {
  entity: 'allUsers',
  role: storage.acl.READER_ROLE
};

albums.acl.add(options, function(err, aclObject) {});

//-
// Make any new objects added to a bucket publicly readable.
//-
albums.acl.default.add(options, function(err, aclObject) {});

//-
// Grant a user ownership permissions to a bucket.
//-
albums.acl.add({
  entity: 'user-useremail@example.com',
  role: storage.acl.OWNER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
albums.acl.add(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Properties

Name	Type	Optional	Description
OWNER_ROLE	string
READER_ROLE	string
WRITER_ROLE	string

See also: About Access Control Lists

static

Bucket Constructor

Bucket class.

See also: Bucket

static

Channel Constructor

Channel class.

See also: Channel

static

File Constructor

File class.

See also: File

acl

Reference to Storage.acl.

See also: Storage.acl

Methods

bucket(name[, options]) → Bucket

Get a reference to a Cloud Storage bucket.

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const albums = storage.bucket('albums');
const photos = storage.bucket('photos');

Parameters

Name Type Optional Description

name

string

Name of the bucket.

options

object

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
kmsKeyName	string	Yes	A Cloud KMS key that will be used to encrypt objects inserted into this bucket, if no encryption method is specified.
userProject	string	Yes	User project to be billed for all requests made from this Bucket object.

See also: Bucket
Returns: Bucket

channel(id, resourceId) → Channel

Reference a channel to receive notifications about changes to your bucket.

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const channel = storage.channel('id', 'resource-id');

Parameters

Name	Type	Optional	Description
id	string		The ID of the channel.
resourceId	string		The resource ID of the channel.

See also: Channel
Returns: Channel

createBucket(name[, metadata][, callback]) → Promise containing CreateBucketResponse

Create a bucket.

Cloud Storage uses a flat namespace, so you can't create a bucket with a name that is already in use. For more information, see Bucket Naming Guidelines.

Examples

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const callback = function(err, bucket, apiResponse) {
  // `bucket` is a Bucket object.
};

storage.createBucket('new-bucket', callback);

//-
// Create a bucket in a specific location and region. <em>See the <a
// href="https://cloud.google.com/storage/docs/json_api/v1/buckets/insert">
// Official JSON API docs</a> for complete details on the `location`
option.
// </em>
//-
const metadata = {
  location: 'US-CENTRAL1',
  regional: true
};

storage.createBucket('new-bucket', metadata, callback);

//-
// Create a bucket with a retention policy of 6 months.
//-
const metadata = {
  retentionPolicy: {
    retentionPeriod: 15780000 // 6 months in seconds.
  }
};

storage.createBucket('new-bucket', metadata, callback);

//-
// Enable versioning on a new bucket.
//-
const metadata = {
  versioning: {
    enabled: true
  }
};

storage.createBucket('new-bucket', metadata, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.createBucket('new-bucket').then(function(data) {
  const bucket = data[0];
  const apiResponse = data[1];
});

include:samples/buckets.js

region_tag:storage_create_bucket
Another example:

Parameters

Name	Type	Optional	Description
name	string		Name of the bucket to create.
metadata	CreateBucketRequest	Yes	Metadata to set for the bucket.
callback	CreateBucketCallback	Yes	Callback function.

See also

Buckets: insert API Documentation

Storage Classes

Bucket#create

Throws

Error

If a name is not provided.

Returns

Promise containing CreateBucketResponse

getBuckets([query][, callback]) → Promise containing GetBucketsResponse

Get Bucket objects for all of the buckets in your project.

Examples

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
storage.getBuckets(function(err, buckets) {
  if (!err) {
    // buckets is an array of Bucket objects.
  }
});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
const callback = function(err, buckets, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    storage.getBuckets(nextQuery, callback);
  }

  // The `metadata` property is populated for you with the metadata at the
  // time of fetching.
  buckets[0].metadata;

  // However, in cases where you are concerned the metadata could have
  // changed, use the `getMetadata` method.
  buckets[0].getMetadata(function(err, metadata, apiResponse) {});
};

storage.getBuckets({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.getBuckets().then(function(data) {
  const buckets = data[0];
});

include:samples/buckets.js

region_tag:storage_list_buckets
Another example:

Parameters

Name	Type	Optional	Description
query	GetBucketsRequest	Yes	Query object for listing buckets.
callback	GetBucketsCallback	Yes	Callback function.

See also: Buckets: list API Documentation
Returns: Promise containing GetBucketsResponse

getServiceAccount([options][, callback]) → Promise containing GetServiceAccountResponse

Get the email address of this project's Google Cloud Storage service account.

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();

storage.getServiceAccount(function(err, serviceAccount, apiResponse) {
  if (!err) {
    const serviceAccountEmail = serviceAccount.emailAddress;
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.getServiceAccount().then(function(data) {
  const serviceAccountEmail = data[0].emailAddress;
  const apiResponse = data[1];
});

Parameters

Name Type Optional Description

options

object

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
userProject	string	Yes	User project to be billed for this request.

callback

GetServiceAccountCallback

Yes

Callback function.

See also: Projects.serviceAccount: get API Documentation; Projects.serviceAccount Resource
Returns: Promise containing GetServiceAccountResponse