Class Storage (5.17.0)

ACLs

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

To learn more about ACLs, read this overview on Access Control.

See Cloud Storage overview See Access Control

Inheritance

Service > Storage

Package

@google-cloud/storage

Constructors

(constructor)(options)

constructor(options?: StorageOptions);

Constructs the Storage client.

Parameter
Name Description
options StorageOptions

Configuration options.
Examples

Create a client that uses Application Default Credentials (ADC)


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

Create a client with explicit credentials


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

Properties

acl

acl: typeof Storage.acl;

Reference to .

Storage#acl

acl

static acl: {
        OWNER_ROLE: string;
        READER_ROLE: string;
        WRITER_ROLE: string;
    };

Bucket

static Bucket: typeof Bucket;

Bucket class.

Storage.Bucket

Channel

static Channel: typeof Channel;

Channel class.

Storage.Channel

File

static File: typeof File;

File class.

Storage.File

HmacKey

static HmacKey: typeof HmacKey;

HmacKey class.

Storage.HmacKey

retryOptions

retryOptions: RetryOptions;

Methods

bucket(name, options)

bucket(name: string, options?: BucketOptions): Bucket;

Get a reference to a Cloud Storage bucket.

Parameters
Name Description
name string

Name of the bucket.
options BucketOptions

Configuration object.
Returns
Type Description
Bucket

{Bucket}
Example 

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

channel(id, resourceId)

channel(id: string, resourceId: string): Channel;

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

Parameters
Name Description
id string

The ID of the channel.
resourceId string

The resource ID of the channel.
Returns
Type Description
Channel

{Channel}
Example 

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

createBucket(name, metadata)

createBucket(name: string, metadata?: CreateBucketRequest): Promise<CreateBucketResponse>;
Parameters
Name Description
name string
metadata CreateBucketRequest
Returns
Type Description
Promise<CreateBucketResponse>

createBucket(name, callback)

createBucket(name: string, callback: BucketCallback): void;
Parameters
Name Description
name string
callback BucketCallback
Returns
Type Description
void

createBucket(name, metadata, callback)

createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Parameters
Name Description
name string
metadata CreateBucketRequest
callback BucketCallback
Returns
Type Description
void

createBucket(name, metadata, callback)

createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Parameters
Name Description
name string
metadata CreateBucketRequest
callback BucketCallback
Returns
Type Description
void

createHmacKey(serviceAccountEmail, options)

createHmacKey(serviceAccountEmail: string, options?: CreateHmacKeyOptions): Promise<CreateHmacKeyResponse>;
Parameters
Name Description
serviceAccountEmail string
options CreateHmacKeyOptions
Returns
Type Description
Promise<CreateHmacKeyResponse>

createHmacKey(serviceAccountEmail, callback)

createHmacKey(serviceAccountEmail: string, callback: CreateHmacKeyCallback): void;
Parameters
Name Description
serviceAccountEmail string
callback CreateHmacKeyCallback
Returns
Type Description
void

createHmacKey(serviceAccountEmail, options, callback)

createHmacKey(serviceAccountEmail: string, options: CreateHmacKeyOptions, callback: CreateHmacKeyCallback): void;
Parameters
Name Description
serviceAccountEmail string
options CreateHmacKeyOptions
callback CreateHmacKeyCallback
Returns
Type Description
void

getBuckets(options)

getBuckets(options?: GetBucketsRequest): Promise<GetBucketsResponse>;
Parameter
Name Description
options GetBucketsRequest
Returns
Type Description
Promise<GetBucketsResponse>

getBuckets(options, callback)

getBuckets(options: GetBucketsRequest, callback: GetBucketsCallback): void;
Parameters
Name Description
options GetBucketsRequest
callback GetBucketsCallback
Returns
Type Description
void

getBuckets(callback)

getBuckets(callback: GetBucketsCallback): void;
Parameter
Name Description
callback GetBucketsCallback
Returns
Type Description
void

getBucketsStream()

getBucketsStream(): Readable;
Returns
Type Description
Readable

getHmacKeys(options)

getHmacKeys(options?: GetHmacKeysOptions): Promise<GetHmacKeysResponse>;

Retrieves a list of HMAC keys matching the criteria.

The authenticated user must have storage.hmacKeys.list permission for the project in which the key exists.

Parameter
Name Description
options GetHmacKeysOptions

Configuration options.
Returns
Type Description
Promise<GetHmacKeysResponse>
Example 

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

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

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

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

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

getHmacKeys(callback)

getHmacKeys(callback: GetHmacKeysCallback): void;
Parameter
Name Description
callback GetHmacKeysCallback
Returns
Type Description
void

getHmacKeys(options, callback)

getHmacKeys(options: GetHmacKeysOptions, callback: GetHmacKeysCallback): void;
Parameters
Name Description
options GetHmacKeysOptions
callback GetHmacKeysCallback
Returns
Type Description
void

getHmacKeysStream()

getHmacKeysStream(): Readable;
Returns
Type Description
Readable

getServiceAccount(options)

getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
Parameter
Name Description
options GetServiceAccountOptions
Returns
Type Description
Promise<GetServiceAccountResponse>

getServiceAccount(options)

getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
Parameter
Name Description
options GetServiceAccountOptions
Returns
Type Description
Promise<GetServiceAccountResponse>

getServiceAccount(options, callback)

getServiceAccount(options: GetServiceAccountOptions, callback: GetServiceAccountCallback): void;
Parameters
Name Description
options GetServiceAccountOptions
callback GetServiceAccountCallback
Returns
Type Description
void

getServiceAccount(callback)

getServiceAccount(callback: GetServiceAccountCallback): void;
Parameter
Name Description
callback GetServiceAccountCallback
Returns
Type Description
void

hmacKey(accessId, options)

hmacKey(accessId: string, options?: HmacKeyOptions): HmacKey;

Get a reference to an HmacKey object. Note: this does not fetch the HMAC key's metadata. Use HmacKey#get() to retrieve and populate the metadata.

To get a reference to an HMAC key that's not created for a service account in the same project used to instantiate the Storage client, supply the project's ID as projectId in the options argument.

Parameters
Name Description
accessId string

The HMAC key's access ID.
options HmacKeyOptions

HmacKey constructor owptions.
Returns
Type Description
HmacKey

{HmacKey}
Example 

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